AWS X-Ray
開発者ガイド

Python 用 AWS X-Ray SDK

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 で問題とプルリクエストを送信できます。

Django または Flask を使用する場合は、アプリケーションに SDK ミドルウェアを追加し、受信リクエストをトレースします。ミドルウェアでは、トレース対象リクエストごとに「セグメント」を作成し、レスポンスが送信されるとセグメントを完了します。セグメントが開いている間、SDK クライアントのメソッドを使用してセグメントに情報を追加し、サブセグメントを作成してダウンストリーム呼び出しをトレースできます。また、SDK では、セグメントが開いている間にアプリケーションがスローする例外を自動的に記録します。他のアプリケーションの場合、手動でセグメントを作成することができます。

計測されたアプリケーションまたはサービスによって呼び出される Lambda 関数の場合、Lambda は トレースヘッダー を読み込み、サンプリングされたリクエストを自動的にトレースします。他の関数については、Lambda の設定 で受信リクエストのサンプルとトレースを行うことができます。いずれの場合も、Lambda はセグメントを作成し、X-Ray SDK に提供します。

注記

Lambda では、X-Ray SDK はオプションです。関数で使用しない場合、サービスマップには Lambda サービス用のノードと各 Lambda 関数用のノードが含まれます。SDK を追加すると、関数コードを計測して、Lambda によって記録された関数セグメントにサブセグメントを追加することができます。詳細については、「AWS Lambda および AWS X-Ray」を参照してください。

Lambda で実行されるサンプル Python 関数については、「ワーカー」を参照してください。

次に、X-Ray SDK for Python を使用してアプリケーションのライブラリにパッチを適用し、ダウンストリーム呼び出しを実装します。SDK は次のライブラリをサポートしています。

サポートされているライブラリ

  • botocoreboto3 – 実装された AWS SDK for Python (Boto) クライアント。

  • pynamodb – 実装された Amazon DynamoDB クライアントの PynamoDB のバージョン。

  • aiobotocoreaioboto3 – 実装された asyncio 統合バージョンの SDK for Python クライアント。

  • requestsaiohttp – 実装された高レベルの HTTP クライアント。

  • httplibhttp.client – 実装された低レベルの HTTP クライアントおよびそれらを使用する高レベルのライブラリ。

  • sqlite3 – 実装された SQLite クライアント。

  • mysql-connector-python – 実装された MySQL クライアント。

アプリケーションが AWS、SQL データベース、またはその他の HTTP サービスを呼び出すと、SDK は呼び出しに関する情報をサブセグメントに記録します。サービス内でアクセスする AWS のサービスとリソースは、サービスマップにダウンストリームノードとして表示され、個々の接続でエラーとスロットリングの問題を識別するのに役立ちます。

SDK を入手したら、レコーダーとミドルウェアを設定して、どの動作をカスタマイズします。プラグインを追加して、アプリケーションを実行しているコンピューティングリソースに関するデータを記録したり、サンプリングルールを定義することでサンプリングの動作のカスタマイズしたり、アプリケーションログに SDK からの情報をより多くあるいは少なく表示するようにログレベルを設定できます。

アプリケーションが注釈やメタデータで行うリクエストや作業に関する追加情報を記録します。注釈は、フィルタ式で使用するためにインデックス化されたシンプルなキーと値のペアで、特定のデータが含まれているトレースを検索できます。メタデータのエントリは制約が緩やかで、JSON にシリアル化することが可能なオブジェクトと配列全体を記録できます。

注釈とメタデータ

注釈とメタデータは、X-Ray SDK でセグメントに追加する任意のテキストです。注釈はフィルタ式用にインデックス付けされます。メタデータはインデックス付けされませんが、X-Ray コンソールまたは API の raw セグメントに表示されます。X-Ray への読み取りアクセスを付与されたユーザーはだれでも、このデータを表示できます。

コードに多数の計測されたクライアントがある場合、単一のリクエストセグメントには計測されたクライアントで行われた呼び出しごとに 1 個の多数のサブセグメントを含めることができます。カスタムサブセグメントで、クライアント呼び出しをラップすることで、サブセグメントを整理してグループできます。関数全体またはコードの任意のセクションに対して、カスタムサブセグメントを作成できます。親セグメントのすべてを書き込むのではなく、サブセグメントにメタデータと注釈を記録することができます。

SDK のクラスとメソッドのリファレンスドキュメントについては、『AWS X-Ray SDK for Python API リファレンス』を参照してください。

要件

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 ファイルに追加します。

例 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 にすべてのパッケージを自動的にインストールします。

このページの内容: