AWS X-Ray
開発者ガイド

X-Ray SDK for Python ミドルウェアを使用して受信リクエストをトレースする

Django または Flask を使用している場合、Django ミドルウェアまたは Flask ミドルウェアを入力して、着信 HTTP リクエストを計測します。ミドルウェアをアプリケーションに追加してセグメント名を設定すると、X-Ray SDK for Python はサンプリングされた要求ごとにセグメントを作成します。このセグメントには、時間、メソッド、HTTP リクエストの処理などが含まれます。追加の計測により、このセグメントでサブセグメントが作成されます。

注記

AWS Lambda 関数の場合、Lambda はサンプリングされたリクエストごとにセグメントを作成します。詳細については、「AWS Lambda および AWS X-Ray」を参照してください。

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

他のフレームワークのスクリプトまたは Python アプリケーションの場合、セグメントを手動で作成することができます。

Each segment has a name that identifies your application in the service map. The segment can be named statically, or you can configure the SDK to name it dynamically based on the host header in the incoming request. Dynamic naming lets you group traces based on the domain name in the request, and apply a default name if the name doesn't match an expected pattern (for example, if the host header is forged).

転送されたリクエスト

ロードバランサーなどを仲介してリクエストがアプリケーションに転送される場合、X-Ray では、IP パケットのソース IP からではなくリクエストの X-Forwarded-For ヘッダーからクライアント IP を取得します。転送されたリクエストに記録されているクライアント IP は偽造されている可能性があるため、信頼すべきではありません。

When a request is forwarded, the SDK sets an additional field in the segment to indicate this. If the segment contains the field x_forwarded_for set to true, the client IP was taken from the X-Forwarded-For header in the HTTP request.

ミドルウェアは、次の情報が含まれる http ブロックを使用して、各受信リクエスト用にセグメントを作成します。

  • HTTP メソッド – GET、POST、PUT、DELETE、その他。

  • クライアントアドレス – リクエストを送信するクライアントの IP アドレス。

  • レスポンスコード – 完了したリクエストの HTTP レスポンスコード。

  • タイミング – 開始時間 (リクエストが受信された時間) および終了時間 (レスポンスが送信された時間)。

  • ユーザーエージェント — リクエストから user-agent を取得します。

  • コンテンツの長さ — レスポンスからの content-length

アプリケーションにミドルウェアを追加する (Django)

ミドルウェアを MIDDLEWARE ファイルの settings.py リストに追加します。X-Ray ミドルウェアは、他のミドルウェアで失敗した要求が確実に記録されるように、settings.py ファイルの最初の行にする必要があります。

例 settings.py-X-Ray SDK for Python ミドルウェア

MIDDLEWARE = [ 'aws_xray_sdk.ext.django.middleware.XRayMiddleware', 'django.middleware.security.SecurityMiddleware', 'django.contrib.sessions.middleware.SessionMiddleware', 'django.middleware.common.CommonMiddleware', 'django.middleware.csrf.CsrfViewMiddleware', 'django.contrib.auth.middleware.AuthenticationMiddleware', 'django.contrib.messages.middleware.MessageMiddleware', 'django.middleware.clickjacking.XFrameOptionsMiddleware' ]

使用する settings.py ファイルにセグメント名を設定します。

例 settings.py – セグメント名

XRAY_RECORDER = {, 'AWS_XRAY_TRACING_NAME': 'My application', 'PLUGINS': ('EC2Plugin'), }

これは、X-Ray レコーダーに、デフォルトのサンプリングレートで Django アプリケーションが提供する要求をトレースするように指示します。使用する Django 設定ファイルにレコーダーを設定して、カスタムサンプリングルールを適用するか、その他の設定を変更することができます。

アプリケーションにミドルウェアを追加する (Flask)

Flask アプリケーションを計測するには、最初に xray_recorder にセグメント名を設定します。次に、XRayMiddleware 関数を使用して Flask アプリケーションをコードにパッチします。

例 app.py

