AWS X-Ray セグメントドキュメント

必須のセグメントフィールド

• name – リクエストを処理したサービスの論理名 (最大 200 文字)。たとえば、アプリケーション名やドメイン名です。名前には、Unicode 文字、数字、空白、および次の記号を含めることができます: _､.､:､/､%､&､#､=､+､\､-､@

• id – セグメントの 64 ビット識別子。16 進数の数字であり、同じトレース内のセグメント間で一意です。

• trace_id – 1 つのクライアントリクエストから送信されるすべてのセグメントとサブセグメントに接続する一意の識別子です。

  X-Ray のトレース ID 形式

  X-Ray trace_id は、ハイフンで区切られた 3 つの数字で構成されています。例えば、1-58406520-a006649127e371903a2de979 と指定します。これには、以下のものが含まれます：

  • バージョン番号、すなわち、1。

  • 元のリクエストの時刻。ユニックスエポックタイムで、16 進数 8 桁で表示されます。

    例えば、エポックタイムで 2016 年 12 月 1 日 10:00AM PST (太平洋標準時刻) は 1480615200 秒、または 16 進数で 58406520 と表示されます。

  • グローバルに一意なトレースの 96 ビットの識別子で、24 桁の 16 進数で表示されます。

  注記

  X-Ray は、OpenTelemetry、および W3C トレースコンテキスト仕様に準拠するその他のフレームワークを使用して作成されたトレース ID をサポートするようになりました。W3C トレース ID は X-Ray に送信するとき、X-Ray トレース ID 形式でフォーマットする必要があります。例えば、W3C トレース ID 4efaaf4d1e8720b39541901950019ee5 は X-Ray に送信するとき、1-4efaaf4d-1e8720b39541901950019ee5 の形式にする必要があります。X-Ray トレース ID には元のリクエストの Unix エポックタイムのタイムスタンプが含まれますが、これは W3C トレース ID を X-Ray 形式で送信する場合に必要ありません。

  トレース ID セキュリティ

  トレース ID はレスポンスヘッダーに表示されます。攻撃者が将来のトレース ID を計算できないように安全なランダムのアルゴリズムを使用してトレース ID を生成し、その ID を使用してアプリケーションにリクエストを送信します。

• start_time – セグメントが作成された時間の数値 (エポック時間の浮動小数点で表した秒数)。例えば、1480615200.010、1.480615200010E9 です。必要なだけ桁数を使用します。利用できる場合は、マイクロ秒の精度をお勧めします。

• end_time – セグメントが切断された時間を表す数値。例えば、1480615200.090、1.480615200090E9 です。end_time または in_progress のいずれかを指定します。

• in_progress – ではなく を設定して、開始されたが完了していないセグメントを記録するtrueブール値end_time。アプリケーションが処理に時間がかかるリクエストを受信したときに、進行中のセグメントを送信して、リクエストの受信を追跡します。レスポンスが送信されると、完了したセグメントが送信され進行中のセグメントを上書きします。リクエストごとに、1 つの完全なセグメントと、1 つまたは 0 個の進行中のセグメントのみを送信します。

オプションのセグメントフィールド

• service – アプリケーションに関する情報を含むオブジェクト。

  • version – リクエストに対応したアプリケーションのバージョンを識別する文字列。

• user – リクエストを送信したユーザーを識別する文字列。

• origin – アプリケーションを実行している AWS リソースのタイプ。

  サポートされる値

  • AWS::EC2::Instance – Amazon EC2 インスタンス。

  • AWS::ECS::Container – Amazon ECS コンテナ。

  • AWS::ElasticBeanstalk::Environment – Elastic Beanstalk 環境

  複数の値をアプリケーションに適用する場合は、最も具体的な値を使用します。たとえば、複数コンテナの Docker Elastic Beanstalk の環境では、Amazon ECS コンテナでアプリケーションが実行され、そのコンテナは Amazon EC2 インスタンスで実行されます。この場合、環境は他の 2 つのリソースの親として、オリジンを AWS::ElasticBeanstalk::Environment に設定します。

• parent_id – 計測したアプリケーションからリクエストが発信された場合に指定するサブセグメント ID。X-Ray SDK は親サブセグメント ID をダウンストリーム HTTP 呼び出しのトレースヘッダーに追加します。ネストされたサブセグメントの場合、サブセグメントは親としてセグメントまたはサブセグメントを持つことができます。

• http – 元の HTTP リクエストに関する情報を含むhttpオブジェクト。

• aws – アプリケーションがリクエストを処理した AWS リソースに関する情報を含む aws オブジェクト。

• error、throttle、fault、cause – エラーが発生したことを示し、エラーの原因となった例外に関する情報を含む error フィールド。

• annotations – X-Ray で検索用にインデックスを作成するキーと値のペアを含むannotationsオブジェクト。

• metadata – セグメントに保存する追加のデータを含むmetadataオブジェクト。

• subsegments – オブジェクトの配列subsegment。

必須のサブセグメントフィールド

