AWS X-Ray 用の SDK Python

X-Ray SDK for Python は、トレースデータを生成して X-Ray デーモンに送信するためのクラスとメソッドを提供する Python Web アプリケーション用のライブラリです。トレースデータには、アプリケーションが処理した受信 HTTP リクエストに関する情報と、アプリケーションが AWS SDK、HTTP クライアント、または SQL データベースコネクタを使用してダウンストリームサービスに対して行う呼び出しに関する情報が含まれます。セグメントを手動で作成し、注釈およびメタデータにデバッグ情報を追加することもできます。

SDK は pip を使用してダウンロードできます。

$ pip install aws-xray-sdk

注記

X-Ray SDK for Python は、オープンソースプロジェクトです。github.com/aws/ でプロジェクトをフォローし、課題やプルリクエストを送信できます GitHub。aws-xray-sdk-python

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

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

注記

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

Lambda ワーカー Python でインストゥルメントされた関数の例については、を参照してください。

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

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

• botocore, boto3 — インストゥルメントクライアント。 AWS SDK for Python (Boto)

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

• aiobotocore、aioboto3 - 測定された asyncio統合バージョンの SDK for Python クライアント。

• requests、aiohttp - 測定された高レベルの HTTP クライアント。

• httplib、 http.client - 測定された低レベルの HTTP クライアントおよびそれらを使用する高レベルのライブラリ。

• sqlite3 - SQLite クライアントを測定します。

• mysql-connector-python - MySQL クライアントを測定します。

• pg8000 - Pure-Python PostgreSQL インターフェイスを測定します。

• psycopg2 - PostgreSQL データベースアダプターを測定します。

• pymongo - MongoDB クライアントを測定します。

• pymysql— PyMy MySQL および MariaDB 用の SQL ベースのクライアントをインストゥルメントします。

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

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

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

注釈とメタデータ

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

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

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

要件

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 以降

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