from aws_xray_sdk.core import xray_recorder from aws_xray_sdk.ext.flask.middleware import XRayMiddleware app = Flask(__name__) xray_recorder.configure(service='My application') XRayMiddleware(app, xray_recorder)

これは、X-Ray レコーダーに、デフォルトのサンプリングレートで Flask アプリケーションが提供する要求をトレースするように指示します。レコーダーをコードに設定して、カスタムサンプリングルールを適用するか、その他の設定を変更することができます。

Python コードを手動で実装する

Django または Flask を使用していない場合、手動でセグメントを作成することができます。受信リクエストごとにセグメントを作成したり、パッチが適用された HTTP または AWS SDK クライアントの周囲にセグメントを作成してレコーダーのコンテキストを提供し、サブセグメントを追加したりすることができます。

例 main.py – 手動実装

from aws_xray_sdk.core import xray_recorder # Start a segment segment = xray_recorder.begin_segment('segment_name') # Start a subsegment subsegment = xray_recorder.begin_subsegment('subsegment_name') # Add metadata and annotations segment.put_metadata('key', dict, 'namespace') subsegment.put_annotation('key', 'value') # Close the subsegment and segment xray_recorder.end_subsegment() xray_recorder.end_segment()

セグメント命名ルールの設定

AWS X-Ray はサービス名を使用してアプリケーションを識別し、アプリケーションが使用する他のアプリケーション、データベース、外部 API、および AWS リソースからそのアプリケーションを区別します。X-Ray SDK が受信リクエストのセグメントを生成するときに、アプリケーションのサービス名をセグメントの name フィールドに記録します。

X-Ray SDK は HTTP リクエストヘッダーのホスト名に合わせてセグメントを命名できます。ただし、このヘッダーは偽造されている可能性があり、その場合はサービスマップで予期しないノードが発生することがあります。SDK が、偽造されたホストヘッダーを持つリクエストによりセグメントに正しくない名前を付けないようにするには、受信リクエストのデフォルト名を指定する必要があります。

アプリケーションが複数のドメインのリクエストに対応する場合、動的な命名ルールを使用してセグメント名にこれを反映するよう SDK を設定できます。動的な命名ルールにより、SDK は予期されるパターンに一致するリクエストにホスト名を使用し、一致しないリクエストにはデフォルト名を適用できます。

たとえば、3 つのサブドメイン (www.example.comapi.example.comstatic.example.com) へのリクエストに対応する 1 つのアプリケーションがあるとします。動的命名ルールとパターン *.example.com を使用して、異なる名前を持つ各サブドメインのセグメントを識別し、それによりサービスマップで 3 つのサービスノードが作成されます。アプリケーションが、パターンに一致しないホスト名のリクエストを受け取った場合は、指定したフォールバック名を持つ 4 番目のノードがサービスマップに表示されます。

すべての要求セグメントに同じ名前を使用するには、前のセクションで示すように、レコーダーを設定するときにアプリケーションの名前を指定します。

動的な命名戦略は、ホスト名と一致するようパターンを定義し、HTTP リクエストのホスト名がパターンと一致しない場合はデフォルトの名前を使用します。Django でセグメントに動的な名前を付けるには、DYNAMIC_NAMING 設定を使用する settings.py ファイルに追加します。

例 settings.py – 動的な名前付け

XRAY_RECORDER = { 'AUTO_INSTRUMENT': True, 'AWS_XRAY_TRACING_NAME': 'My application', 'DYNAMIC_NAMING': '*.example.com', 'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin'), }

パターン内で任意の文字列に一致させるには「*」を、また、任意の 1 文字に一致させるには「?」を使用することができます。Flask の場合は、コードでレコーダーを設定します

例 main.py – セグメント名

from aws_xray_sdk.core import xray_recorder xray_recorder.configure(service='My application') xray_recorder.configure(dynamic_naming='*.example.com')

注記

コードで定義したデフォルトのサービス名は、AWS_XRAY_TRACING_NAME 環境変数で上書きできます。