• id – サブセグメントの 64 ビット識別子。16 進数の数字であり、同じトレース内のセグメント間で一意です。

• name – サブセグメントの論理名。ダウンストリーム呼び出しの場合は、リソースまたはサービスを呼び出した後のサブセグメントの名前。カスタムサブセグメントの場合は、計測するコードの後にサブセグメントの名前を付けます (関数名など)。

• start_time – サブセグメントが作成された時間を表す数値で、エポック時間を浮動小数点で表した秒 (ミリ秒)。例えば、1480615200.010、1.480615200010E9 です。

• end_time – サブセグメントが切断された時間を表す数値。例えば、1480615200.090、1.480615200090E9 です。end_time または in_progress を指定します。

• in_progress – ではなく を設定して、開始されたが完了していないサブセグメントを記録するtrueブール値end_time。ダウンストリームリクエストごとに、1 つの完全なサブセグメントと、1 つまたは 0 個の進行中のサブセグメントのみを送信します。

• trace_id – サブセグメントの親セグメントのトレース ID。サブセグメントを個別に送信する場合にのみ必要です。

  X-Ray のトレース ID 形式

  X-Ray trace_id は、ハイフンで区切られた 3 つの数字で構成されています。例えば、1-58406520-a006649127e371903a2de979 と指定します。これには、以下のものが含まれます：

  • バージョン番号、すなわち、1。

  • 元のリクエストの時刻。ユニックスエポックタイムで、16 進数 8 桁で表示されます。

    例えば、エポックタイムで 2016 年 12 月 1 日 10:00AM PST (太平洋標準時刻) は 1480615200 秒、または 16 進数で 58406520 と表示されます。

  • グローバルに一意なトレースの 96 ビットの識別子で、24 桁の 16 進数で表示されます。

  注記

  X-Ray は、OpenTelemetry、および W3C トレースコンテキスト仕様に準拠するその他のフレームワークを使用して作成されたトレース ID をサポートするようになりました。W3C トレース ID は X-Ray に送信するとき、X-Ray トレース ID 形式でフォーマットする必要があります。例えば、W3C トレース ID 4efaaf4d1e8720b39541901950019ee5 は X-Ray に送信するとき、1-4efaaf4d-1e8720b39541901950019ee5 の形式にする必要があります。X-Ray トレース ID には元のリクエストの Unix エポックタイムのタイムスタンプが含まれますが、これは W3C トレース ID を X-Ray 形式で送信する場合に必要ありません。

• parent_id – サブセグメントの親セグメントのセグメント ID。サブセグメントを個別に送信する場合にのみ必要です。ネストされたサブセグメントの場合、サブセグメントは親としてセグメントまたはサブセグメントを持つことができます。

• type – subsegment。サブセグメントを個別に送信する場合にのみ必要です。

オプションのサブセグメントフィールド

• namespace – AWS SDK 呼び出しの場合は aws、他のダウンストリーム呼び出しの場合は remote。

• http – 送信 HTTP 呼び出しに関する情報を含むhttpオブジェクト。

• aws – アプリケーションが呼び出したダウンストリーム AWS リソースに関する情報を含む aws オブジェクト。

• error、throttle、fault、cause – エラーが発生したことを示し、エラーの原因となった例外に関する情報を含む error フィールド。

• annotations – X-Ray で検索用にインデックスを作成するキーと値のペアを含むannotationsオブジェクト。

• metadata – セグメントに保存する追加のデータを含むmetadataオブジェクト。

• subsegments – subsegmentオブジェクトの配列。

• precursor_ids – このサブセグメントの前に完了した同じ親を持つサブセグメントを識別するサブセグメント ID の配列。

http

すべてのフィールドはオプションです。

• request – リクエストに関する情報。

  • method – リクエストメソッド。例えば、GET と指定します。

  • url – リクエストのプロトコル、ホスト名、およびパスからコンパイルされた、リクエストの完全な URL。

  • user_agent – リクエスタのクライアントからのユーザーエージェント文字列。

  • client_ip – リクエスタの IP アドレス。IP パケットの Source Address から、または転送リクエストの場合は X-Forwarded-For ヘッダーから取得できます。

  • x_forwarded_for – (セグメントのみ) が ヘッダーから読み取られ、偽造されている可能性があるため信頼できないことを示すclient_ipブール値X-Forwarded-For。

  • traced – (サブセグメントのみ) ダウンストリーム呼び出しが別の追跡されたサービスであることを示すブール値。このフィールドが true に設定されている場合、このブロックを含むサブセグメントの parent_id に一致する id を含むセグメントをダウンストリームサービスがアップロードするまで、X-Ray はトレースが壊れていると見なします。

• response – レスポンスに関する情報。

  • status – レスポンスの HTTP ステータスを示す整数。

  • content_length – レスポンス本文の長さをバイト単位で示す整数。

aws (セグメント)

すべてのフィールドはオプションです。

• account_id – アプリケーションがセグメントを別の に送信する場合は AWS アカウント、アプリケーションを実行しているアカウントの ID を記録します。

