AWS X-Ray セグメントドキュメント - AWS X-Ray
セグメントフィールドサブセグメントHTTP リクエストデータ‏注釈メタデータAWS リソースデータエラーと例外SQL クエリ

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

トレースセグメントは、アプリケーションが対応するリクエストの JSON 表現です。トレースセグメントは、元のリクエストに関する情報、アプリケーションがローカルで実行する作業に関する情報、およびアプリケーションが リソース、HTTP API、SQL データベースに対して行うダウンストリーム呼び出しに関する情報のサブセグメントAWSを記録します。

セグメントドキュメントは、セグメントに関する情報を X-Ray に伝えます。セグメントドキュメントは最大で 64 kB とし、サブセグメントを含むセグメント全体、リクエストが進行中であることを示すセグメントのフラグメント、または別個に送信される単一のサブセグメントを含むことができます。セグメントドキュメントは、PutTraceSegments API を使用して直接 X-Ray に送信できます。

X-Ray はセグメントドキュメントをコンパイルおよび処理し、それぞれGetTraceSummariesおよびBatchGetTraces API を使用してアクセスできる、クエリ可能なトレースサマリおよびトレース全体を生成します。このサービスは、X-Ray に送信するセグメントとサブセグメントに加えて、サブセグメントの情報を使用して推測セグメントを生成し、トレース全体に追加します。推定セグメントは、トレースマップのダウンストリームサービスとリソースを表します。

X-Ray は、セグメントドキュメントの JSON スキーマを提供します。スキーマは、「xray-segmentdocument-schema-v1.0.0」からダウンロードできます。スキーマに示されたフィールドとオブジェクトについては、以下のセクションで詳しく説明します。

セグメントフィールドのサブセットは、フィルタ式で使用するために X-Ray によってインデックスが作成されます。たとえば、セグメントの user フィールドを一意の ID に設定した場合、X-Ray コンソールで、または GetTraceSummaries API を使用して、特定のユーザーに関連付けられたセグメントを検索できます。詳細については、「フィルター式の使用」を参照してください。

X-Ray SDK でアプリケーションを計測すると、SDK によりセグメントドキュメントが生成されます。セグメントドキュメントを直接 X-Ray に送信する代わりに、SDK がそれらのドキュメントをローカル UDP ポート経由で X-Ray デーモンに送信します。詳細については、「セグメントドキュメントを X-Ray デーモンに送信する」を参照してください。

セグメントフィールド

セグメントは、アプリケーションが対応するリクエストに関する追跡情報を記録します。セグメントは、少なくともリクエストの名前、ID、開始時間、トレース ID、および終了時間を記録します。

例 最小完了セグメント
{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0a",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "end_time" : 1.478293361449E9
}

次のフィールドは、セグメントで必須、または条件付きで必須です。

注記

特に明記されていない限り、値は文字列である必要があります (最大 250 文字)。

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

  • 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 個の進行中のセグメントのみを送信します。

サービス名

セグメントの name は、セグメントを生成するサービスのドメイン名または論理名と一致する必要があります。ただし、これは強制ではありません。権限を持つアプリケーションPutTraceSegmentsは、任意の名前でセグメントを送信できます。

次のフィールドは、セグメントではオプションです。

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

  • 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オブジェクトの配列。

サブセグメント

サブセグメントを作成して、AWS のサービス と AWS SDK で作成するリソースへの呼び出し、内部または外部 HTTP ウェブ API への呼び出し、あるいは SQL データベースクエリの呼び出しを記録することができます。また、サブセグメントを作成してアプリケーションでコードブロックをデバッグしたり、注釈を付けたりできます。サブセグメントには他のサブセグメントを含めることができるため、内部関数呼び出しに関するメタデータを記録するカスタムサブセグメントには、他のカスタムサブセグメントおよびダウンストリーム呼び出し用のサブセグメントを含めることができます。

サブセグメントは、ダウンストリーム呼び出しを、それを呼び出したサービスの視点から記録します。X-Ray はサブセグメントを使用して、セグメントを送信しないダウンストリームサービスを識別し、そのエントリをサービスグラフに作成します。

サブセグメントはフルセグメントドキュメントに埋め込むことも、個別に送信することもできます。サブセグメントを個別に送信して、長期実行されているリクエストのダウンストリーム呼び出しを非同期でトレースしたり、セグメントドキュメントの最大サイズを超えないようにしたりできます。

例 埋め込みサブセグメントを含むセグメント

独立したサブセグメントには、親セグメントを識別する type の subsegment、および parent_id があります。

