翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS X-Ray の概念
AWS X-Ray は、サービスから*セグメント*形式でデータを受け取ります。X-Ray は、*トレース*への共通リクエストを含むセグメントをグループ化します。X-Ray は、トレースを処理して、アプリケーションのビジュアル表現を提供する*サービスグラフ*を生成します。
**Topics**
+ [セグメント](#xray-concepts-segments)
+ [サブセグメント](#xray-concepts-subsegments)
+ [サービスグラフ](#xray-concepts-servicegraph)
+ [トレース](#xray-concepts-traces)
+ [サンプリング](#xray-concepts-sampling)
+ [トレースヘッダー](#xray-concepts-tracingheader)
+ [フィルタ式](#xray-concepts-filterexpressions)
+ [グループ](#xray-concepts-groups)
+ [注釈とメタデータ](#xray-concepts-annotations)
+ [エラー、障害、および例外](#xray-concepts-errors)
## セグメント
アプリケーションロジックを実行しているコンピューティングリソースは、**セグメント**としての動作に関するデータを送信します。セグメントには、リソース名、リクエストの詳細、行った作業の詳細が含まれています。たとえば、HTTP リクエストがアプリケーションに到達すると、次のデータが記録されます。
+ **ホスト** – ホスト名、エイリアス、または IP アドレス
+ **リクエスト** – メソッド、クライアントアドレス、パス、ユーザーエージェント
+ **レスポンス** – ステータス、コンテンツ
+ **行った作業** – 開始および終了時刻、サブセグメント
+ **発生する問題** – [エラー、障害、例外](#xray-concepts-errors) (例外スタックの自動取得を含む)。
![\[X-Ray トレースのセグメントデータ\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-cw-segment-overview.png)
X-Ray SDK はリクエストおよびレスポンスのヘッダー、アプリケーションのコード、およびそれを実行する AWS リソースに関するメタデータから情報を収集します。収集するデータを選択するには、アプリケーション設定、または受信リクエスト、ダウンストリームリクエスト、AWS SDK クライアントを計測するコードを変更します。
**転送されたリクエスト**
ロードバランサーまたは他の仲介者がアプリケーションにリクエストを転送する場合、X-Ray は、クライアントの IP をIP パケットの送信元 IP からではなく、リクエストの`X-Forwarded-For`ヘッダーから取得します。転送されたリクエストに対して、記録されたクライアント IP は偽造される可能性があるので、信頼できるものではありません。
X-Ray SDK を使用して、[注釈やメタデータ](#xray-concepts-annotations)などの追加情報を記録します。セグメントとサブセグメントで記録される構造と情報の詳細については、「」を参照してください[AWS X-Ray セグメントドキュメント](xray-api-segmentdocuments.md) セグメントのドキュメントのサイズは最大 64 kB まで可能です｡
## サブセグメント
セグメントでは、完了した作業に関するデータを**サブセグメント**に分けることができます。サブセグメントには、詳細なタイミング情報や、元のリクエストを満たすためにアプリケーションが実行したダウンストリーム呼び出しに関する詳細を含みます。サブセグメントには、AWS のサービス、外部 HTTP API、SQL データベースに対する呼び出しに関する追加の詳細を含めることができます。アプリケーションのコードの特定の関数または行を計測する任意のサブセグメントを定義することもできます。
![\[サブセグメントに含まれる詳細情報\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-cw-timeline-segment.png)
Amazon DynamoDB のような独自のセグメントを送信しないサービスでは、X-Ray はサブセグメントを使用してトレースマップ上に*推測セグメント*とダウンストリームノードを生成します。これにより、トレースをサポートしていない場合でも、外部の場合でも、すべてのダウンストリーム依存関係を表示することができます。
サブセグメントは、クライアントとしてのダウンストリーム呼び出しのアプリケーションビューを表します。ダウンストリームサービスも計測されている場合、送信するセグメントは、アップストリームクライアントのサブセグメントから生成された推測セグメントを置き換えます。利用可能であれば、サービスグラフのノードはサービスのセグメントからの情報を常に使用しますが、2 つのノード間のエッジはアップストリームサービスのサブセグメントを使用します。
たとえば、実装された AWS SDK クライアントで DynamoDB を呼び出すと、X-Ray SDK はその呼び出しのサブセグメントを記録します。DynamoDB はセグメントを送信しないので、トレースの推測セグメント、サービスグラフの DynamoDB ノード、サービスと DynamoDB の間のエッジにはサブセグメントの情報が含まれます。
![\[実装されたアプリケーションと DynamoDB の間のエッジ。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-cw-servicemap-ddb-edge.png)
実装されたアプリケーションを使用して実装された別のサービスを呼び出すと、ダウンストリームサービスは、サブセグメントに記録されたアップストリームサービスと同じ呼び出しのビューを記録するために、独自のセグメントを送信します。サービスグラフでは、両方のサービスのノードに、それらのサービスのセグメントからのタイミング情報とエラー情報が含まれています。その間には、アップストリームサービスのサブセグメントの情報が含まれています。
![\[他の計測アプリケーションを呼び出す計測アプリケーション。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-cw-servicemap-instrumented-edge.png)
ダウンストリームサービスは要求の処理を開始および終了した時点を正確に記録し、アップストリームサービスは要求が 2 つのサービス間を移動した時間を含めて往復遅延を記録するため、両方の視点が役立ちます。
## サービスグラフ
X-Ray はアプリケーションが送信したデータを使用して**サービスグラフ**を生成します。X-Ray にデータを送信する各 AWS リソースは、グラフのサービスとして表示されます。**エッジ**は、リクエスト処理に一緒に使用するサービスに接続されています。エッジは、クライアントをアプリケーションに接続し、アプリケーションを、使用しているダウンストリームサービスおよびリソースに接続します。
**サービス名**
セグメントの `name` は、セグメントを生成するサービスのドメイン名または論理名と一致する必要があります。ただし、これは強制ではありません。[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)にアクセス許可を持つアプリケーションは、任意の名前でセグメントを送信できます。
サービスグラフは、アプリケーションを構成するサービスおよびリソースに関する情報を含む JSON ドキュメントです。X-Ray コンソールでは、サービスグラフを使用して、視覚化または*サービスマップ*を生成します。
![\[トレースマップ\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-gettingstarted-cw-servicemap-simplified.png)
分散アプリケーションの場合、X-Ray は、同一のトレース ID を含むリクエストを処理するすべてのサービスのノードを、単一のサービスグラフに組み合わせます。リクエストがヒットする最初のサービスによって、フロントエンドと呼び出すサービスの間で伝達される「[トレースヘッダー](#xray-concepts-tracingheader)」が追加されます。
たとえば、[Scorekeep](xray-scorekeep.md) は、マイクロサービス (AWS Lambda 関数) を呼び出し、Node.js ライブラリを使用してランダム名を生成するウェブ API を実行します。X-Ray SDK for Java はトレース ID を生成し、Lambda への呼び出しにそれを含めます。Lambda はトレースデータを送信し、トレース ID を関数に渡します。また、X-Ray SDK for Node.js は、トレース ID を使用してデータを送信します。その結果、API、Lambda サービス、Lambda 関数のノードはすべて別々ですが、接続されたノードとしてトレースマップに表示されます。
サービスグラフのデータは 30 日間保持されます｡
## トレース
**トレース ID** はアプリケーションを経由するリクエストのパスを追跡します。トレースでは、1 つのリクエストで生成されたセグメントをすべて収集します。このリクエストは、通常ロードバランサーを経由してやり取りされる HTTP GET または POST リクエストですが、アプリケーションコードにヒットし、他の AWS サービスまたは外部の ウェブ API のダウンストリーム呼び出しを生成します。HTTP リクエストでやり取りされる最初にサポートされたサービスでは、トレース ID のヘッダーをリクエストに追加し、ダウンストリームに伝達して、レイテンシー、処理、その他のリクエストデータを追跡します。
![\[単一のリクエストによって生成されるすべてのセグメントを収集するトレースのタイムライン表示\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/xray-trace-details-cw.png)
X-Ray トレースの請求方法については、「[AWS X-Ray の料金](https://aws.amazon.com/xray/pricing/)」をご覧ください。トレースデータは 30 日間保持されます｡
## サンプリング
効率的にトレースを行ってアプリケーションが処理するリクエストの代表的なサンプルを提供するため、X-Ray SDK によって**サンプリング**アルゴリズムが適用され、トレースするリクエストが決定されます。デフォルトでは、X-Ray SDK は 1 秒ごとに最初のリクエストを記録し、追加のリクエストの 5% を記録します。
開始時にサービス料がかからないように、デフォルトのサンプリングレートは控えめになっています｡ デフォルトのサンプリングルールを変更し、サービスまたはリクエストのプロパティに基づいてサンプリングを適用する追加のルールを設定するように X-Ray を設定できます。
例えば、サンプリングを無効にして、状態を変更したり、ユーザーやトランザクションを処理したりする呼び出しのすべての要求をトレースすることができます。バックグラウンドポーリング、ヘルスチェック、接続保守などの大量の読み取り専用呼び出しでは、低いレートでサンプリングを行っても、問題が発生した場合にも十分なデータを得ることができます。
詳細については、「[サンプリングルールの設定](xray-console-sampling.md)」を参照してください。
## トレースヘッダー
構成可能な最小値まではすべてのリクエストがトレースされます。その後はリクエストの一定の割合がトレースされ、不要なコストを避けます。サンプリングデシジョンおよびトレース ID は、HTTP リクエストの ** という名前の**トレースヘッダー`X-Amzn-Trace-Id`に追加されます。トレースヘッダーは、リクエストがヒットした最初の X-Ray 組み込みサービスによって追加されます。また、X-Ray SDK によって読み取られ、レスポンスに含められます。
**Example ルートトレース ID 突きのトレースヘッダーおよびサンプリングデシジョン**
```
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1
```
**トレースヘッダーのセキュリティ**
トレースヘッダーは、X-Ray SDK、AWS のサービス、またはクライアントリクエストから発信されます。アプリケーションで受信リクエストから `X-Amzn-Trace-Id` を削除し、ユーザーが自分のリクエストにトレース ID またはサンプリングデシジョンを追加することで発生する問題を回避できます。
計測対象アプリケーションからのリクエストの場合は、親セグメント ID をトレースヘッダーに含めることもできます。たとえば、アプリケーションで計測対象 HTTP クライアントを使用してダウンストリーム HTTP ウェブ API を呼び出す場合、X-Ray SDK は元のリクエストのセグメントの ID をダウンストリームリクエストのトレースヘッダーに追加します。ダウンストリームリクエストを処理する計測対象アプリケーションで、親セグメント ID を記録して 2 つのリクエストを接続できます。
**Example ルートトレース ID、親セグメント ID およびサンプリングデシジョンを含むトレースヘッダー**
```
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1
```
処理メカニズムの一部として、Lambda や他の AWS のサービス によってトレースヘッダーに `Lineage` が追加される場合がありますが、直接使用しないでください。
**Example Lineage を含むトレースヘッダー**
```
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1;Lineage=25:a87bd80c:1
```
## フィルタ式
サンプリングされている場合でも、複雑なアプリケーションでは大量のデータが生成されます。AWS X-Ray コンソールでは、操作が簡単なサービスグラフのビューを提供します。問題を識別しアプリケーションを最適化するために役立つ健全性とパフォーマンス情報が表示されます。高度なトレースでは、個別のリクエストのトレースを掘り下げたり、**フィルタ式**を使用して特定のパスまたはユーザーに関連するトレースを検索したりできます。
![\[個別のリクエストのトレースを掘り下げる\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-filter-httpurlCONTAINS-cw.png)
## グループ
フィルタ式が拡張され、X-Ray でもグループ機能がサポートされます。フィルタ式を使用すると、グループへのトレースを受け入れる基準を定義できます。
グループを名前別または Amazon リソースネーム (ARN) 別に呼び出すことで、独自のサービスグラフ、トレースサマリ、および Amazon CloudWatch メトリクスを生成することができます。グループの作成後、着信トレースは、X-Ray サービスに格納されるときにグループのフィルタ式と照合されます。各基準に一致するトレース数のメトリクスは、1 分ごとに CloudWatch に公開されます。
グループのフィルタ式を更新しても、すでに記録されているデータは変わりません。更新は後続のトレースにのみ適用されます。これにより、新しい式と古い式がマージされたグラフが表示される場合があります。これを回避するには、現在のグループを削除し、新しいグループを作成します。
**注記**
グループは、フィルタ式と一致する取得済みのトレースの数で請求されます。詳細については、「[AWS X-Ray 料金表](https://aws.amazon.com/xray/pricing/)」を参照してください。
グループの詳細については、「[グループの設定](xray-console-groups.md)」を参照してください。
## 注釈とメタデータ
アプリケーションを設定すると、X-Ray SDK は、受信リクエストと発信リクエスト、使用された AWS のリソース、およびアプリケーション自体に関する情報を記録します。その他の情報を注釈およびメタデータとして、セグメントドキュメントに追加することもできます。注釈とメタデータはトレースレベルで集約され、任意のセグメントまたはサブセグメントに追加できます。
**注釈**は、「[フィルタ式](xray-console-filters.md)」で使用するためにインデックス化されたシンプルなキーと値のペアです。注釈を使用して、コンソールでトレースをグループ化するため、または[https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API を呼び出すときに使用するデータを記録します。
X-Ray は、トレースごとに 50 の注釈までインデックスを付けます。
**メタデータ**は、オブジェクトとリストを含む、任意のタイプの値を持つことができるキーと値のペアですが、フィルタ式に使用するためにインデックスは作成されません。メタデータを使用してトレースに保存するデータを記録しますが、トレースの検索用に使用する必要はありません。
セグメントまたはサブセグメントの詳細ウィンドウ内の注釈およびメタデータは、CloudWatch コンソールで[トレースの詳細](xray-console-traces.md#xray-console-traces-view)ページに表示できます。
![\[セグメントまたはサブセグメントの注釈とメタデータは CloudWatch コンソールで詳細を確認できる\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-cw-subsegment-metadata.png)
## エラー、障害、および例外
X-Ray は、アプリケーションコードで発生するエラーと、ダウンストリームサービスから返されるエラーをトレースします。エラーは次のように分類されます。
+ **`Error`** – クライアントエラー (400 系のエラー)
+ **`Fault`** – サーバー障害 (500 系のエラー)
+ **`Throttle`** – スロットリングエラー (429 Too Many Requests)
アプリケーションが実装されたリクエストを処理しているときに例外が発生すると、X-Ray SDK はスタックトレースを含む例外に関する詳細を記録します (利用可能な場合)。X-Ray コンソールで[セグメント詳細](xray-console-traces.md#xray-console-segments)の例外を表示できます。