X-Ray SDK for Python を使用してセグメントに注釈とメタデータを追加する

注釈やメタデータにより、リクエスト、環境、またはアプリケーションに関する追加情報を記録することができます。X-Ray SDK が作成するセグメントまたは作成するカスタムサブセグメントに、注釈およびメタデータを追加できます。

注釈は文字列、数値、またはブール値を使用したキーと値のペアです。注釈は、フィルタ式用にインデックス付けされます。注釈を使用して、コンソールでトレースをグループ化するため、またはGetTraceSummaries API を呼び出すときに使用するデータを記録します。

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

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

X-Ray SDK for Python で注釈を記録する

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

注釈の要件

• キー – 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()

2. 文字列キー、および、ブール値、数値、文字列値を使用して 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]フィルタ式の キーワードを使用します。

X-Ray SDK for Python でメタデータを記録する

メタデータを使用して、検索用にインデックスを作成する必要のないセグメントまたはサブセグメントに情報を記録します。メタデータ値は、文字列、数値、ブール値、または 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()

2. 文字列キー、ブール値、数値、文字列値、オブジェクト値、文字列名前空間を使用して 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 を記録する

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

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

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

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

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

   document.set_user("U12345");

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

ユーザー ID のトレースを見つけるには、userフィルタ式で、 キーワードを使用します。