翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS X-Ray SDK for Python
**注記**
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。
X-Ray SDK for Python は、Python ウェブアプリケーション用のライブラリです。トレースデータを作成し X-Ray デーモンに送信するためのクラスおよびメソッドを提供します。トレースデータには、アプリケーションによって提供される受信 HTTP リクエストに関する情報、およびアプリケーションが AWS SDK、HTTP クライアント、または SQL データベースコネクタを使用してダウンストリームサービスに対して行う呼び出しが含まれます。セグメントを手動で作成し、注釈およびメタデータにデバッグ情報を追加することもできます。
SDK は `pip` を使用してダウンロードできます。
```
$ pip install aws-xray-sdk
```
**注記**
X-Ray SDK for Python は、オープンソースプロジェクトです。プロジェクトに従って、GitHub [github.com/aws/aws-xray-sdk-python](https://github.com/aws/aws-xray-sdk-python) で問題とプルリクエストを送信できます。
Django または Flask を使用する場合は、[アプリケーションに SDK ミドルウェアを追加し](xray-sdk-python-middleware.md)、受信リクエストをトレースします。ミドルウェアでは、トレース対象リクエストごとに「[セグメント](xray-concepts.md#xray-concepts-segments)」を作成し、レスポンスが送信されるとセグメントを完了します。セグメントが開いている間、SDK クライアントのメソッドを使用してセグメントに情報を追加し、サブセグメントを作成してダウンストリーム呼び出しをトレースできます。また、SDK では、セグメントが開いている間にアプリケーションがスローする例外を自動的に記録します。他のアプリケーションの場合、[手動でセグメントを作成](xray-sdk-python-middleware.md#xray-sdk-python-middleware-manual)することができます。
測定されたアプリケーションまたはサービスから呼び出された Lambda 関数に対して、Lambda は [トレースヘッダー](xray-concepts.md#xray-concepts-tracingheader) を読み込み、サンプリングされたリクエストを自動的にトレースします。その他の関数については、[Lambda の設定](xray-services-lambda.md) から受信リクエストのサンプリングとトレースを行うことができます。いずれの場合も、Lambda はセグメントを作成し、X-Ray SDK に提供します。
**注記**
Lambda では、X-Ray SDK はオプションです。関数でこれを使用しない場合、サービスマップには Lambda サービスのノードと Lambda 関数ごとに 1 つのノードが含まれます。SDK を追加することで、関数コードをインストルメントして、Lambda で記録された関数セグメントにサブセグメントを追加することができます。詳細については「[AWS Lambda および AWS X-Ray](xray-services-lambda.md)」を参照してください。
Lambda で実行されているサンプル Python 関数については、「[ワーカー](scorekeep-lambda.md#scorekeep-lambda-worker)」を参照してください。
次に､X-Ray SDK for Python を使用してダウンストリーム呼び出しを実装するには、[アプリケーションが使用するライブラリにパッチを適用](xray-sdk-python-patching.md)します。SDK は次のライブラリをサポートしています。
**サポートされているライブラリ**
+ `[botocore](https://pypi.python.org/pypi/botocore)`、 `[boto3](https://pypi.python.org/pypi/boto3)` – 計測 AWS SDK for Python (Boto) クライアント。
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)` – 測定された Amazon DynamoDB クライアントの PynamoDB のバージョン。
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`、`[aioboto3](https://pypi.python.org/pypi/aioboto3)` - 測定された [asyncio](https://docs.python.org/3/library/asyncio.html)統合バージョンの SDK for Python クライアント。
+ `[requests](https://pypi.python.org/pypi/requests)`、`[aiohttp](https://pypi.python.org/pypi/aiohttp)` - 測定された高レベルの HTTP クライアント。
+ `[httplib](https://docs.python.org/2/library/httplib.html)`、[https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html) – 測定された低レベルの HTTP クライアントおよびそれらを使用する高レベルのライブラリ。
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)` - SQLite クライアントを測定します。
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)` - MySQL クライアントを測定します。
+ `[pg8000](https://pypi.org/project/pg8000/)` - Pure-Python PostgreSQL インターフェイスを測定します。
+ `[psycopg2](https://pypi.org/project/psycopg2/)` - PostgreSQL データベースアダプターを測定します。
+ `[pymongo](https://pypi.org/project/pymongo/)` - MongoDB クライアントを測定します。
+ `[pymysql](https://pypi.org/project/PyMySQL/)` - MySQL と MariaDB の測定された PyMySQL ベースのクライアント。
アプリケーションが AWS、SQL データベース、またはその他の HTTP サービスを呼び出すたびに、SDK は呼び出しに関する情報をサブセグメントに記録します。 AWS のサービス また、サービス内でアクセスするリソースは、トレースマップにダウンストリームノードとして表示され、個々の接続でエラーやスロットリングの問題を特定するのに役立ちます。
SDK を入手したら、[レコーダーとミドルウェアを設定](xray-sdk-python-configuration.md)して､その動作をカスタマイズします。プラグインを追加して、アプリケーションを実行しているコンピューティングリソースに関するデータを記録したり、サンプリングルールを定義することでサンプリングの動作をカスタマイズしたり、アプリケーションログに SDK からの情報をより多くあるいは少なく表示するようにログレベルを設定できます。
アプリケーションが[注釈やメタデータ](xray-sdk-python-segment.md)で行うリクエストや作業に関する追加情報を記録します。注釈は、[フィルタ式](xray-console-filters.md)で使用するためにインデックス化されたシンプルなキーと値のペアで、特定のデータが含まれているトレースを検索できます。メタデータのエントリは制約が緩やかで、JSON にシリアル化できるオブジェクトと配列全体を記録できます。
**注釈とメタデータ**
注釈およびメタデータとは、X-Ray SDK を使用してセグメントに追加する任意のテキストです。注釈は、フィルタ式用にインデックス付けされます。メタデータはインデックス化されませんが、X-Ray コンソールまたは API を使用して raw セグメントで表示できます。X-Ray への読み取りアクセスを許可した人は誰でも、このデータを表示できます。
コードに多数の計測されたクライアントがある場合、単一のリクエストセグメントには計測されたクライアントで行われた呼び出しごとに 1 個の多数のサブセグメントを含めることができます。[カスタムサブセグメント](xray-sdk-python-subsegments.md)で、クライアント呼び出しをラップすることで、サブセグメントを整理してグループできます。関数全体またはコードの任意のセクションに対して､カスタムサブセグメントを作成できます。親セグメントのすべてを書き込むのではなく、サブセグメントにメタデータと注釈を記録することができます。
SDK のクラスとメソッドのリファレンスドキュメントについては、[AWS X-Ray SDK for Python API リファレンス](https://docs.aws.amazon.com/xray-sdk-for-python/latest/reference)を参照してください。
## 要件
X-Ray SDK for Python では、次の言語とライブラリのバージョンがサポートされています。
+ **Python** – 2.7、3.4 以降
+ **Django** – 1.10 以降
+ **Flask** – 0.10 以降
+ **aiohttp** – 2.3.0 以降
+ **AWS SDK for Python (Boto)** - 1.4.0 以降
+ **botocore** – 1.5.0 以降
+ **enum** – 0.4.7 以降 (Python バージョン 3.4.0 以前)
+ **jsonpickle** – 1.0.0 以降
+ **setuptools** – 40.6.3 以降
+ **wrapt** – 1.11.0 以降
## 依存関係管理
X-Ray SDK for Python は、`pip`から入手できます。
+ **パッケージ** – `aws-xray-sdk`
1. SDK を依存関係として `requirements.txt` ファイルに追加します。
**Example requirements.txt**
```
aws-xray-sdk==2.4.2
boto3==1.4.4
botocore==1.5.55
Django==1.11.3
```
Elastic Beanstalk を使用してアプリケーションをデプロイする場合、Elastic Beanstalk は `requirements.txt` のパッケージをすべて自動的にインストールします。
# X-Ray SDK for Python の設定
**注記**
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日に、 AWS X-Ray SDKs/Daemon はメンテナンスモードに移行します。 AWS は、X-Ray SDK とデーモンのリリースをセキュリティ上の問題にのみ対処するように制限します。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。
X-Ray SDK for Python には、グローバルレコーダーを提供する `xray_recorder` というクラスがあります。グローバルレコーダーを設定して、受信 HTTP コールのセグメントを作成するミドルウェアをカスタマイズできます。
**Topics**
+ [サービスプラグイン](#xray-sdk-python-configuration-plugins)
+ [サンプリングルール](#xray-sdk-python-configuration-sampling)
+ [ログ記録](#xray-sdk-python-configuration-logging)
+ [コード内のレコーダー設定](#xray-sdk-python-middleware-configuration-code)
+ [Django でのレコーダー設定](#xray-sdk-python-middleware-configuration-django)
+ [環境変数](#xray-sdk-python-configuration-envvars)
## サービスプラグイン
`plugins`を使用して、アプリケーションをホストしているサービスに関する情報を記録します。
**プラグイン**
+ Amazon EC2 —`EC2Plugin`は、インスタンス ID、アベイラビリティーゾーン、および CloudWatch Logs グループを追加します。
+ ElasticBeanstalk– `ElasticBeanstalkPlugin`は、環境名、バージョンラベル、およびデプロイ ID を追加します。
+ Amazon ECS —`ECSPlugin`は、コンテナ ID を追加します。
![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png)
プラグインを使用するには、`configure` で `xray_recorder` を呼び出します。1 はタプルとして渡されるため、単一のプラグインを指定する場合は必ず末尾に 2 を付けてください。
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
xray_recorder.configure(service='My app')
plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin')
xray_recorder.configure(plugins=plugins)
patch_all()
```
**注記**
`plugins` はタプルとして渡されるため、単一のプラグインを指定する場合は必ず末尾に `,` を付けてください。例: `plugins = ('EC2Plugin',)`
また、コードで設定した値よりも優先される[環境変数](#xray-sdk-python-configuration-envvars)を使用して、レコーダーを設定することもできます。
ダウンストリームコールを記録するには、[パッチライブラリ](xray-sdk-python-patching.md)の前にプラグインを設定します。
また、SDK はプラグインの設定を利用して、セグメントの `origin` フィールドを設定します。これは、アプリケーションを実行する AWS リソースのタイプを示します。複数のプラグインを使用する場合、SDK は次の解決順序を使用して起点を決定します。ElasticBeanStalk > EKS > ECS > EC2。
## サンプリングルール
SDK は X-Ray コンソールで定義したサンプリングルールを使用し、記録するリクエストを決定します。デフォルトルールでは、最初のリクエストを毎秒トレースし、X-Ray にトレースを送信するすべてのサービスで追加のリクエストの 5% をトレースします。[X-Ray コンソールに追加のルールを作成する](xray-console-sampling.md)をクリックして、各アプリケーションで記録されるデータ量をカスタマイズします。
SDK は、定義された順序でカスタムルールを適用します。リクエストが複数のカスタムルールと一致する場合、SDK は最初のルールのみを適用します。
**注記**
SDK が X-Ray に到達してサンプリングルールを取得できない場合、1 秒ごとに最初のリクエストのデフォルトのローカルルールに戻り、ホストあたりの追加リクエストの 5% に戻ります。これは、ホストがサンプリング API を呼び出す権限を持っていない場合や、SDK によって行われる API 呼び出しの TCP プロキシとして機能する X-Ray デーモンに接続できない場合に発生します。
JSON ドキュメントからサンプリングルールをロードするように SDK を設定することもできます。SDK は、X-Ray サンプリングが利用できない場合のバックアップとしてローカルルールを使用することも、ローカルルールを排他的に使用することもできます。
**Example sampling-rules.json**
```
{
"version": 2,
"rules": [
{
"description": "Player moves.",
"host": "*",
"http_method": "*",
"url_path": "/api/move/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
```
この例では、1 つのカスタムルールとデフォルトルールを定義します。カスタムルールでは、5 パーセントのサンプリングレートが適用され、`/api/move/`以下のパスに対してトレースするリクエストの最小数はありません。デフォルトのルールでは、1秒ごとの最初のリクエストおよび追加リクエストの 10 パーセントをトレースします。
ルールをローカルで定義することの欠点は、固定ターゲットが X-Ray サービスによって管理されるのではなく、レコーダーの各インスタンスによって個別に適用されることです。より多くのホストをデプロイすると、固定レートが乗算され、記録されるデータ量の制御が難しくなります。
では AWS Lambda、サンプリングレートを変更することはできません。関数がインストルメント化されたサービスによって呼び出された場合、そのサービスによってサンプリングされたリクエストを生成した呼び出しは Lambda によって記録されます。アクティブなトレースが有効で、トレースヘッダーが存在しない場合、Lambda はサンプリングを決定します。
バックアップサンプリングルールを設定するには、次の例に示すように、`xray_recorder.configure` を呼び出します。*rules* は、ルールの辞書または JSON ファイルの絶対パスサンプリングルールです。
```
xray_recorder.configure(sampling_rules=rules)
```
ローカルルールのみを使用するには、`LocalSampler` でレコーダーを設定します。
```
from aws_xray_sdk.core.sampling.local.sampler import LocalSampler
xray_recorder.configure(sampler=LocalSampler())
```
サンプリングを無効にしてすべての着信リクエストを実装するように、グローバルレコーダーを設定することもできます。
**Example main.py - サンプリングを無効にする**
```
xray_recorder.configure(sampling=False)
```
## ログ記録
SDK は、Python の組み込み `logging` モジュールを使用し、`WARNING`デフォルトのログ記録レベルを使用します。`aws_xray_sdk` クラスのロガーへの参照を取得し、その上で `setLevel` を呼び出して、ライブラリとアプリケーションに別のログレベルを設定します。
**Example app.py - ログ記録**
```
logging.basicConfig(level='WARNING')
logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)
```
デバッグログを使用して問題を識別します。たとえば、「[サブセグメントを手動で生成する](xray-sdk-python-subsegments.md)」場合にサブセグメントが閉じない問題などです。
## コード内のレコーダー設定
追加の設定は、`xray_recorder` の `configure` メソッドから利用できます。
+ `context_missing` - 測定されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外のスローを回避するには、`LOG_ERROR` に設定します。
+ `daemon_address` – X-Ray デーモンリスナーのホストとポートを設定します。
+ `service` - SDK がセグメントに使用するサービス名を設定します。
+ `plugins` – アプリケーションの AWS リソースに関する情報を記録します。
+ `sampling` – `False` に設定してサンプリングを無効にします。
+ `sampling_rules` – [サンプリングルール](#xray-sdk-python-configuration-sampling)を含む JSON ファイルのパスを設定します。
**Example main.py - コンテキスト欠落例外を無効にする**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(context_missing='LOG_ERROR')
```
## Django でのレコーダー設定
Django フレームワークを使用している場合は、Django `settings.py` ファイルを使用してグローバルレコーダーのオプションを設定できます。
+ `AUTO_INSTRUMENT` (Django のみ) - 組み込みデータベースおよびテンプレートレンダリング操作のサブセグメントを記録します。
+ `AWS_XRAY_CONTEXT_MISSING` - `LOG_ERROR` に設定すると、セグメントを開いていないときに測定されたコードがデータを記録しようとしたときに例外が発生するのを防ぐことができます。
+ `AWS_XRAY_DAEMON_ADDRESS` – X-Ray デーモンリスナーのホストとポートを設定します。
+ `AWS_XRAY_TRACING_NAME` - SDK がセグメントに使用するサービス名を設定します。
+ `PLUGINS` – アプリケーションの AWS リソースに関する情報を記録します。
+ `SAMPLING` – `False` に設定してサンプリングを無効にします。
+ `SAMPLING_RULES` – [サンプリングルール](#xray-sdk-python-configuration-sampling)を含む JSON ファイルのパスを設定します。
`settings.py` でレコーダ設定を有効にするには、インストールされているアプリのリストに Django ミドルウェアを追加します。
**Example settings.py - インストールされたアプリ**
```
INSTALLED_APPS = [
...
'django.contrib.sessions',
'aws_xray_sdk.ext.django',
]
```
`XRAY_RECORDER` という名前の dict で利用可能な設定を行います。
**Example settings.py - インストールされたアプリ**
```
XRAY_RECORDER = {
'AUTO_INSTRUMENT': True,
'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR',
'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:5000',
'AWS_XRAY_TRACING_NAME': 'My application',
'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'),
'SAMPLING': False,
}
```
## 環境変数
環境変数を使用して、X-Ray SDK for Python を設定できます。SDK は次の変数をサポートしています。
+ `AWS_XRAY_TRACING_NAME` - SDK がセグメントに使用するサービス名を設定します。プログラムによって設定したサービス名を上書きします。
+ `AWS_XRAY_SDK_ENABLED` – `false`に設定されている場合、SDK は無効になります。デフォルトでは、環境変数が false に設定されている場合を除き、SDK は有効です。
+ 無効にすると、グローバルレコーダーによって、デーモンに送信されないダミーセグメントとサブセグメントが自動的に生成され、自動パッチ適用は無効になります。ミドルウェアはグローバルレコーダーのラッパーとして記述されています。ミドルウェアによるセグメントやサブセグメントの生成もすべて、ダミーセグメントおよびダミーサブセグメントになります。
+ `AWS_XRAY_SDK_ENABLED` の値を設定するには、環境変数を使用するか、`aws_xray_sdk` ライブラリの `global_sdk_config` オブジェクトと直接やり取りします。環境変数を設定すると、これらの通信は上書きされます。
+ `AWS_XRAY_DAEMON_ADDRESS` – X-Ray デーモンリスナーのホストとポートを設定します。デフォルトでは、SDK はトレースデータ (UDP) とサンプリング (TCP) の両方に`127.0.0.1:2000`を使用します。この変数は、デーモンを次のように構成している場合に使用します。[別のポートでリッスンする](xray-daemon-configuration.md)または、別のホストで実行されている場合。
**形式**
+ **同じポート** – `address:port`
+ **異なるポート** – `tcp:address:port udp:address:port`
+ `AWS_XRAY_CONTEXT_MISSING` – 計測されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外をスローするには、`RUNTIME_ERROR` に設定します。
**有効な値**
+ `RUNTIME_ERROR`— ランタイム例外をスローします。
+ `LOG_ERROR` – エラーをログ記録して続行します (デフォルト)。
+ `IGNORE_ERROR` – エラーを無視して続行します。
リクエストが開かれていないときに実行されるスタートアップコード、または新しいスレッドを生成するコードで測定されたクライアントを使用しようとしたときに発生する可能性があるセグメントまたはサブセグメントの欠落に関連するエラー。
環境変数は、コードで設定される値を上書きします。
# X-Ray SDK for Python ミドルウェアを使用して受信リクエストをトレースします。
**注記**
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。
ミドルウェアをアプリケーションに追加してセグメント名を設定すると、X-Ray SDK for Python はサンプリングされた要求ごとにセグメントを作成します。このセグメントには、時間、メソッド、HTTP リクエストの処理などが含まれます。追加の計測により、このセグメントでサブセグメントが作成されます。
X-Ray SDK for Python は、受信 HTTP リクエストを測定する次のミドルウェアをサポートしています。
+ Django
+ Flask
+ Bottle
**注記**
AWS Lambda 関数の場合、Lambda はサンプリングされたリクエストごとにセグメントを作成します。詳細については「[AWS Lambda および AWS X-Ray](xray-services-lambda.md)」を参照してください。
Lambda で測定されているサンプル Python 関数については、「[ワーカー](scorekeep-lambda.md#scorekeep-lambda-worker)」を参照してください。
他のフレームワークのスクリプトまたは Python アプリケーションの場合、[セグメントを手動で作成](#xray-sdk-python-middleware-manual)することができます。
各セグメントには、サービスマップ内のアプリケーションを識別する名前があります。セグメントの名前は静的に指定することも、受信リクエストのホストヘッダーに基づいて動的に名前を付けるように SDK を設定することもできます。動的ネーミングでは、リクエスト内のドメイン名に基づいてトレースをグループ化でき、名前が予想されるパターンと一致しない場合（たとえば、ホストヘッダーが偽造されている場合）、デフォルト名を適用できます。
**転送されたリクエスト**
ロードバランサーまたは他の仲介者がアプリケーションにリクエストを転送する場合、X-Ray は、クライアントの IP をIP パケットの送信元 IP からではなく、リクエストの`X-Forwarded-For`ヘッダーから取得します。転送されたリクエストについて記録されたクライアント IP は偽造される可能性があるため、信頼されるべきではありません。
リクエストが転送されると、それを示す追加フィールドが SDK によってセグメントに設定されます。セグメントのフィールド `x_forwarded_for` が `true` に設定されている場合、クライアント IP が HTTP リクエストの `X-Forwarded-For` ヘッダーから取得されます。
ミドルウェアは、次の情報が含まれる `http` ブロックを使用して、各受信リクエスト用にセグメントを作成します。
+ **HTTP メソッド** – GET、POST、PUT、DELETE、その他。
+ **クライアントアドレス** – リクエストを送信するクライアントの IP アドレス。
+ **レスポンスコード** – 完了したリクエストの HTTP レスポンスコード。
+ **タイミング** – 開始時間 (リクエストが受信された時間) および終了時間 (レスポンスが送信された時間)。
+ **ユーザーエージェント** — リクエストからの`user-agent`
+ **コンテンツの長さ** — レスポンスからの`content-length`
**Topics**
+ [アプリケーションにミドルウェアを追加する (Django)](#xray-sdk-python-adding-middleware-django)
+ [アプリケーションにミドルウェアを追加する (Flask)](#xray-sdk-python-adding-middleware-flask)
+ [アプリケーションにミドルウェアを追加する (Bottle)](#xray-sdk-python-adding-middleware-bottle)
+ [Python コードを手動で実装する](#xray-sdk-python-middleware-manual)
+ [セグメント命名ルールの設定](#xray-sdk-python-middleware-naming)
## アプリケーションにミドルウェアを追加する (Django)
ミドルウェアを `MIDDLEWARE` ファイルの `settings.py` リストに追加します。X-Ray ミドルウェアは、他のミドルウェアで失敗した要求が確実に記録されるように、`settings.py` ファイルの最初の行にする必要があります。
**Example settings.py - X-Ray SDK for Python ミドルウェア**
```
MIDDLEWARE = [
'aws_xray_sdk.ext.django.middleware.XRayMiddleware',
'django.middleware.security.SecurityMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.common.CommonMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
'django.middleware.clickjacking.XFrameOptionsMiddleware'
]
```
`settings.py` ファイルの `INSTALLED_APPS` リストに X-Ray SDK Django アプリを追加します。これにより、アプリの起動時にX-Ray レコーダーを設定できるようになります。
**Example settings.py - X-Ray SDK for Python Django アプリ**
```
INSTALLED_APPS = [
'aws_xray_sdk.ext.django',
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
]
```
使用する [`settings.py` ファイル](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django)にセグメント名を設定します。
**Example settings.py - セグメント名**
```
XRAY_RECORDER = {
'AWS_XRAY_TRACING_NAME': 'My application',
'PLUGINS': ('EC2Plugin',),
}
```
これは、X-Ray レコーダーに､デフォルトのサンプリングレートで Django アプリケーションが提供する要求をトレースするように指示します。[使用する Django 設定ファイルにレコーダーを設定](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django)して､カスタムサンプリングルールを適用するか、その他の設定を変更することができます。
**注記**
`plugins` はタプルとして渡されるため、単一のプラグインを指定する場合は必ず末尾に `,` を付けてください。例: `plugins = ('EC2Plugin',)`
## アプリケーションにミドルウェアを追加する (Flask)
Flask アプリケーションを計測するには、最初に `xray_recorder` にセグメント名を設定します。次に、`XRayMiddleware` 関数を使用して Flask アプリケーションをコードにパッチします。
**Example app.py**
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
app = Flask(__name__)
xray_recorder.configure(service='My application')
XRayMiddleware(app, xray_recorder)
```
これは、X-Ray レコーダーに､デフォルトのサンプリングレートで Flask アプリケーションが提供する要求をトレースするように指示します。[レコーダーをコードに設定](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code)して､カスタムサンプリングルールを適用するか、その他の設定を変更することができます。
## アプリケーションにミドルウェアを追加する (Bottle)
Bottle アプリケーションを計測するには、最初に `xray_recorder` にセグメント名を設定します。次に、`XRayMiddleware` 関数を使用して Bottle アプリケーションをコードにパッチします。
**Example app.py**
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.bottle.middleware import XRayMiddleware
app = Bottle()
xray_recorder.configure(service='fallback_name', dynamic_naming='My application')
app.install(XRayMiddleware(xray_recorder))
```
これは、X-Ray レコーダーに､デフォルトのサンプリングレートで Bottle アプリケーションが提供する要求をトレースするように指示します。[レコーダーをコードに設定](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code)して､カスタムサンプリングルールを適用するか、その他の設定を変更することができます。
## Python コードを手動で実装する
Django または Flask を使用していない場合、手動でセグメントを作成することができます。受信リクエストごとにセグメントを作成するか、パッチが適用された HTTP または AWS SDK クライアントの周囲にセグメントを作成して、レコーダーがサブセグメントを追加するためのコンテキストを提供できます。
**Example main.py - 手動測定**
```
from aws_xray_sdk.core import xray_recorder
# Start a segment
segment = xray_recorder.begin_segment('segment_name')
# Start a subsegment
subsegment = xray_recorder.begin_subsegment('subsegment_name')
# Add metadata and annotations
segment.put_metadata('key', dict, 'namespace')
subsegment.put_annotation('key', 'value')
# Close the subsegment and segment
xray_recorder.end_subsegment()
xray_recorder.end_segment()
```
## セグメント命名ルールの設定
AWS X-Ray は*サービス名*を使用してアプリケーションを識別し、アプリケーションが使用する他のアプリケーション、データベース、外部 APIs、 AWS リソースと区別します。X-Ray SDK が受信リクエストのセグメントを生成すると、アプリケーションのサービス名がセグメントの[名前フィールド](xray-api-segmentdocuments.md#api-segmentdocuments-fields)に記録されます。
X-Ray SDK では、HTTP リクエストヘッダーのホスト名の後にセグメントの名前を指定できます。ただし、このヘッダーは偽造され、サービスマップに予期しないノードが発生する可能性があります。偽造されたホストヘッダーを持つリクエストによって SDK がセグメントの名前を間違えないようにするには、受信リクエストのデフォルト名を指定する必要があります。
アプリケーションが複数のドメインのリクエストを処理する場合、動的ネーミングストラテジーを使用してセグメント名にこれを反映するように SDK を設定できます。動的ネーミングストラテジーにより、SDK は予想されるパターンに一致するリクエストにホスト名を使用し、そうでないリクエストにデフォルト名を適用できます。
たとえば、3 つのサブドメイン（`www.example.com`,`api.example.com`,および`static.example.com`）に対してリクエストを処理する単一のアプリケーションがあるとします。動的ネーミングストラテジーをパターン `*.example.com` で使用して、異なる名前を持つ各サブドメインのセグメントを識別することができます。結果的にはサービスマップ上に 3 つのサービスノードを作成することになります。アプリケーションがパターンと一致しないホスト名のリクエストを受信すると、指定したフォールバック名を持つ 4 番目のノードがサービスマップに表示されます。
すべてのリクエストセグメントに同じ名前を使用するには、[前のセクション](#xray-sdk-python-adding-middleware-django)で示されたように、レコーダーを設定するときにアプリケーションの名前を指定します｡
動的命名ルールは、ホスト名と一致するようパターンを定義し、HTTP リクエストのホスト名がパターンと一致しない場合はデフォルトの名前を使用します。Django でセグメントに動的な名前を付けるには、`DYNAMIC_NAMING` 設定を使用する [settings.py](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django) ファイルに追加します｡
**Example settings.py - 動的ネーミング**
```
XRAY_RECORDER = {
'AUTO_INSTRUMENT': True,
'AWS_XRAY_TRACING_NAME': 'My application',
'DYNAMIC_NAMING': '*.example.com',
'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin')
}
```
パターン内で任意の文字列に一致させるには「\$1」を､また、任意の 1 文字に一致させるには「?」を使用することができます。Flask の場合は、[コードでレコーダーを設定します](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code)。
**Example main.py - セグメント名**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='My application')
xray_recorder.configure(dynamic_naming='*.example.com')
```
**注記**
コードで定義したデフォルトのサービス名は、`AWS_XRAY_TRACING_NAME` [環境変数](xray-sdk-python-configuration.md#xray-sdk-python-configuration-envvars)で上書きできます。
# ダウンストリームコールを実装するためのライブラリへのパッチ適用
**注記**
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。
ダウンストリーム呼び出しを測定するには、X-Ray SDK for Python を使用して、アプリケーションが使用するライブラリにパッチを適用します。X-Ray SDK for Python では、以下のライブラリにパッチを適用できます。
**サポートされているライブラリ**
+ `[botocore](https://pypi.python.org/pypi/botocore)`、 `[boto3](https://pypi.python.org/pypi/boto3)` – 計測 AWS SDK for Python (Boto) クライアント。
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)` – 測定された Amazon DynamoDB クライアントの PynamoDB のバージョン。
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`、`[aioboto3](https://pypi.python.org/pypi/aioboto3)` - 測定された [asyncio](https://docs.python.org/3/library/asyncio.html)統合バージョンの SDK for Python クライアント。
+ `[requests](https://pypi.python.org/pypi/requests)`、`[aiohttp](https://pypi.python.org/pypi/aiohttp)` - 測定された高レベルの HTTP クライアント。
+ `[httplib](https://docs.python.org/2/library/httplib.html)`、[https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html) – 測定された低レベルの HTTP クライアントおよびそれらを使用する高レベルのライブラリ。
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)` - SQLite クライアントを測定します。
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)` - MySQL クライアントを測定します。
+ `[pg8000](https://pypi.org/project/pg8000/)` - Pure-Python PostgreSQL インターフェイスを測定します。
+ `[psycopg2](https://pypi.org/project/psycopg2/)` - PostgreSQL データベースアダプターを測定します。
+ `[pymongo](https://pypi.org/project/pymongo/)` - MongoDB クライアントを測定します。
+ `[pymysql](https://pypi.org/project/PyMySQL/)` - MySQL と MariaDB 用 PyMySQL ベースクライアントを測定します。
パッチ適用されたライブラリを使用すると、X-Ray SDK for Python は呼び出しのサブセグメントが作成され、リクエストとレスポンスの情報を記録します。SDK ミドルウェアまたは AWS Lambdaのいずれかから、サブセグメントを作成するためにSDK でセグメントを使用できる必要があります。
**注記**
SQLAlchemy ORM を使用する場合は、SQLAlchemy のセッションクラスとクエリクラスの SDK のバージョンをインポートして、SQL クエリを追加できます。手順については、[Use SQLAlchemy ORM](https://github.com/aws/aws-xray-sdk-python/blob/master/README.md#use-sqlalchemy-orm) を参照してください。
使用可能なすべてのライブラリにパッチを適用するには、`aws_xray_sdk.core` の `patch_all` 関数を使用します。`httplib` や `urllib` などの一部のライブラリでは、`patch_all(double_patch=True)` を呼び出して二重パッチ適用を有効にすることが必要な場合があります。
**Example main.py - サポートされているすべてのライブラリにパッチを適用**
```
import boto3
import botocore
import requests
import sqlite3
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all()
```
単一のライブラリにパッチを適用するには、ライブラリ名のタプルを使用して `patch` を呼び出します。これを行うには、単一の要素リストを用意する必要があります。
**Example main.py - 特定のライブラリにパッチを適用**
```
import boto3
import botocore
import requests
import mysql-connector-python
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch
libraries = (['botocore'])
patch(libraries)
```
**注記**
場合によっては、ライブラリにパッチを適用するために使用するキーがライブラリ名と一致しない場合があります。一部のキーは、1 つまたは複数のライブラリのエイリアスとして機能します。
`httplib` – `[httplib](https://docs.python.org/2/library/httplib.html)` および [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html)
`mysql` – `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`
## 非同期作業のコンテキストのトレース
`asyncio` によって統合されたライブラリの場合や、[非同期関数用のサブセグメントを作成](xray-sdk-python-subsegments.md)する場合は、非同期コンテキストで X-Ray SDK for Python も設定する必要があります。`AsyncContext` クラスをインポートし、そのインスタンスを X-Ray レコーダーに渡します。
**注記**
ウェブフレームワークサポートライブラリ (例: AIOHTTP) は、`aws_xray_sdk.core.patcher` モジュールで処理することはできません。これらのライブラリは、サポートされているライブラリの `patcher` カタログに表示されません。
**Example main.py - aioboto3 にパッチを適用**
```
import asyncio
import aioboto3
import requests
from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())
from aws_xray_sdk.core import patch
libraries = (['aioboto3'])
patch(libraries)
```
# X-Ray AWS SDK for Python を使用した SDK 呼び出しのトレース
**注記**
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。
アプリケーションが AWS のサービス を呼び出してデータの保存、キューへの書き込み、または通知の送信を行うと、X-Ray SDK for Python は[サブセグメントのダウンストリームの呼び出しを追跡します](xray-sdk-python-subsegments.md)。これらのサービス内でアクセスするトレースされた AWS のサービス およびリソース (Amazon S3 バケットや Amazon SQS キューなど) は、X-Ray コンソールのトレースマップにダウンストリームノードとして表示されます。
X-Ray SDK for Python は、ライブラリにパッチを適用すると、すべての AWS SDK クライアントを自動的に計測します。 [`botocore`](xray-sdk-python-patching.md)個々のクライアントを実装することはできません。
すべてのサービスにおいて、X-Ray コンソールでコールされた API の名前を確認できます。サービスのサブセットの場合、X-Ray SDK はセグメントに情報を追加して、サービスマップでより細かく指定します。
たとえば、実装された DynamoDB クライアントでコールすると、SDK はテーブルをターゲットとするコールのセグメントにテーブル名を追加します。コンソールで、各テーブルはサービスマップ内に個別のノードとして表示され、テーブルをターゲットにしないコール用の汎用の DynamoDB ノードが表示されます。
**Example 項目を保存するための DynamoDB に対するコールのサブセグメント**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
名前付きリソースにアクセスしたとき、次のサービスをコールすると、サービスマップに追加のノードが作成されます。特定のリソースをターゲットとしないコールでは、サービスの汎用ノードが作成されます。
+ **Amazon DynamoDB** – テーブル名
+ **Amazon Simple Storage Service** – バケットとキー名
+ **Amazon Simple Queue Service** – キュー名
# X-Ray SDK for Python を使用してダウンストリーム HTTP ウェブサービスの呼び出しをトレースする
**注記**
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。
アプリケーションがマイクロサービスまたはパブリック HTTP API に呼び出しを実行する場合に、X-Ray SDK for Python を使用してこれらの呼び出しを計測し、API をダウンストリームサービスとしてサービスグラフに追加できます。
HTTP クライアントを設定するには、送信呼び出しに使用する[ライブラリにパッチを適用](xray-sdk-python-patching.md)します。`requests` や Python で実装されている HTTP クライアントを使っている場合は、必要な作業はこれだけです。`aiohttp` の場合は、[非同期コンテキスト](xray-sdk-python-patching.md#xray-sdk-python-patching-async)を使用してレコーダーも設定します。
`aiohttp` 3 のクライアント API を使用する場合は、SDK で提供されるトレース設定のインスタンスを使用して、`ClientSession` を設定する必要もあります。
**Example [`aiohttp` 3 クライアント API](https://github.com/aws/aws-xray-sdk-python#trace-aiohttp-client-requests)**
```
from aws_xray_sdk.ext.aiohttp.client import aws_xray_trace_config
async def foo():
trace_config = aws_xray_trace_config()
async with ClientSession(loop=loop, trace_configs=[trace_config]) as session:
async with session.get(url) as resp
await resp.read()
```
ダウンストリームウェブ API に対する呼び出しを計測すると、X-Ray SDK for Python は HTTP リクエストおよびレスポンスに関する情報を含むセグメントを記録します。X-Ray はサブセグメントを使用してリモート API の推測セグメントを生成します。
**Example ダウンストリーム HTTP 呼び出しのサブセグメント**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example ダウンストリーム HTTP 呼び出しの推定セグメント**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# X-Ray SDK for Python を使用したカスタムサブセグメントの生成
**注記**
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。
サブセグメントはリクエストを処理するために行われた作業の詳細を含んだトレースの[セグメント](xray-concepts.md#xray-concepts-segments)を拡張します。計測済みクライアント内で呼び出しを行うたびに、X-Ray SDK によってサブセグメントに生成された情報が記録されます。追加のサブセグメントを作成して、他のサブセグメントをグループ化したり、コードセクションのパフォーマンスを測定したり、注釈とメタデータを記録したりできます。
サブセグメントを管理するには、`begin_subsegment` および `end_subsegment` メソッドを使用します。
**Example main.py - カスタムサブセグメント**
```
from aws_xray_sdk.core import xray_recorder
subsegment = xray_recorder.begin_subsegment('annotations')
subsegment.put_annotation('id', 12345)
xray_recorder.end_subsegment()
```
同期関数のサブセグメントを作成するには、`@xray_recorder.capture` デコレータを使用します。サブセグメントの名前をキャプチャ関数に渡すことも、関数名を使用することもできます。
**Example main.py - 関数サブセグメント**
```
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('## create_user')
def create_user():
...
```
非同期関数の場合、`@xray_recorder.capture_async` デコレータを使用し、非同期コンテキストをレコーダーに渡します。
**Example main.py - 非同期関数サブセグメント**
```
from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())
@xray_recorder.capture_async('## create_user')
async def create_user():
...
async def main():
await myfunc()
```
セグメントまたは別のサブセグメント内にサブセグメントを作成する場合、X-Ray SDK for Python によってその ID が生成され、開始時刻と終了時刻が記録されます。
**Example サブセグメントとメタデータ**
```
"subsegments": [{
"id": "6f1605cd8a07cb70",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "Custom subsegment for UserModel.saveUser function",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
```
# X-Ray SDK for Python を使用してセグメントに注釈とメタデータを追加する
**注記**
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。
リクエスト、環境、または注釈やメタデータを使用するアプリケーションに関する追加情報を記録できます。X-Ray SDK が作成するセグメントまたは作成するカスタムサブセグメントに、注釈およびメタデータを追加できます。
**注釈**は文字列、数値、またはブール値を使用したキーと値のペアです。注釈は、[フィルタ式](xray-console-filters.md)用にインデックス付けされます。注釈を使用して、コンソールでトレースをグループ化するため、または[https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API を呼び出すときに使用するデータを記録します。
**メタデータ**は、オブジェクトとリストを含む、任意のタイプの値を持つことができるキーバリューのペアですが、フィルタ式に使用するためにインデックスは作成されません。メタデータを使用してトレースに保存する追加のデータを記録しますが、検索で使用する必要はありません。
注釈とメタデータに加えて、セグメントに[ユーザー ID 文字列を記録](#xray-sdk-python-segment-userid)することもできます。ユーザー ID はセグメントの個別のフィールドに記録され、検索用にインデックスが作成されます。
**Topics**
+ [X-Ray SDK for Python で注釈を記録する](#xray-sdk-python-segment-annotations)
+ [X-Ray SDK for Python でメタデータを記録する](#xray-sdk-python-segment-metadata)
+ [X-Ray SDK for Python でユーザー ID を記録する](#xray-sdk-python-segment-userid)
## X-Ray SDK for Python で注釈を記録する
注釈を使用して、検索用にインデックスを作成するセグメントまたはサブセグメントに情報を記録します。
**注釈の要件**
+ **キー** – X-Ray 注釈のキーには最大 500 文字の英数字を使用できます。スペースまたはドットやピリオド (.) 以外の記号は使用できません。
+ **値** – X-Ray 注釈の値には最大 1,000 の Unicode 文字を使用できます。
+ **注釈**の数 – トレースごとに最大 50 の注釈を使用できます。
**注釈を記録するには**
1. `xray_recorder` から現在のセグメントまたはサブセグメントの参照を取得します。
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
または
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. 文字列キー、および、ブール値、数値、文字列値を使用して `put_annotation` を呼び出します。
```
document.put_annotation("mykey", "my value");
```
次の例は、ドット、ブール値、数値、または文字列値を含む文字列キーを使用して `putAnnotation` を呼び出す方法を示しています。
```
document.putAnnotation("testkey.test", "my value");
```
または、`put_annotation` メソッドを `xray_recorder` で使用できます。このメソッドは、現在のサブセグメントの注釈を記録します。サブセグメントが開いていない場合は、セグメントの注釈を記録します。
```
xray_recorder.put_annotation("mykey", "my value");
```
SDK は、セグメントドキュメントの `annotations` オブジェクトにキーと値のペアとして、注釈を記録します。同じキーで `put_annotation` を 2 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。
特定の値を持つ注釈のあるトレースを見つけるには、`annotation[key]`フィルタ式[の ](xray-console-filters.md) キーワードを使用します。
## X-Ray SDK for Python でメタデータを記録する
**警告**
X-Ray SDK for Python では、循環参照を持つオブジェクトをメタデータ値として追加しないでください。これらのオブジェクトは JSON にシリアル化できず、SDK で無限ループを作成する可能性があります。また、パフォーマンスの問題を防ぐために、複雑で大規模なオブジェクトをメタデータとして追加することは避けてください。
メタデータを使用して、検索用にインデックスを作成する必要のないセグメントまたはサブセグメントに情報を記録します。メタデータ値は、文字列、数値、ブール値、または JSON オブジェクトや JSON 配列にシリアル化できる任意のオブジェクトになります。
**メタデータを記録するには**
1. `xray_recorder` から現在のセグメントまたはサブセグメントの参照を取得します。
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
または
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. 文字列キー、ブール値、数値、文字列値、オブジェクト値、文字列名前空間を使用して `put_metadata` を呼び出します。
```
document.put_metadata("my key", "my value", "my namespace");
```
または
キーと値だけを使用して `put_metadata` を呼び出します。
```
document.put_metadata("my key", "my value");
```
または、`put_metadata` メソッドを `xray_recorder` で使用できます。このメソッドは、現在のサブセグメントのメタデータを記録します。サブセグメントが開いていない場合は、セグメントのメタデータを記録します。
```
xray_recorder.put_metadata("my key", "my value");
```
名前空間を指定しない場合、SDK は `default` を使用します。同じキーで `put_metadata` を 2 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。
## X-Ray SDK for Python でユーザー ID を記録する
リクエストセグメントにユーザー ID を記録して、リクエストを送信したユーザーを識別します。
**ユーザー ID を記録するには**
1. `xray_recorder` から現在のセグメントへの参照を取得します。
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
1. リクエストを送信したユーザーの文字列 ID を使用して `setUser` を呼び出します。
```
document.set_user("U12345");
```
コントローラーで `set_user` を呼び出し、アプリケーションがリクエストの処理を開始するとすぐに、ユーザー ID を記録できます。
ユーザー ID のトレースを見つけるには、`user`フィルタ式[で、](xray-console-filters.md) キーワードを使用します。
# サーバーレス環境にデプロイされたウェブフレームワークの計測
**注記**
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。
AWS X-Ray SDK for Python は、サーバーレスアプリケーションにデプロイされたウェブフレームワークの計測をサポートしています。サーバーレスはクラウドのネイティブアーキテクチャで、運用上の多くの責任を AWSにシフトさせることができるため、俊敏性とイノベーションを強化できます。
サーバーレスアーキテクチャは、サーバーを意識せずにアプリケーションやサービスを構築および実行できるソフトウェアアプリケーションモデルです。サーバーまたはクラスターのプロビジョニング、パッチ適用、オペレーティングシステムのメンテナンス、キャパシティのプロビジョニングといったインフラストラクチャ管理のタスクが不要になります。サーバーレスアプリケーションは、ほぼすべてのタイプのアプリケーションやバックエンドサービス向けに構築でき、高可用性を実現しながら、アプリケーションの実行やスケーリングに必要な作業のすべてをユーザーに代わって行います。
このチュートリアルでは、サーバーレス環境にデプロイされた Flask や Django などのウェブフレームワーク AWS X-Ray で を自動的に計測する方法について説明します。アプリケーションの X-Ray 計測により、 AWS Lambda Amazon API Gateway から関数を介して行われたすべてのダウンストリーム呼び出しと、アプリケーションが行う発信呼び出しを表示できます。
X-Ray SDK for Python では、次の Python アプリケーションフレームワークをサポートしています。
+ Flask バージョン 0.8 以降
+ Django バージョン 1.0 以降
このチュートリアルでは、Lambda にデプロイされ、API Gateway から呼び出されるサーバーレスアプリケーションのサンプルを作成します。このチュートリアルでは、Zappa を使用して、アプリケーションを Lambda に自動的にデプロイし、API Gateway のエンドポイントを設定します。
## 前提条件
+ [Zappa](https://github.com/Miserlou/Zappa)
+ [Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python.html) – バージョン 2.7 または 3.6。
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) – AWS CLI が、アプリケーションをデプロイする アカウントと AWS リージョン で設定されていることを確認します。
+ [Pip](https://pypi.org/project/pip/)
+ [Virtualenv](https://virtualenv.pypa.io/en/latest/)
## ステップ 1: 環境を作成する
このステップでは、`virtualenv` を使用して仮想環境を作成し、アプリケーションをホスティングします。
1. を使用して AWS CLI、アプリケーションのディレクトリを作成します。その新しいディレクトリに変更します。
```
mkdir serverless_application
cd serverless_application
```
1. 次に、新しいディレクトリ内に仮想環境を作成します。アクティベートするには以下のコマンドを使用します。
```
# Create our virtual environment
virtualenv serverless_env
# Activate it
source serverless_env/bin/activate
```
1. X-Ray、Flask、Zappa およびリクエストライブラリをその環境にインストールします。
```
# Install X-Ray, Flask, Zappa, and Requests into your environment
pip install aws-xray-sdk flask zappa requests
```
1. アプリケーションコードを `serverless_application` ディレクトリに追加します。この例では、Flasks の [Hello World](https://flask.palletsprojects.com/en/3.0.x/quickstart/) の例を基にします。
`serverless_application` ディレクトリに `my_app.py` という名前のファイルを作成します。テキストエディタで、次のコマンドを追加します。このアプリケーションでは、リクエストライブラリを計測し、Flask アプリケーションのミドルウェアにパッチを適用して、エンドポイント `'/'` を開きます。
```
# Import the X-Ray modules
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
from aws_xray_sdk.core import patcher, xray_recorder
from flask import Flask
import requests
# Patch the requests module to enable automatic instrumentation
patcher.patch(('requests',))
app = Flask(__name__)
# Configure the X-Ray recorder to generate segments with our service name
xray_recorder.configure(service='My First Serverless App')
# Instrument the Flask application
XRayMiddleware(app, xray_recorder)
@app.route('/')
def hello_world():
resp = requests.get("https://aws.amazon.com")
return 'Hello, World: %s' % resp.url
```
## ステップ 2: Zappa 環境の作成とデプロイ
このステップでは、Zappa を使用して API Gateway のエンドポイントを自動的に設定し、Lambda にデプロイします。
1. `serverless_application` ディレクトリ内から Zappa を初期化します。この例では、デフォルト設定を使用しましたが、カスタマイズ設定がある場合は Zappa に設定手順が表示されます。
```
zappa init
```
```
What do you want to call this environment (default 'dev'): dev
...
What do you want to call your bucket? (default 'zappa-*******'): zappa-*******
...
...
It looks like this is a Flask application.
What's the modular path to your app's function?
This will likely be something like 'your_module.app'.
We discovered: my_app.app
Where is your app's function? (default 'my_app.app'): my_app.app
...
Would you like to deploy this application globally? (default 'n') [y/n/(p)rimary]: n
```
1. X-Ray を有効にします。`zappa_settings.json` ファイルを開き、例のように表示されていることを確認します。
```
{
"dev": {
"app_function": "my_app.app",
"aws_region": "us-west-2",
"profile_name": "default",
"project_name": "serverless-exam",
"runtime": "python2.7",
"s3_bucket": "zappa-*********"
}
}
```
1. 設定ファイルのエントリとして `"xray_tracing": true` を追加します。
```
{
"dev": {
"app_function": "my_app.app",
"aws_region": "us-west-2",
"profile_name": "default",
"project_name": "serverless-exam",
"runtime": "python2.7",
"s3_bucket": "zappa-*********",
"xray_tracing": true
}
}
```
1. アプリケーションをデプロイします。これにより、API Gateway エンドポイントが設定され、コードは Lambda に更新されます。
```
zappa deploy
```
```
...
Deploying API Gateway..
Deployment complete!: https://**********.execute-api.us-west-2.amazonaws.com/dev
```
## ステップ 3: API Gateway 用 X-Ray トレースを有効にする
このステップでは、API Gateway コンソールを使用して、X-Ray トレースを有効にします。
1. にサインイン AWS マネジメントコンソール し、[https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/) で API Gateway コンソールを開きます。
1. 新しく生成された API を探します。`serverless-exam-dev` のようになります。
1. **[Stages]** (ステージ) を選択します。
1. API のデプロイステージの名前を選択します。デフォルトは `dev` です。
1. [**Logs/Tracing**] タブで、[**X-Ray トレースを有効にする**] チェックボックスをオンにします。
1. **[Save changes]** (変更の保存) をクリックします。
1. ブラウザでエンドポイントにアクセスします。サンプルの `Hello World` アプリケーションを使用した場合は、次のように表示されます。
```
"Hello, World: https://aws.amazon.com/"
```
## ステップ 4: 作成したトレースを表示する
このステップでは、X-Ray コンソールを使用して、サンプルアプリケーションで作成されたトレースを表示します。トレース解析の詳細なチュートリアルについては、「[サービスマップの表示](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap)」を参照してください。
1. にサインイン AWS マネジメントコンソール し、[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) で X-Ray コンソールを開きます。
1. API Gateway、Lambda 関数、Lambda コンテナによって生成されたセグメントを表示します。
1. Lambda 関数のセグメントで、`My First Serverless App` という名前のサブセグメントを表示します。次に、`https://aws.amazon.com` という名前の 2 番目のサグメントが続きます。
1. Lambda では、初期化中に `initialization` という名前の 3 番目のサブセグメントが生成されることがあります。
![\[トレースセグメントビュー\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/serverless-traceView.png)
![\[サービスグラフビュー\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/serverless-serviceView.png)
## ステップ 5：クリーンアップ
不要なコストがかからないように、使用しなくなったリソースは必ず終了してください。このチュートリアルで示されているように、Zappa のようなツールを使用することで、サーバーレスの再デプロイを効率化することができます。
Lambda、API Gateway、Amazon S3 からアプリケーションを削除するには、 AWS CLIを使用して、プロジェクトディレクトリで次のコマンドを実行します。
```
zappa undeploy dev
```
## 次の手順
AWS クライアントを追加して X-Ray で計測することで、アプリケーションに機能を追加します。サーバーレスコンピューティングのオプションについては、[AWSのサーバーレス](https://aws.amazon.com/serverless)を参照してください。