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

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

X-Ray SDK for Python は、受信 HTTP リクエストを測定する次のミドルウェアをサポートしています。

• Django

• Flask

• Bottle

注記

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

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

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

各セグメントには、サービスマップ内のアプリケーションを識別する名前があります。セグメントの名前は静的に指定することも、受信リクエストのホストヘッダーに基づいて動的に名前を付けるように SDK を設定することもできます。動的ネーミングでは、リクエスト内のドメイン名に基づいてトレースをグループ化でき、名前が予想されるパターンと一致しない場合（たとえば、ホストヘッダーが偽造されている場合）、デフォルト名を適用できます。

転送されたリクエスト

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

リクエストが転送されると、それを示す追加フィールドが SDK によってセグメントに設定されます。セグメントのフィールド x_forwarded_for が true に設定されている場合、クライアント IP が HTTP リクエストの X-Forwarded-For ヘッダーから取得されます。

ミドルウェアは、次の情報が含まれる 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 ファイルの INSTALLED_APPS リストに X-Ray SDK Django アプリを追加します。これにより、アプリの起動時にX-Ray レコーダーを設定できるようになります。

例 settings.py - X-Ray SDK for Python Django アプリ

INSTALLED_APPS = [
    'aws_xray_sdk.ext.django',
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
]

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

例 settings.py - セグメント名

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

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

注記

plugins はタプルとして渡されるため、単一のプラグインを指定する場合は必ず末尾に , を付けてください。例えば、plugins = ('EC2Plugin',) などです。

アプリケーションにミドルウェアを追加する (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 アプリケーションが提供する要求をトレースするように指示します。レコーダーをコードに設定して､カスタムサンプリングルールを適用するか、その他の設定を変更することができます。

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

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

例 app.py

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.bottle.middleware import XRayMiddleware
 
app = Bottle()
 
xray_recorder.configure(service='fallback_name', dynamic_naming='My application')
app.install(XRayMiddleware(xray_recorder))

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

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 が受信リクエストのセグメントを生成すると、アプリケーションのサービス名がセグメントの名前フィールドに記録されます。

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

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

たとえば、3 つのサブドメイン（www.example.com,api.example.com,およびstatic.example.com）に対してリクエストを処理する単一のアプリケーションがあるとします。動的ネーミングストラテジーをパターン *.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 環境変数で上書きできます。