AWS X-Rayのまとめ(AWS DVA対策)

AWS DVA
2025.09.14

AWS Certified Developer – Associate(DVA) を勉強中です。

先日、AWS X-Rayのチュートリアルをやってみて、なんとなくではありますが、できる事がわかりました。
今回はAWS DVA対策として、AWS X-Rayを理解するためのキーワードを自分なりにまとめました。

サービスマップ(トレースマップ)

AWS X-Rayといえばこれだと思います。

以下の図がサービスマップですが、クライアントからのリクエストをECSで受け付けて、そこから更にECSがDynamoDBのAPIを実行していることがわかります。

表示を切り替えることで、平均レイテンシ、平均リクエスト数などもわかります。円の大きさはリクエストの多さを表し、円が赤色の場合は障害(5XX)の発生を表しているようです。

ちなみに、キャプチャ画面にはTrace Mapと書いていますが、サービスマップはTrace Mapに統合されたようです。X-Ray トレースマップの使用 – AWS X-Ray

セグメント

セグメントは、以下の図のようにECS などのサービスが X-Ray に送信する「処理の記録」です。

例として、下のキャプチャは ECS がクライアントからリクエストを受け取ったときに作られたセグメントです。

このセグメントには、以下の情報が含まれます。

  1. 時間情報：リクエストの開始と終了の時間、リクエストの所要時間
  2. リクエスト情報：リクエストのURL、メソッド、結果のステータスコード
  3. エラー情報：エラーと障害の情報（あれば）
  4. [リソース]タブ：このセグメントを送ってきた環境の情報が表示される。
    今回でいうとEC2で動いているコンテナの情報。例えば、「エラーが発生したセグメントが、どのEC2で動いていたか」がすぐに分かる。

後述しますが、セグメントにはX-Ray SDKを使って、注釈(Annotation)やメタデータなどの情報も付与することができます。

サブセグメント

サブセグメントは、セグメントをさらに細かく分けて「何をやったか」を記録したものです。

例えば先ほどのセグメントは「ECS がクライアントからリクエストを受け取ってレスポンスを返した」という全体の処理を表しています。

その中でレスポンスを返すまでには、次の処理が行われています。

  • DynamoDB からデータを取得・登録する
  • Amazon SNS に通知を送る

このように、クライアントからリクエストを受けてレスポンスを返すまでの間に ECS が実際にどんな処理をしたのかを詳しく記録しているのがサブセグメントです。

サブセグメントには次の情報が含まれます。（セグメントとほぼ同じです）

  1. 時間情報：処理の開始と終了の時間、処理の所要時間
  2. リクエスト情報：リクエストのURL、メソッド、結果のステータスコード
  3. エラー情報：エラーと障害の情報（あれば）
  4. [リソース]タブ：キャプチャはDynamoDBの例ですが、テーブルネーム、操作(GetItem)、Consistent read(強力な整合性のある読み込みかどうか)の情報がある。ここに示される情報はサービスによって異なる。

トレース

トレースは1つのリクエストで生成されたセグメントの全てのことを言います。
今回の例では、クライアントがECSにリクエストをして、ECSがDynamoDBのAPIを実行しています。DynamoDBはセグメントを送らないため、トレースに含まれるのはECSのセグメントだけです。
例えば、API Gateway→Lambda→API Gateway→Fargate→S3のような構成でのリクエストの流れでは、トレースに含まれるセグメントは4つです。

AWS-Black-Belt_2023_AWS-X-Ray_0228_v1.pdfより

トレースヘッダーの伝搬（X-AmznーTrace-Id)

複数のサービスをまたいだリクエストなのに、どうやって「同じトレースに属するセグメントだ」と判断しているのか気になったので調べてみました。

答えはX-Amzn-Trace-IdというHTTPヘッダーで、リクエストの最初のポイント(API GatewayやALBなど)でこのヘッダーが付与され、後続のサービス(Lambda、ECS、Fargateなど)へリクエストを転送する際にそのまま引き継がれる仕組みになっているようです。

  • 最初にリクエストを受けたサービスがトレースIDを発行し、X-Amzn-Trace-Idヘッダーに設定する
  • 後続の各サービスは、このヘッダーの値を読み取り、同じトレースIDを使ってセグメントを送信する
  • X-Ray SDKを使っていれば、このヘッダーの伝播は基本的に自動でやってくれるらしい

サンプリング

サンプリングは、トレースを取得する頻度やルールを決めるもの。デフォルトでは１秒毎に最低１つのリクエストをサンプリングし、その後はリクエストの5％が取得されます。
サンプリングを設定する理由は、コスト削減のためだけでなく、アプリケーションの代表的なリクエストを効率よくトレースするためでもあります。

