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

# X-Ray SDK for Python を使用してセグメントに注釈とメタデータを追加する
<a name="xray-sdk-python-segment"></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 が作成するセグメントまたは作成するカスタムサブセグメントに、注釈およびメタデータを追加できます。

**注釈**は文字列、数値、またはブール値を使用したキーと値のペアです。注釈は、[フィルタ式](xray-console-filters.md)用にインデックス付けされます。注釈を使用して、コンソールでトレースをグループ化するため、または[https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API を呼び出すときに使用するデータを記録します。

**メタデータ**は、オブジェクトとリストを含む、任意のタイプの値を持つことができるキーバリューのペアですが、フィルタ式に使用するためにインデックスは作成されません。メタデータを使用してトレースに保存する追加のデータを記録しますが、検索で使用する必要はありません。

注釈とメタデータに加えて、セグメントに[ユーザー ID 文字列を記録](#xray-sdk-python-segment-userid)することもできます。ユーザー ID はセグメントの個別のフィールドに記録され、検索用にインデックスが作成されます。

**Topics**
+ [X-Ray SDK for Python で注釈を記録する](#xray-sdk-python-segment-annotations)
+ [X-Ray SDK for Python でメタデータを記録する](#xray-sdk-python-segment-metadata)
+ [X-Ray SDK for Python でユーザー ID を記録する](#xray-sdk-python-segment-userid)

## X-Ray SDK for Python で注釈を記録する
<a name="xray-sdk-python-segment-annotations"></a>

注釈を使用して、検索用にインデックスを作成するセグメントまたはサブセグメントに情報を記録します。

**注釈の要件**
+ **キー** – X-Ray 注釈のキーには最大 500 文字の英数字を使用できます。スペースまたはドットやピリオド (.) 以外の記号は使用できません。
+ **値** – X-Ray 注釈の値には最大 1,000 の Unicode 文字を使用できます。
+ **注釈**の数 – トレースごとに最大 50 の注釈を使用できます。

**注釈を記録するには**

1. `xray_recorder` から現在のセグメントまたはサブセグメントの参照を取得します。

   ```
   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_segment()
   ```

   または

   ```
   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_subsegment()
   ```

1. 文字列キー、および、ブール値、数値、文字列値を使用して `put_annotation` を呼び出します。

   ```
   document.put_annotation("mykey", "my value");
   ```

   次の例は、ドット、ブール値、数値、または文字列値を含む文字列キーを使用して `putAnnotation` を呼び出す方法を示しています。

   ```
   document.putAnnotation("testkey.test", "my value");
   ```

または、`put_annotation` メソッドを `xray_recorder` で使用できます。このメソッドは、現在のサブセグメントの注釈を記録します。サブセグメントが開いていない場合は、セグメントの注釈を記録します。

```
xray_recorder.put_annotation("mykey", "my value");
```

SDK は、セグメントドキュメントの `annotations` オブジェクトにキーと値のペアとして、注釈を記録します。同じキーで `put_annotation` を 2 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。

特定の値を持つ注釈のあるトレースを見つけるには、`annotation[key]`フィルタ式[の ](xray-console-filters.md) キーワードを使用します。

## X-Ray SDK for Python でメタデータを記録する
<a name="xray-sdk-python-segment-metadata"></a>

**警告**  
X-Ray SDK for Python では、循環参照を持つオブジェクトをメタデータ値として追加しないでください。これらのオブジェクトは JSON にシリアル化できず、SDK で無限ループを作成する可能性があります。また、パフォーマンスの問題を防ぐために、複雑で大規模なオブジェクトをメタデータとして追加することは避けてください。

メタデータを使用して、検索用にインデックスを作成する必要のないセグメントまたはサブセグメントに情報を記録します。メタデータ値は、文字列、数値、ブール値、または JSON オブジェクトや JSON 配列にシリアル化できる任意のオブジェクトになります。

**メタデータを記録するには**

1. `xray_recorder` から現在のセグメントまたはサブセグメントの参照を取得します。

   ```
   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_segment()
   ```

   または

   ```
   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_subsegment()
   ```

1. 文字列キー、ブール値、数値、文字列値、オブジェクト値、文字列名前空間を使用して `put_metadata` を呼び出します。

   ```
   document.put_metadata("my key", "my value", "my namespace");
   ```

   または

   キーと値だけを使用して `put_metadata` を呼び出します。

   ```
   document.put_metadata("my key", "my value");
   ```

または、`put_metadata` メソッドを `xray_recorder` で使用できます。このメソッドは、現在のサブセグメントのメタデータを記録します。サブセグメントが開いていない場合は、セグメントのメタデータを記録します。

```
xray_recorder.put_metadata("my key", "my value");
```

名前空間を指定しない場合、SDK は `default` を使用します。同じキーで `put_metadata` を 2 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。

## X-Ray SDK for Python でユーザー ID を記録する
<a name="xray-sdk-python-segment-userid"></a>

リクエストセグメントにユーザー ID を記録して、リクエストを送信したユーザーを識別します。

**ユーザー ID を記録するには**

1. `xray_recorder` から現在のセグメントへの参照を取得します。

   ```
   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_segment()
   ```

1. リクエストを送信したユーザーの文字列 ID を使用して `setUser` を呼び出します。

   ```
   document.set_user("U12345");
   ```

コントローラーで `set_user` を呼び出し、アプリケーションがリクエストの処理を開始するとすぐに、ユーザー ID を記録できます。

ユーザー ID のトレースを見つけるには、`user`フィルタ式[で、](xray-console-filters.md) キーワードを使用します。