{
  "trace_id"   : "1-5759e988-bd862e3fe1be46a994272793",
  "id"         : "defdfd9912dc5a56",
  "start_time" : 1461096053.37518,
  "end_time"   : 1461096053.4042,
  "name"       : "www.example.com",
  "http"       : {
    "request"  : {
      "url"        : "https://www.example.com/health",
      "method"     : "GET",
      "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7",
      "client_ip"  : "11.0.3.111"
    },
    "response" : {
      "status"         : 200,
      "content_length" : 86
    }
  },
  "subsegments" : [
    {
      "id"         : "53995c3f42cd8ad8",
      "name"       : "api.example.com",
      "start_time" : 1461096053.37769,
      "end_time"   : 1461096053.40379,
      "namespace"  : "remote",
      "http"       : {
        "request"  : {
          "url"    : "https://api.example.com/health",
          "method" : "POST",
          "traced" : true
        },
        "response" : {
          "status"         : 200,
          "content_length" : 861
        }
      }
    }
  ]
}

長期間実行されるリクエストについては、進行中のセグメントを送信してリクエストが受信されたことを X-Ray に通知し、セグメントを個別に送信して追跡してから、元のリクエストを完了することができます。

例 進行中セグメント
{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0b",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "in_progress": true
}
例 独立したサブセグメント

独立したサブセグメントには、親セグメントを識別する type の subsegment、trace_id、および parent_id があります。

{
  "name" : "api.example.com",
  "id" : "53995c3f42cd8ad8",
  "start_time" : 1.478293361271E9,
  "end_time" : 1.478293361449E9,
  "type" : "subsegment",
  "trace_id" : "1-581cf771-a006649127e371903a2de979"
  "parent_id" : "defdfd9912dc5a56",
  "namespace"  : "remote",
  "http"       : {
      "request"  : {
          "url"    : "https://api.example.com/health",
          "method" : "POST",
          "traced" : true
      },
      "response" : {
          "status"         : 200,
          "content_length" : 861
      }
  }
}

リクエストが完了したら、end_time とともに再送信してセグメントを閉じます。完了セグメントは進行中のセグメントを上書きします。

非同期ワークフローをトリガーした、完了したリクエストに対してサブセグメントを個別に送信することもできます。たとえば、ウェブ API は、ユーザーがリクエストした作業を開始する直前に OK 200 応答を返す場合があります。応答が送信されたらすぐに、完全なセグメントを X-Ray に送信し、それに続いて後で完了する作業のサブセグメントを送信できます。セグメントと同様に、サブセグメントフラグメントを送信して、サブセグメントが開始されたことを記録した後で、ダウンストリーム呼び出しが完了したら完全なサブセグメントでそれを上書きできます。

次のフィールドは、サブセグメントで必須、または条件付きで必須です。

注記

特に明記されていない限り、値は文字列です (最大 250 文字)。

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

  • 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 リクエストデータ

HTTP ブロックを使用して、(セグメントで) アプリケーションが対応した HTTP リクエスト、または (サブセグメントで) アプリケーションがダウンストリーム HTTP API に対して行ったリクエストの詳細を記録します。このオブジェクトのほとんどのフィールドは、HTTP リクエストと応答で見つかった情報にマッピングされます。

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 – レスポンス本文の長さをバイト単位で示す整数。

ダウンストリームウェブ API に対する呼び出しを計測するときは、HTTP リクエストおよびレスポンスに関する情報を含むセグメントを記録します。X-Ray はサブセグメントを使用してリモート API の推測セグメントを生成します。

例 Amazon EC2 で実行しているアプリケーションにより提供される HTTP 呼び出し用のセグメント
{
  "id": "6b55dcc497934f1a",
  "start_time": 1484789387.126,
  "end_time": 1484789387.535,
  "trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
  "name": "www.example.com",
  "origin": "AWS::EC2::Instance",
  "aws": {
    "ec2": {
      "availability_zone": "us-west-2c",
      "instance_id": "i-0b5a4678fc325bg98"
    },
    "xray": {
        "sdk_version": "2.11.0 for Java"
    },
  },
  "http": {
    "request": {
      "method": "POST",
      "client_ip": "78.255.233.48",
      "url": "http://www.example.com/api/user",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
      "x_forwarded_for": true
    },
    "response": {
      "status": 200
    }
  }
例 ダウンストリーム HTTP 呼び出しのサブセグメント
{
  "id": "004f72be19cddc2a",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "name": "names.example.com",
  "namespace": "remote",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  }
}
例 ダウンストリーム HTTP 呼び出しの推定セグメント
{
  "id": "168416dc2ea97781",
  "name": "names.example.com",
  "trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "parent_id": "004f72be19cddc2a",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  },
  "inferred": true
}

‏注釈

セグメントとサブセグメントは、X-Ray がフィルタ式で使用するためにインデックスを作成する 1 つ以上のフィールドが含まれた annotations オブジェクトを含むことができます。フィールドは、文字列、数値、またはブール値を持つことができます (オブジェクトや配列を含むことはできません)。X-Ray は、トレースごとに 50 の注釈までインデックスを付けます。

