AWS X-Ray による分散トレーシングと障害調査

分散したリクエストの経路を追う

アプリケーションが一つのプロセス内で完結せず、APIの入口、複数のサービス、データベース、外部APIなどを連携して処理すると、応答が遅くなった場所やエラーの発生箇所をログだけから突き止めるのが難しくなります。AWS X-Rayは、アプリケーションが処理するリクエストについて、入口から下流の依存先までの処理データを集め、個々のリクエストの調査とアプリケーション全体の可視化を支援する分散トレーシングサービスです。

各処理が記録したデータを共通のトレースにまとめることで、複数のコンポーネントを通過したリクエストを一続きの流れとして確認できます。応答時間、各処理区間の所要時間、呼び出し先、HTTP応答、例外やエラーなどをたどれば、どの部分が全体の遅延や失敗に関係したかを調べられます。

X-Rayが提供する可視化には、アプリケーションと依存関係の全体像を確認するサービスマップ（トレースマップ）と、個別のリクエストを詳細に追うトレースがあります。サービスマップで異常な依存先や遅い区間の候補を見つけ、関連するトレースを開いて一件の処理を掘り下げる、という使い方ができます。

サービスマップで全体像、トレースで個々の処理を見る

サービスマップは、アプリケーションを構成するサービスやクライアント、データストアなどをノードとして表し、リクエストが流れる依存関係をエッジで結んだ図です。ノードやエッジに集約されたトレースデータから、リクエスト量、応答時間、エラーの発生状況などを見渡し、負荷や遅延が集中している箇所を探せます。下流サービスがトレースを直接送信しない場合でも、呼び出し元の記録から依存先を推定してマップに表せる場合があります。

トレースは、一つのリクエストを処理する各リソースの記録を、共通のトレースIDで関連付けたものです。サービスマップが集約された関係と傾向を俯瞰するのに対して、トレース詳細では各セグメントやサブセグメントの開始・終了時刻、エラー、呼び出し先などを時系列に沿って確認します。例えば、配達日時を予約するWeb APIで応答が遅い場合、マップで遅延の目立つ在庫確認サービスを見つけ、個別トレースを開けば、API入口、アプリケーション、在庫照会のどの区間に時間を要したかを比較できます。

サービスマップで遅いサービスが見つかっても、それだけで根本原因が確定するわけではありません。個々のリクエストのトレースを調べ、呼び出し順序と区間ごとの時間、エラーの種類を照合して原因を切り分けます。全体の傾向をつかむ図と、個々のリクエストを分析する記録は、相互に補完するものです。

トレースデータが届くまで

トレースを収集するには、アプリケーションの処理に計装（instrumentation）を行います。計装は、受信したリクエスト、下流への呼び出し、処理中に生じたイベントなどをトレースデータとして記録できるようにすることです。アプリケーションにX-Ray SDKを組み込む従来方式では、SDKがリクエストやレスポンスの情報、アプリケーション内の処理、AWS SDKクライアントを通じた呼び出しなどをセグメント／サブセグメントとして記録します。

SDKからデータを送る構成では、セグメントのJSONドキュメントをローカルで待ち受けるX-Rayデーモンに渡します。デーモンはUDPポート2000でデータを受け取り、一時的に蓄積してバッチ単位でX-Rayサービスへ送信します。デーモンがX-Ray APIへデータをアップロードするには、必要なAWS認証情報と送信権限が必要です。EC2では一般にインスタンスプロファイルのIAMロールを利用し、アプリケーションとデーモン双方の配置・権限・接続設定を環境に合わせて用意します。

デーモンを含む実行環境は一律にAWSが自動管理するものではありません。EC2などでは運用者がデーモンの導入と実行環境を構成します。一方、AWS LambdaのX-Ray統合では、サンプリングされたリクエストの関数実行時にLambdaがデーモンを実行します。したがって「SDKが記録すること」と「記録データを受け取りX-Rayへ中継すること」は別の役割であり、使用するサービスの統合状況によってデーモンの運用責任が異なります。

AWS X-Rayは全リクエストを常に記録するとは限りません。サンプリングは、どのリクエストをトレース対象として記録するかを決める仕組みです。トラフィックが大きいアプリケーションでデータ量を制御しながら代表的なリクエストを観測できますが、サンプリングされないリクエストの個別トレースは得られない点を踏まえて調査します。

セグメント、サブセグメント、トレースID

X-Rayが受け取る処理記録の基本単位はセグメントです。セグメントは、アプリケーションを動かす一つのリソースがリクエストを処理した内容を表します。リソース名やリクエストの詳細、処理の開始・終了時刻、レスポンス、発生したエラーや例外などを含められます。セグメントはJSON形式のドキュメントとして記録され、X-Rayは同じリクエストに属するセグメントを集めてトレースを構成します。

セグメント内の処理をさらに細かく観察する記録がサブセグメントです。下流のAWSサービス、外部HTTP API、SQLデータベースへの呼び出しを記録したり、必要に応じてアプリケーション固有の処理区間を計測したりできます。サブセグメントの開始・終了時刻を比較すれば、親の処理時間のうち、どの依存先または処理区間が時間を使ったかを詳しく調べられます。下流サービスが独自のセグメントを送信しない場合、呼び出し元のサブセグメントから依存先の推定情報が作られることもあります。

トレースIDは、同じリクエストに関係するセグメントを識別する共通IDです。リクエストが複数のリソースを経由しても、トレースIDを引き継ぐことで、別々に記録された処理を同じトレースとして関連付けられます。HTTP通信ではトレースヘッダーをリクエストに含めてコンテキストを伝播させます。X-Rayのトレースヘッダーには、トレースのルートIDや親区間のID、サンプリング情報などが含まれます。受信側がヘッダーを引き継げなかったり計装されていなかったりすると、全体の追跡が分断されることがあります。