• cloudwatch_logs – 単一の CloudWatch ロググループを記述するオブジェクトの配列。

  • log_group – CloudWatch のロググループ名。

  • arn – CloudWatch のロググループ ARN。

• ec2 – Amazon EC2 インスタンスに関する情報。

  • instance_id – EC2 インスタンスのインスタンス ID。

  • instance_size – EC2 インスタンスのタイプ。

  • ami_id – Amazon マシンイメージ ID。

  • availability_zone – インスタンスが実行されているアベイラビリティーゾーン。

• ecs – Amazon ECS コンテナに関する詳細。

  • container – コンテナのホスト名。

  • container_id – コンテナの完全なコンテナ ID。

  • container_arn – コンテナインスタンスの ARN。

• eks – Amazon EKS クラスターに関する情報。

  • pod – EKS ポッドのホスト名。

  • cluster_name – EKS クラスター名。

  • container_id – コンテナの完全なコンテナ ID。

• elastic_beanstalk – Elastic Beanstalk 環境に関する情報。この情報は、最新の Elastic Beanstalk プラットフォームの /var/elasticbeanstalk/xray/environment.conf という名前のファイルにあります。

  • environment_name – 環境の名前。

  • version_label – リクエストに対応したインスタンスに現在デプロイされているアプリケーションバージョンの名前。

  • deployment_id – リクエストに対応したインスタンスに対して最後に成功したデプロイの ID を示す数値。

• xray – 使用した計測のタイプとバージョンに関するメタデータ。

  • auto_instrumentation – 自動計測が使用されたかどうかを示すブール値 (例えば、Java Agent)。

  • sdk_version – 使用中の SDK またはエージェントのバージョン。

  • sdk – SDK のタイプ。

aws (サブセグメント)

すべてのフィールドはオプションです。

• operation – AWS のサービス または リソースに対して呼び出された API アクションの名前。

• account_id – アプリケーションが別のアカウントのリソースにアクセスする場合、またはセグメントを別のアカウントに送信する場合は、アプリケーションがアクセスした AWS リソースを所有するアカウントの ID を記録します。

• region – リソースがアプリケーションとは異なるリージョンにある場合は、そのリージョンを記録します。例えば、us-west-2 と指定します。

• request_id – リクエストの一意の識別子。

• queue_url – Amazon SQS キューのオペレーションの場合は、キューの URL。

• table_name – DynamoDB テーブルのオペレーションの場合、テーブルの名前。

エラーのタイプ

次の 1 つ以上のフィールドを true に設定して、エラーが発生したことを示します。複合エラーの場合は、複数のタイプを適用できます。たとえば、ダウンストリーム呼び出しからの 429 Too Many Requests エラーにより、アプリケーションは 500 Internal Server Error を返すことがあり、その場合は 3 つすべてのタイプが適用されます。

• error – クライアントエラーが発生したことを示すブール値 (レスポンスステータスコードは 4XX Client Error でした)。

• throttle – リクエストが調整されたことを示すブール値 (レスポンスステータスコードは 429 Too Many Requests でした)。

• fault – サーバーエラーが発生したことを示すブール値 (レスポンスステータスコードは 5XX Server Error でした)。

cause

原因は、16 文字の例外 ID、または次のフィールドを含むオブジェクトとすることができます。

• working_directory – 例外が発生したときの作業ディレクトリのフルパス。

• paths – 例外が発生したときに使用されているライブラリまたはモジュールへのパスの配列。

• exceptions – 例外オブジェクトの配列。

exception

すべてのフィールドはオプションです。

• id – 例外の 64 ビット識別子。16 進数の数字であり、同じトレース内のセグメント間で一意です。

• message – 例外メッセージ。

• type – 例外のタイプ。

• remote – ダウンストリームサービスによって返されたエラーが原因で例外が発生したことを示すブール値。

• truncated – から省略されたスタックフレームの数を示す整数stack。

• skipped – この例外とその子の間でスキップされた例外 (発生した例外) の数を示す整数。

• cause – 例外の親 (この例外を発生させた例外) の例外 ID。

• stack – stackFrame オブジェクトの配列。

stackFrame

すべてのフィールドはオプションです。

• path – ファイルの相対パス。

• line – ファイルの行。

• label – 関数またはメソッド名。

sql

すべてのフィールドはオプションです。

• connection_string – SQL Server または URL 接続文字列を使用しないその他のデータベース接続の場合は、パスワードを除く接続文字列を記録します。

• url – URL 接続文字列を使用するデータベース接続の場合は、パスワードを除く URL を記録します。

• sanitized_query – データベースクエリと、プレースホルダーによって削除または置換されたユーザー指定の値。

• database_type – データベースエンジンの名前。

• database_version – データベースエンジンのバージョン番号。

• driver_version – アプリケーションが使用するデータベースエンジンドライバーの名前とバージョン番号。

• user – データベースユーザー名。

• preparation – クエリで call を使用した場合は PreparedCall、クエリで statement を使用した場合は PreparedStatement。