サンプリングルールの例：

  • POSTメソッドは１秒毎に最低10のリクエストを取得し、それ以降は10%を取得する
  • PUTメソッドはpathが/history/*のリクエストは全て取得する

のように、複数の設定ができます。

フィルタ式

フィルタ式は、条件に合致するトレースを大量のトレースの中から検索するための式です。

X-Rayでは大量のトレースが取得されるので、フィルタ式を使用して特定のパスやユーザーのトレースを見つけることができます。

以下は、フィルタ式の構文です。

keyword operator value

例えば以下のキャプチャでは、responsetime (応答時間)が0.1秒以上のトレースを検索し、結果として7件のトレースがヒットしていることが分かります。

※右ペインの「クエリ」を選択すると、サンプルクエリを確認できます。

また、以下の例はリクエストURLに“/api/game/”を含むトレースをフィルタします。

http.url CONTAINS "/api/game/"

他にも様々なkeywordや演算子があるので、気になる方は公式ドキュメントを確認してみてください。

フィルター式の使用 – AWS X-Ray

Keywordの例

keyword意味
duration所要時間
http.statusレスポンスステータスコード
http.urlリクエストURL
http.methodリクエストメソッド

注釈とメタデータ

注釈(Annotation)とメタデータは、どちらもセグメントに追加するデータですが、明確な違いがあります。

注釈(Annotation)

  • インデックス化されたキーと値のペア
  • インデックス化されている ＝ フィルタ式で検索できる
  • 用途：検索用

メタデータ

  • オブジェクトとリストを含む、任意のタイプの値を持つことができるキーと値のペア
  • インデックスは作成されない = フィルタ式での検索はできない
  • 用途：セグメントに追加のデータを保存してデバッグ用に使う

X-Rayにセグメントを送る方法

ここからは、「どうやってX-Rayによる計測を開始するのか？」を確認したいと思います。

X-Rayデーモンとは

EC2・ECSでX-Rayを使う場合、共通で登場するのが「X-Rayデーモン」という存在です。

X-RayデーモンはUDPポート2000をリッスンし、未加工のセグメントデータをX-Ray APIに送信するアプリケーションソフトウェアです。
なぜ、X-Rayデーモンを経由してX-Ray APIにセグメントを送るのかというと、計測するアプリケーションの負荷を最低限にするためです。

EC2で動作するアプリケーションの場合

EC2で動作するアプリケーションを計測するために必要な作業は以下です

  • X-Ray SDKを使ってアプリケーションコードに計測するためのコードを組み込む。
    →X-Ray SDKは６つの言語（Go，Java，Node.js, Python, .NET, Ruby）で用意されています。
  • EC2にX-Rayデーモンをインストールする
  • インスタンスプロファイルを使用して、X-RayデーモンがセグメントデータをX-Ray APIにアップロードするためのアクセス権限を付与する

以上の設定により、X-Rayによる計測を行うことができます。

ECSで操作するアプリケーションの場合

ECSの場合は、X-Rayデーモンプロセスを実行するコンテナをsidecarとしてデプロイします
このときも、タスクロールに管理ポリシーを追加して、X-RayデーモンがセグメントデータをX-Ray APIにアップロードするためのアクセス権限を付与する必要があります。

AWS Lambdaの場合

Lambda関数の設定から有効化できるようです。

AWS-Black-Belt_2023_AWS-X-Ray_0228_v1.pdfより

その他

API Gateway、App Runner、SNSなどのAWSサービスも設定画面から有効化できるようです。

X-Rayが利用できるその他のAWSサービスは、他の AWS X-Ray との統合 AWS のサービス – AWS X-Rayをご確認ください。

最後に

AWSのX-Rayのドキュメントに以下の注記がありました。

End-of-support通知 – 2027 年 2 月 25 日、 AWS X-Ray は AWS X-Ray SDKs とデーモンのサポートを終了します。2027 年 2 月 25 日以降、更新やリリースは配信されなくなります。サポートタイムラインの詳細については、「」を参照してくださいX-Ray SDK とデーモンのサポート終了タイムライン。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「X-Ray 計測から OpenTelemetry 計測への移行」を参照してください。
X-Ray の使用開始 – AWS X-Ray

ということで、AWS Certified Developer – Associate(DVA)の試験バージョンが変わるときには、X-Rayではなく、OpenTelemetryが試験範囲になるかもしれませんね。
また勉強し直さないと。

以上です。
この記事がどなたかのお役に立てれば幸いです。
もし間違いを見つけた場合は、コメントで教えていただけると助かります。

コメント