例 注釈を使用した HTTP 呼び出しのセグメント
{
  "id": "6b55dcc497932f1a",
  "start_time": 1484789187.126,
  "end_time": 1484789187.535,
  "trace_id": "1-5880168b-fd515828bs07678a3bb5a78c",
  "name": "www.example.com",
  "origin": "AWS::EC2::Instance",
  "aws": {
    "ec2": {
      "availability_zone": "us-west-2c",
      "instance_id": "i-0b5a4678fc325bg98"
    },
    "xray": {
        "sdk_version": "2.11.0 for Java"
    },
  },
  "annotations": {
    "customer_category" : 124,
    "zip_code" : 98101,
    "country" : "United States",
    "internal" : false
  },
  "http": {
    "request": {
      "method": "POST",
      "client_ip": "78.255.233.48",
      "url": "http://www.example.com/api/user",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
      "x_forwarded_for": true
    },
    "response": {
      "status": 200
    }
  }

キーはフィルタで動作するために英数字である必要があります。アンダースコアは使用できます。その他の記号や空白は使用できません。

メタデータ

セグメントとサブセグメントは、オブジェクトと配列を含めて、任意の型の値を持つ 1 つ以上のフィールドが含まれた metadata オブジェクトを含むことができます。X-Ray はメタデータのインデックスを作成せず、セグメントドキュメントが最大サイズ (64 kB) を超えない限り、任意のサイズにすることができます。BatchGetTraces API によって返された完全なセグメントドキュメントで、メタデータを表示できます。debug で始まるフィールドキー (次の例の AWS.) は、AWS が提供する SDK およびクライアントでの使用のために予約されています。

例 カスタムサブセグメントとメタデータ
{
  "id": "0e58d2918e9038e8",
  "start_time": 1484789387.502,
  "end_time": 1484789387.534,
  "name": "## UserModel.saveUser",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },
  "subsegments": [
    {
      "id": "0f910026178b71eb",
      "start_time": 1484789387.502,
      "end_time": 1484789387.534,
      "name": "DynamoDB",
      "namespace": "aws",
      "http": {
        "response": {
          "content_length": 58,
          "status": 200
        }
      },
      "aws": {
        "table_name": "scorekeep-user",
        "operation": "UpdateItem",
        "request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG",
        "resource_names": [
          "scorekeep-user"
        ]
      }
    }
  ]
}

AWS リソースデータ

セグメントの場合、aws オブジェクトはアプリケーションが実行されているリソースに関する情報を含みます。複数のフィールドを単一のリソースに適用できます。たとえば、Elastic Beanstalk の複数コンテナの Docker 環境で実行されているアプリケーションは、Amazon EC2 インスタンス、インスタンス上で実行されている Amazon ECS コンテナ、および Elastic Beanstalk 環境自体に関する情報を持つことができます。

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 ブロック
"aws":{
   "elastic_beanstalk":{
      "version_label":"app-5a56-170119_190650-stage-170119_190650",
      "deployment_id":32,
      "environment_name":"scorekeep"
   },
   "ec2":{
      "availability_zone":"us-west-2c",
      "instance_id":"i-075ad396f12bc325a",
      "ami_id":
   },
   "cloudwatch_logs":[
      {
         "log_group":"my-cw-log-group",
         "arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
      }
   ],
   "xray":{
      "auto_instrumentation":false,
      "sdk":"X-Ray for Java",
      "sdk_version":"2.8.0"
   }
}

サブセグメントの場合、アプリケーションがアクセスする AWS のサービス およびリソースに関する情報を記録します。X-Ray はこの情報を使用して、サービスマップのダウンストリームサービスを表す推定セグメントを作成します。

aws (サブセグメント)

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

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

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

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

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

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

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

例 項目を保存するための DynamoDB に対する呼び出しのサブセグメント
{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "table_name": "scorekeep-user",
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}

エラーと例外

エラーが発生した場合は、エラーと生成された例外に関する詳細を記録できます。アプリケーションがユーザーにエラーを返す場合はセグメントにエラーを記録し、ダウンストリーム呼び出しがエラーを返す場合はサブセグメントにエラーを記録します。

エラーのタイプ

次の 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 オブジェクトを含めてエラーの原因を示します。

cause

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

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

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

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

1 つまたは複数の例外オブジェクトのエラーに関する詳細情報を含めます。

exception

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

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

  • message – 例外メッセージ。

  • type – 例外のタイプ。

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

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

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

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

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

使用可能な場合、コールスタックに関する情報を stackFrame オブジェクトに記録します。

stackFrame

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

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

  • line – ファイルの行。

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

SQL クエリ

アプリケーションが SQL データベースに対して実行するクエリのサブセグメントを作成できます。

sql

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

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

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

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

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

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

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

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

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

例 サブセグメントと SQL クエリ
{
  "id": "3fd8634e78ca9560",
  "start_time": 1484872218.696,
  "end_time": 1484872218.697,
  "name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
  "namespace": "remote",
  "sql" : {
    "url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
    "preparation": "statement",
    "database_type": "PostgreSQL",
    "database_version": "9.5.4",
    "driver_version": "PostgreSQL 9.4.1211.jre7",
    "user" : "dbuser",
    "sanitized_query" : "SELECT  *  FROM  customers  WHERE  customer_id=?;"
  }
}