翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS X-Ray セグメントドキュメント
**トレースセグメント**は、アプリケーションが対応するリクエストの JSON 表現です。トレースセグメントは、元のリクエストに関する情報、アプリケーションがローカルで実行する作業に関する情報、およびアプリケーションが ** リソース、HTTP API、SQL データベースに対して行うダウンストリーム呼び出しに関する情報の**サブセグメントAWSを記録します。
**セグメントドキュメント**は、セグメントに関する情報を X-Ray に伝えます。セグメントドキュメントは最大で 64 kB とし、サブセグメントを含むセグメント全体、リクエストが進行中であることを示すセグメントのフラグメント、または別個に送信される単一のサブセグメントを含むことができます。セグメントドキュメントは、[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) API を使用して直接 X-Ray に送信できます。
X-Ray はセグメントドキュメントをコンパイルおよび処理し、それぞれ [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) および [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API を使用してアクセスできる、クエリ可能な**トレースサマリー**および**トレース全体**を生成します。このサービスは、X-Ray に送信するセグメントとサブセグメントに加えて、サブセグメントの情報を使用して**推測セグメント**を生成し、トレース全体に追加します。推定セグメントは、トレースマップのダウンストリームサービスとリソースを表します。
X-Ray は、セグメントドキュメントの **JSON スキーマ**を提供します。スキーマは、「[xray-segmentdocument-schema-v1.0.0](samples/xray-segmentdocument-schema-v1.0.0.zip)」からダウンロードできます。スキーマに示されたフィールドとオブジェクトについては、以下のセクションで詳しく説明します。
セグメントフィールドのサブセットは、フィルタ式で使用するために X-Ray によってインデックスが作成されます。たとえば、セグメントの `user` フィールドを一意の ID に設定した場合、X-Ray コンソールで、または `GetTraceSummaries` API を使用して、特定のユーザーに関連付けられたセグメントを検索できます。詳細については、「[フィルター式の使用](xray-console-filters.md)」を参照してください。
X-Ray SDK でアプリケーションを計測すると、SDK によりセグメントドキュメントが生成されます。セグメントドキュメントを直接 X-Ray に送信する代わりに、SDK がそれらのドキュメントをローカル UDP ポート経由で [X-Ray デーモン](xray-daemon.md)に送信します。詳細については、「[セグメントドキュメントを X-Ray デーモンに送信する](xray-api-sendingdata.md#xray-api-daemon)」を参照してください。
**Topics**
+ [セグメントフィールド](#api-segmentdocuments-fields)
+ [サブセグメント](#api-segmentdocuments-subsegments)
+ [HTTP リクエストデータ](#api-segmentdocuments-http)
+ [注釈](#api-segmentdocuments-annotations)
+ [メタデータ](#api-segmentdocuments-metadata)
+ [AWS リソースデータ](#api-segmentdocuments-aws)
+ [エラーと例外](#api-segmentdocuments-errors)
+ [SQL クエリ](#api-segmentdocuments-sql)
## セグメントフィールド
セグメントは、アプリケーションが対応するリクエストに関する追跡情報を記録します。セグメントは、少なくともリクエストの名前、ID、開始時間、トレース ID、および終了時間を記録します。
**Example 最小完了セグメント**
```
{
"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 トレースコンテキスト仕様](https://www.w3.org/TR/trace-context/)に準拠するその他のフレームワークを使用して作成されたトレース 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 は[レスポンスヘッダー](xray-concepts.md#xray-concepts-tracingheader)に表示されます。攻撃者が将来のトレース 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` は、セグメントを生成するサービスのドメイン名または論理名と一致する必要があります。ただし、これは強制ではありません。権限を持つアプリケーション[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)は、任意の名前でセグメントを送信できます。
次のフィールドは、セグメントではオプションです。
**オプションのセグメントフィールド**
+ `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 呼び出しの[トレースヘッダー](xray-concepts.md#xray-concepts-tracingheader)に追加します。ネストされたサブセグメントの場合、サブセグメントは親としてセグメントまたはサブセグメントを持つことができます。
+ `http` – 元の HTTP リクエストに関する情報を含む [`http`](#api-segmentdocuments-http) オブジェクト。
+ `aws` – アプリケーションがリクエストに対応した[`aws`](#api-segmentdocuments-aws)リソースに関する情報を含む AWS オブジェクト。
+ `error`、`throttle`、`fault`、`cause` – エラーが発生したことを示し、エラーの原因となった例外に関する情報を含む [error](#api-segmentdocuments-errors) フィールド。
+ `annotations` – X-Ray で検索用にインデックスを作成するキーと値のペアを含む [`annotations`](#api-segmentdocuments-annotations) オブジェクト。
+ `metadata` – セグメントに保存する追加のデータを含む [`metadata`](#api-segmentdocuments-metadata) オブジェクト。
+ `subsegments` – **オブジェクトの**配列[`subsegment`](#api-segmentdocuments-subsegments)。
## サブセグメント
サブセグメントを作成して、AWS のサービス と AWS SDK で作成するリソースへの呼び出し、内部または外部 HTTP ウェブ API への呼び出し、あるいは SQL データベースクエリの呼び出しを記録することができます。また、サブセグメントを作成してアプリケーションでコードブロックをデバッグしたり、注釈を付けたりできます。サブセグメントには他のサブセグメントを含めることができるため、内部関数呼び出しに関するメタデータを記録するカスタムサブセグメントには、他のカスタムサブセグメントおよびダウンストリーム呼び出し用のサブセグメントを含めることができます。
サブセグメントは、ダウンストリーム呼び出しを、それを呼び出したサービスの視点から記録します。X-Ray はサブセグメントを使用して、セグメントを送信しないダウンストリームサービスを識別し、そのエントリをサービスグラフに作成します。
サブセグメントはフルセグメントドキュメントに埋め込むことも、個別に送信することもできます。サブセグメントを個別に送信して、長期実行されているリクエストのダウンストリーム呼び出しを非同期でトレースしたり、セグメントドキュメントの最大サイズを超えないようにしたりできます。
**Example 埋め込みサブセグメントを含むセグメント**
独立したサブセグメントには、親セグメントを識別する `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 に通知し、セグメントを個別に送信して追跡してから、元のリクエストを完了することができます。
**Example 進行中セグメント**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}
```
**Example 独立したサブセグメント**
独立したサブセグメントには、親セグメントを識別する `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 トレースコンテキスト仕様](https://www.w3.org/TR/trace-context/)に準拠するその他のフレームワークを使用して作成されたトレース 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`](#api-segmentdocuments-http) オブジェクト。
+ `aws` – アプリケーションが呼び出したダウンストリーム[`aws`](#api-segmentdocuments-aws)リソースに関する情報を含む AWS オブジェクト。
+ `error`、`throttle`、`fault`、`cause` – エラーが発生したことを示し、エラーの原因となった例外に関する情報を含む [error](#api-segmentdocuments-errors) フィールド。
+ `annotations` – X-Ray で検索用にインデックスを作成するキーと値のペアを含む [`annotations`](#api-segmentdocuments-annotations) オブジェクト。
+ `metadata` – セグメントに保存する追加のデータを含む [`metadata`](#api-segmentdocuments-metadata) オブジェクト。
+ `subsegments` – [`subsegment`](#api-segmentdocuments-subsegments)オブジェクトの**配列**。
+ `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 の推測セグメントを生成します。
**Example 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
}
}
```
**Example ダウンストリーム 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
}
}
}
```
**Example ダウンストリーム 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 の注釈までインデックスを付けます。
**Example 注釈を使用した 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) を超えない限り、任意のサイズにすることができます。[https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API によって返された完全なセグメントドキュメントで、メタデータを表示できます。`debug` で始まるフィールドキー (次の例の `AWS.`) は、AWS が提供する SDK およびクライアントでの使用のために予約されています。
**Example カスタムサブセグメントとメタデータ**
```
{
"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 のタイプ。
**Example 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 テーブルのオペレーションの場合、テーブルの名前。
**Example 項目を保存するための 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`。
**Example サブセグメントと 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=?;"
}
}
```