概念を区別すると、セグメントはリソース単位の処理記録、サブセグメントはその中の詳細な区間、トレースIDは一つのリクエストに属する記録を結び付ける識別子、トレースはそれらの関連記録をまとめた単位です。

アノテーションでトレースを検索する

本番環境ではトレース数が多くなり、すべてを目視で確認するのは現実的ではありません。トレースを絞り込むには、検索条件に使えるアノテーションをセグメントやサブセグメントへ追加します。アノテーションは、トレースとともに記録される単純なキーと値の組であり、X-Rayの検索式から参照できるようインデックス化されます。例えば、リクエストの operation に reservation-confirm、result に capacity-unavailable といった独自属性を付ければ、特定の操作や業務上の結果に該当するトレースを検索する手掛かりになります。アノテーションはトレースのグループ分けや、条件に合うトレースの抽出に向いています。

これに対してメタデータは、トレース内に保存して詳細画面で確認する追加情報です。文字列だけでなく、オブジェクトやリストなど複雑な値も保持できますが、アノテーションのような検索インデックスは作られません。検索条件として使いたい属性はアノテーションに、検索は不要だが診断時に参照したい情報はメタデータにする、という使い分けが重要です。大量・機微な情報を無制限に追加するのではなく、調査目的に必要な値に限定します。

AWSリソースのタグは、X-Rayトレースに付けるアノテーションとは別の仕組みです。タグはAWSリソースを分類し、コスト配分やリソース管理、IAMポリシーによるアクセス制御などに活用する管理用のキーと値です。トレース検索でタグをアノテーションの代わりに使うことはできません。検索したいリクエスト属性は、アプリケーションの計装でアノテーションとして記録します。

情報	トレース検索での利用	主な用途
アノテーション	インデックス化され、検索式に利用できる	条件に合うリクエストの絞り込みやグループ化
メタデータ	インデックス化されず、検索条件にできない	個別トレースの詳細画面で参照する補足情報
AWSリソースタグ	X-Rayのトレース検索用属性ではない	コスト管理、リソース分類、IAMによる管理・制御

CloudWatchコンソールで確認する

X-Rayのトレースとマップは、Amazon CloudWatchコンソールから確認できます。CloudWatch側のX-Ray機能では、トレースの表示・分析・フィルタリングや、アプリケーションの処理経路を表すトレースマップの確認ができ、CloudWatchのログやメトリクスと関連付けながら問題を調査できます。トレースマップは、従来「サービスマップ」と呼ばれてきた依存関係の可視化に相当します。

AWSには従来のX-Rayコンソールもありますが、AWSはそのコンソールの新規開発を継続しておらず、CloudWatchコンソール側に新しいX-Ray機能を提供しています。現在の画面ではCloudWatchのナビゲーションから「X-Ray traces」配下の「Trace Map」を開いて全体像を確認し、そこから関連トレースの詳細へ進めます。学習上は「X-Rayでサービスマップとトレースを確認する」と理解しつつ、実際の操作場所がCloudWatchコンソールにある点も押さえます。

現行の計装方式を選ぶときの注意

従来のX-Ray SDKとデーモンは既存システムのトレース理解に重要ですが、AWSの案内ではX-Ray SDK／デーモンは2026年2月25日からメンテナンスモードに入り、セキュリティ問題への対応にリリースが限定されています。AWSはOpenTelemetryへの移行を推奨しています。また、CloudWatch Agentのバージョン1.300025.0以降は、EC2やオンプレミスのサーバーからOpenTelemetryまたはX-RayクライアントSDKのトレースを収集してX-Rayへ送信でき、従来の専用デーモンや複数エージェントの管理を減らせる場合があります。

試験では、X-Ray SDKがアプリケーションを計装し、セグメントデータがデーモン経由で送信される従来の構成、トレースIDによるリクエストの関連付け、セグメントとサブセグメントの役割、アノテーションによる検索を区別できることが重要です。実システムを新たに設計する際には、SDK／デーモンのメンテナンス状況を踏まえてOpenTelemetryなどの現在の推奨方式を検討します。

試験での判断ポイント

• 複数サービスにまたがるリクエストの経路や各区間の遅延、エラー原因を調査する要件には、AWS X-Rayの分散トレーシングが適します。
• サービス間の依存関係や全体の遅延傾向を俯瞰するときはサービスマップ／トレースマップを、特定リクエストの区間やエラーを深掘りするときは個別トレースを使います。
• 一つのリソースが受け持つ処理の記録はセグメント、外部呼び出しや内部処理をさらに詳しく測る記録はサブセグメントです。
• リクエストが別サービスへ渡る際は、トレースヘッダーと共通のトレースIDによってコンテキストを引き継ぎます。
• トレースの検索キーにはアノテーションを使います。詳細表示に残すが検索不要な情報はメタデータであり、AWSリソースタグはトレース検索属性ではありません。
• 大量のリクエストではサンプリングにより記録対象が選択されます。サンプリングされていないリクエストに個別トレースがないことを考慮します。
• デーモン方式では、SDKによる記録、デーモンによるバッファリングと送信、デーモンに付与するIAM権限を区別します。Lambdaなどのマネージド統合では、利用者が担う運用範囲が異なります。

X-Rayを活用する要点は、全体像の可視化と個別リクエストの追跡を使い分け、各記録の関連付けをトレースIDで保ち、検索対象の属性をアノテーションとして設計することです。計装・サンプリング・データ送信の構成を理解すると、分散したアプリケーションの遅延や障害を、単一のログやメトリクスでは見えにくいリクエスト経路に沿って分析できます。