ひとことで言うと
1件のリクエストが、複数のサービス（Lambda・API Gateway・Bedrock 呼び出し・下流のツール）をまたいでどこで時間を使ったかを可視化する分散トレーシングです。CloudWatch のメトリクスが「全体としてどれくらい遅いか」を見るのに対し、X-Ray は「この1件がどこで詰まったか」を見ます。
要するに、宅配便の追跡番号です。平均配達時間（メトリクス）ではなく、この荷物が今どの営業所に何分間止まっていたかを1件ずつ追える。エージェント型アプリで「このリクエストだけ遅い」の原因調査に向いています。
なぜ生まれたか
| エージェント型アプリで起きる問題 | X-Ray 側の受け皿 |
|---|---|
| Lambda → Bedrock → 別の Lambda（ツール呼び出し）と処理が連鎖し、どこが遅いか分からない | トレースマップ（サービス間の呼び出し関係と各区間の時間を可視化） |
| モデル呼び出し自体の遅延か、前後の処理の遅延か切り分けたい | セグメント／サブセグメント単位の時間内訳 |
| マルチエージェント協調で、どのエージェント・どのツールが失敗したか特定したい | トレースIDによるリクエストの追跡 |
D2 の 2.4（FM API 統合）で「指数バックオフ・レート制限・X-Ray」、2.5（開発ツール）で「CloudWatch Logs Insights・X-Ray でのトラブルシュート」と明記されており、API 統合のエラー処理・トラブルシュートの文脈で出ます。
何に使うか
| 用途 | 使い方 | 関連ドメイン |
|---|---|---|
| サービスをまたいだ遅延の切り分け | トレースマップでボトルネックのサービスを特定 | D2, D5 |
| Lambda・API Gateway 経由の Bedrock 呼び出しの追跡 | 両サービスとも能動的なインストルメンテーション対応（サンプリング・トレースヘッダ付与） | D2 |
| SNS/SQS/EventBridge を挟む非同期処理の追跡 | パッシブインストルメンテーション（トレースヘッダを伝播するだけ） | D2 |
| AgentCore エージェントのスパン可視化 | AgentCore が X-Ray をトレース配信先として使用（CloudWatch Transaction Search 経由） | D2, D5 |
試験でどう問われるか
| 問われ方 | 正解に寄る条件 | 引っかけ |
|---|---|---|
| 「Lambda 経由で Bedrock を呼ぶ構成で、どのステップが遅いか分からない」 | サービスをまたいだ時間内訳が要る → X-Ray のトレースマップ | CloudWatch のメトリクスだけで足りると考える（メトリクスは集約値で1件を追えない） |
| 「SQS で非同期化した処理のトレースがつながらない」 | SQS はパッシブインストルメンテーション（自分ではトレースを開始しない） → 送信側が X-Ray SDK でトレースしていて初めてヘッダが伝播する | SQS 単体でトレースが自動生成されると誤解する |
| 「AgentCore で動くエージェントのスパンを見たい」 | AgentCore Observability はまず CloudWatch Transaction Search を有効化し、トレースの配信先を X-Ray（CloudWatch Logs 経由）に向ける必要がある | X-Ray コンソールを直接見れば最初から出てくると誤解する |
| 「モデル呼び出しの中身（プロンプト）まで X-Ray で見たい」 | X-Ray は時間の内訳を見るもので、リクエスト本文は記録しない | モデル呼び出しログ（CloudWatch Logs）の代わりになると誤解する |
X-Ray SDK/Daemon は保守モードに移行予定です。公式ドキュメントは、X-Ray の SDK/Daemon が今後セキュリティ修正のみの保守モードに入り、OpenTelemetry（ADOT）への移行を推奨しています。AgentCore の観測性設定も、X-Ray SDK ではなく ADOT（AWS Distro for OpenTelemetry）SDK を使う前提で説明されています。「トレーシング＝X-Ray SDK を組み込む」という前提のまま試験に臨むと、AgentCore 文脈の選択肢で迷います。
実務でどう使うか
- サービスとの統合レベルは一様ではありません。 Lambda・API Gateway は能動的（自動でサンプリング・トレース開始）、SNS・SQS・EventBridge は受動的（上流がトレースしていれば伝播するだけ）。「SQS を挟めば自動でトレースされる」という思い込みは実装時に踏みます
- AgentCore でトレースを見るには一度きりのセットアップが要ります。 CloudWatch Transaction Search の有効化 → トレースセグメントの配信先を CloudWatch Logs に設定 → （必要なら）サンプリング率の調整、という順番
- エージェントのスパンはデフォルトで共有ロググループ（
aws/spans）に入ります。 個々のエージェントごとに専用ロググループへ切り替えたい場合はUNIFIED_TRACES_DESTINATION_ENABLED環境変数で明示的にオプトインが要ります - セッションIDの伝播は自動ではありません。
X-Amzn-Bedrock-AgentCore-Runtime-Session-Idヘッダを自分でリクエストに付ける必要があります
ADOT Collector は AgentCore のエージェント可観測性では非対応です。AgentCore ランタイム外でホストするエージェントにテレメトリを送る場合、使えるのは ADOT SDK か AWS Lambda Layer for OpenTelemetry のみ。「Collector を立てれば済む」という一般的な OpenTelemetry の発想を持ち込むと構成が動きません。
取り違えやすいもの
| 迷う相手 | 切り分けの一言 |
|---|---|
| CloudWatch メトリクス | X-Ray はリクエスト単位の時間内訳。メトリクスは集約された量。「この1件が遅い理由」はX-Ray、「全体として遅くなっている傾向」はメトリクス |
| CloudWatch Logs（モデル呼び出しログ） | X-Ray は時間の内訳を追う。呼び出しログはリクエスト・レスポンスの中身を記録する。役割がそもそも違う |
| CloudTrail | X-Ray はパフォーマンス・遅延の可視化。CloudTrail は「誰が API を呼んだか」の監査証跡。目的の軸が違う |
| AgentCore Observability | AgentCore は専用ダッシュボードで、内部的に X-Ray（トレース配信先）と CloudWatch Logs（スパン格納先）の両方を使う統合レイヤー。X-Ray 単体の代替ではない |
想起チェック
Q1. SQS を経由する非同期処理で、送信側が X-Ray SDK を使っていない場合、受信側のトレースはどうなる？
トレースはつながりません。 SQS は受動的インストルメンテーションなので、送信側がトレースしていて初めてトレーシングヘッダを伝播できます。SQS 自体が自動でトレースを開始するわけではありません。
Q2. AgentCore で動くエージェントのトレースを CloudWatch で見るために、最初に必要な一手間は？
CloudWatch Transaction Search の有効化です。これをしないと AgentCore はスパンを配信できません。有効化後、トレースセグメントの配信先を CloudWatch Logs に設定する必要もあります。
Q3. X-Ray でモデルに送ったプロンプトの内容を確認できる？
できません。 X-Ray はリクエストの時間内訳（どこで何ミリ秒使ったか）を追うもので、本文までは記録しません。プロンプトの中身が要るならモデル呼び出しログ（CloudWatch Logs / S3）を使います。