AWS X-Ray
開発者ガイド

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

注釈とメタデータを使用して、リクエスト、環境、またはアプリケーションに関する追加情報を記録できます。X-Ray SDK によって作成されたセグメント、または作成したカスタムサブセグメントに注釈とメタデータを追加できます。

Annotations are key-value pairs with string, number, or Boolean values. Annotations are indexed for use with filter expressions. Use annotations to record data that you want to use to group traces in the console, or when calling the GetTraceSummaries API.

Metadata are key-value pairs that can have values of any type, including objects and lists, but are not indexed for use with filter expressions. Use metadata to record additional data that you want stored in the trace but don't need to use with search.

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

X-Ray SDK for Python を使用して注釈を記録する

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

注釈の要件

  • キー – 最大 500 の英数字。アンダースコアを除くスペースまたは記号はありません。

  • – 最大 1,000 のユニコード文字。

  • エントリ – トレースごとに最大 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");

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

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

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

特定の値を持つ注釈のあるトレースを見つけるには、フィルタ式annotations.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 キーワードを使用します。