AWS X-Ray
開発者ガイド

X-Ray SDK for Python の設定

X-Ray SDK for Python には、グローバルレコーダーを提供する xray_recorder というクラスがあります。グローバルレコーダーを設定して、受信 HTTP 呼び出しのセグメントを作成するミドルウェアをカスタマイズできます。

サービスプラグイン

Use plugins to record information about the service hosting your application.

プラグイン

  • Amazon EC2 – EC2Plugin は、インスタンス ID とアベイラビリティーゾーンを追加します。

  • Elastic Beanstalk – ElasticBeanstalkPlugin は、環境名、バージョンラベル、およびデプロイ ID を追加します。

  • Amazon ECS – ECSPlugin は、コンテナ ID を追加します。


        Amazon EC2 および Elastic Beanstalk プラグインを使用してリソースデータをセグメント化します。

プラグインを使用するには、configurexray_recorder を呼び出します。

from aws_xray_sdk.core import xray_recorder from aws_xray_sdk.core import patch_all xray_recorder.configure(aws_xray_tracing_name='My app') plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin') xray_recorder.configure(plugins=plugins) patch_all()

また、コードで設定した値よりも優先される環境変数を使用して、レコーダーを設定することもできます。

ダウンストリームコールを記録するには、パッチライブラリの前にプラグインを設定します。

また、SDK は、プラグイン設定を使用して、セグメントの origin フィールドを設定します。これは、アプリケーションを実行する AWS リソースのタイプを示します。リソースタイプは、サービスマップでアプリケーション名の下に表示されます。たとえば、AWS::ElasticBeanstalk::Environment と表示されます。

リソースノードとリソースタイプ。

複数のプラグインを使用すると、SDK は最後にロードされたプラグインを使用してオリジンを判断します。

サンプリングルール

SDK では、X-Ray コンソールで定義したサンプリングルールに従って、記録するリクエストを決定します。デフォルトのルールでは、X-Ray にトレースを送信するすべてのサービスをまたいで 1 秒ごとに最初のリクエストと、追加リクエストの 5% をトレースします。アプリケーションごとに記録するデータの量をカスタマイズするには、X-Ray コンソールで追加のルールを作成します。

SDK は定義されている順にカスタムルールを適用します。リクエストが複数のカスタムルールに一致する場合、SDK は最初のルールのみを適用します。

注記

SDK は、X-Ray からサンプリングルールを取得できない場合、デフォルトのローカルルール (1 秒ごとに最初のリクエストと、追加リクエストの 5%) をホストごとに適用します。これが発生するのは、サンプリング API を呼び出す権限がホストにない場合、またはホストが X-Ray デーモンに接続できない場合です。このデーモンは、SDK が行う API コールに対して TCP プロキシとして機能します。

サンプリングルールを JSON ドキュメントからロードするように SDK を設定することもできます。SDK では、X-Ray サンプリングが使用できない場合にローカルルールをバックアップとして使用したり、専らローカルルールだけを使用したりできます。

例 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 サービスで管理されずに、レコーダーのインスタンスごとに適用されることです。ホストのデプロイ数が増えると、固定レートが増加し、記録するデータ量の制御が難しくなります。

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())

サンプリングを無効にしてすべての着信リクエストを計測するように、グローバルレコーダーを構成することもできます。

例 main.py– でサンプリングを無効にする

xray_recorder.configure(sampling=False)

のログ記録

SDK は、Python の組み込みの logging モジュールを使用します。aws_xray_sdk クラスのロガーへの参照を取得し、その上で setLevel を呼び出して、ライブラリとアプリケーションに別のログレベルを設定します。

例 app.py– ログ記録

logging.basicConfig(level='WARNING') logging.getLogger('aws_xray_sdk').setLevel(logging.DEBUG)

デバッグログを使用して問題を識別します。たとえば、「サブセグメントを手動で生成する」場合にサブセグメントが閉じない問題などです。

コード内のレコーダー設定

追加の設定は、xray_recorderconfigure メソッドから利用できます。

  • context_missing – 実装されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外のスローを回避するには、LOG_ERROR に設定します。

  • daemon_address – X-Ray デーモンリスナーのホストとポートを設定します。

  • service – SDK がセグメントに使用するサービス名を設定します。

  • plugins – アプリケーションの AWS リソースに関する情報を記録します。

  • samplingFalse に設定してサンプリングを無効にします。

  • sampling_rulesサンプリングルールを含む JSON ファイルのパスを設定します。

例 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 リソースに関する情報を記録します。

  • SAMPLINGFalse に設定してサンプリングを無効にします。

  • SAMPLING_RULESサンプリングルールを含む JSON ファイルのパスを設定します。

settings.py でレコーダ設定を有効にするには、インストールされているアプリのリストに Django ミドルウェアを追加します。

例 settings.py– インストールされたアプリ

INSTALLED_APPS = [ ... 'django.contrib.sessions', 'aws_xray_sdk.ext.django', ]

XRAY_RECORDER という名前の dict で利用可能な設定を行います。

例 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, }

Environment Variables

環境変数を使用して、X-Ray SDK for Python を設定できます。SDK は次の変数をサポートしています。

  • AWS_XRAY_TRACING_NAME – SDK がセグメントに使用するサービス名を設定します。サーブレットフィルタのセグメント命名ルールで設定したサービス名を上書きします。

  • AWS_XRAY_SDK_ENABLEDfalse に設定されている場合、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 を使用します。デーモンを別のポートでリッスンするように設定しているか、デーモンが別のホストで実行されている場合は、この変数を使用します。

    形式

    • 同じポートaddress:port

    • 異なるポートtcp:address:port udp:address:port

  • AWS_XRAY_CONTEXT_MISSING – Set to LOG_ERROR to avoid throwing exceptions when your instrumented code attempts to record data when no segment is open.

    Valid Values

    • RUNTIME_ERROR – Throw a runtime exception (default).

    • LOG_ERROR – Log an error and continue.

    Errors related to missing segments or subsegments can occur when you attempt to use an instrumented client in startup code that runs when no request is open, or in code that spawns a new thread.

環境変数は、コードで設定される値を上書きします。