X-Ray SDK for Python の設定 - AWS X-Ray

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

X-Ray SDK for Python の設定

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

サービスプラグイン

pluginsを使用して、アプリケーションをホストしているサービスに関する情報を記録します。

プラグイン
  • Amazon EC2 —EC2Pluginは、インスタンス ID、アベイラビリティーゾーン、および CloudWatch Logs グループを追加します。

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

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


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

プラグインを使用するには、configurexray_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',) などです。

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

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

また、SDK はプラグインの設定を利用して、セグメントの origin フィールドを設定します。これは、アプリケーションを実行する AWS リソースのタイプを示します。複数のプラグインを使用する場合、SDK は次の解決順序を使用して起点を決定します。ElasticBeanStalk > EKS > ECS > EC2。

サンプリングルール

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

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

注記

SDK が X-Ray に到達してサンプリングルールを取得できない場合、1 秒ごとに最初のリクエストのデフォルトのローカルルールに戻り、ホストあたりの追加リクエストの 5% に戻ります。これは、ホストがサンプリング API を呼び出す権限を持っていない場合や、SDK によって行われる API 呼び出しの TCP プロキシとして機能する X-Ray デーモンに接続できない場合に発生します。

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 サービスによって管理されるのではなく、レコーダーの各インスタンスによって個別に適用されることです。より多くのホストをデプロイすると、固定レートが乗算され、記録されるデータ量の制御が難しくなります。

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

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

例 main.py - サンプリングを無効にする
xray_recorder.configure(sampling=False)

ログ記録

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

例 app.py - ログ記録
logging.basicConfig(level='WARNING') logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)

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

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

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

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

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

  • 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 – デーモンリスナーのホストとポートを設定します。

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

環境変数

環境変数を使用して、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を使用します。この変数は、デーモンを次のように構成している場合に使用します。別のポートでリッスンするまたは、別のホストで実行されている場合。

    [Format] (形式)
    • 同じポートaddress:port

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

  • AWS_XRAY_CONTEXT_MISSING – 計測されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外をスローするには、RUNTIME_ERROR に設定します。

    有効な値
    • RUNTIME_ERROR – ランタイム例外をスローします。

    • LOG_ERROR – エラーをログ記録して続行します (デフォルト)。

    • IGNORE_ERROR – エラーを無視して続行します。

    リクエストが開かれていないときに実行されるスタートアップコード、または新しいスレッドを生成するコードで測定されたクライアントを使用しようとしたときに発生する可能性があるセグメントまたはサブセグメントの欠落に関連するエラー。

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