AWS X-Ray SDK for Python
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 関数ごとに 1 つのノードが含まれます。SDK を追加することで、関数コードをインストルメントして、Lambda で記録された関数セグメントにサブセグメントを追加することができます。詳細については、「AWS Lambda および AWS X-Ray」を参照してください。
Lambda で実行されているサンプル Python 関数については、「ワーカー」を参照してください。
次に、X-Ray SDK for Python を使用してダウンストリーム呼び出しを実装するには、アプリケーションが使用するライブラリにパッチを適用します。SDK は次のライブラリをサポートしています。
サポートされているライブラリ
-
pynamodb
– 測定された Amazon DynamoDB クライアントの PynamoDB のバージョン。 -
aiobotocore
、aioboto3
- 測定された asyncio統合バージョンの SDK for Python クライアント。 -
httplib
、http.client
- 測定された低レベルの HTTP クライアントおよびそれらを使用する高レベルのライブラリ。 -
sqlite3
- SQLite クライアントを測定します。 -
mysql-connector-python
- MySQL クライアントを測定します。 -
pg8000
- Pure-Python PostgreSQL インターフェイスを測定します。 -
psycopg2
- PostgreSQL データベースアダプターを測定します。 -
pymongo
- MongoDB クライアントを測定します。 -
pymysql
- MySQL と MariaDB の測定された PyMySQL ベースのクライアント。
アプリケーションが 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
のパッケージをすべて自動的にインストールします。