翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# X-Ray SDK for Python ミドルウェアを使用して受信リクエストをトレースします。
<a name="xray-sdk-python-middleware"></a>

**注記**  
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。

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

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

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

Lambda で測定されているサンプル Python 関数については、「[ワーカー](scorekeep-lambda.md#scorekeep-lambda-worker)」を参照してください。

他のフレームワークのスクリプトまたは Python アプリケーションの場合、[セグメントを手動で作成](#xray-sdk-python-middleware-manual)することができます。

各セグメントには、サービスマップ内のアプリケーションを識別する名前があります。セグメントの名前は静的に指定することも、受信リクエストのホストヘッダーに基づいて動的に名前を付けるように 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`

**Topics**
+ [アプリケーションにミドルウェアを追加する (Django)](#xray-sdk-python-adding-middleware-django)
+ [アプリケーションにミドルウェアを追加する (Flask)](#xray-sdk-python-adding-middleware-flask)
+ [アプリケーションにミドルウェアを追加する (Bottle)](#xray-sdk-python-adding-middleware-bottle)
+ [Python コードを手動で実装する](#xray-sdk-python-middleware-manual)
+ [セグメント命名ルールの設定](#xray-sdk-python-middleware-naming)

## アプリケーションにミドルウェアを追加する (Django)
<a name="xray-sdk-python-adding-middleware-django"></a>

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

**Example 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 レコーダーを設定できるようになります。

**Example 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` ファイル](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django)にセグメント名を設定します。

**Example settings.py - セグメント名**  

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

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

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

## アプリケーションにミドルウェアを追加する (Flask)
<a name="xray-sdk-python-adding-middleware-flask"></a>

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

**Example 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 アプリケーションが提供する要求をトレースするように指示します。[レコーダーをコードに設定](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code)して､カスタムサンプリングルールを適用するか、その他の設定を変更することができます。

## アプリケーションにミドルウェアを追加する (Bottle)
<a name="xray-sdk-python-adding-middleware-bottle"></a>

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

**Example 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 アプリケーションが提供する要求をトレースするように指示します。[レコーダーをコードに設定](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code)して､カスタムサンプリングルールを適用するか、その他の設定を変更することができます。

## Python コードを手動で実装する
<a name="xray-sdk-python-middleware-manual"></a>

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

**Example 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()
```

## セグメント命名ルールの設定
<a name="xray-sdk-python-middleware-naming"></a>

AWS X-Ray は*サービス名*を使用してアプリケーションを識別し、アプリケーションが使用する他のアプリケーション、データベース、外部 APIs、 AWS リソースと区別します。X-Ray SDK が受信リクエストのセグメントを生成すると、アプリケーションのサービス名がセグメントの[名前フィールド](xray-api-segmentdocuments.md#api-segmentdocuments-fields)に記録されます。

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

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

たとえば、3 つのサブドメイン（`www.example.com`,`api.example.com`,および`static.example.com`）に対してリクエストを処理する単一のアプリケーションがあるとします。動的ネーミングストラテジーをパターン `*.example.com` で使用して、異なる名前を持つ各サブドメインのセグメントを識別することができます。結果的にはサービスマップ上に 3 つのサービスノードを作成することになります。アプリケーションがパターンと一致しないホスト名のリクエストを受信すると、指定したフォールバック名を持つ 4 番目のノードがサービスマップに表示されます。

すべてのリクエストセグメントに同じ名前を使用するには、[前のセクション](#xray-sdk-python-adding-middleware-django)で示されたように、レコーダーを設定するときにアプリケーションの名前を指定します｡

動的命名ルールは、ホスト名と一致するようパターンを定義し、HTTP リクエストのホスト名がパターンと一致しない場合はデフォルトの名前を使用します。Django でセグメントに動的な名前を付けるには、`DYNAMIC_NAMING` 設定を使用する [settings.py](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django) ファイルに追加します｡

**Example settings.py - 動的ネーミング**  

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

パターン内で任意の文字列に一致させるには「\$1」を､また、任意の 1 文字に一致させるには「?」を使用することができます。Flask の場合は、[コードでレコーダーを設定します](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code)。

**Example 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` [環境変数](xray-sdk-python-configuration.md#xray-sdk-python-configuration-envvars)で上書きできます。