翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 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` – エラーを無視して続行します。
リクエストが開かれていないときに実行されるスタートアップコード、または新しいスレッドを生成するコードで測定されたクライアントを使用しようとしたときに発生する可能性があるセグメントまたはサブセグメントの欠落に関連するエラー。
環境変数は、コードで設定される値を上書きします。