AWS X-Ray

解決する課題

マイクロサービスやサーバーレスでは、1つのリクエストが API Gateway、Lambda、DynamoDB、外部 API など多数のコンポーネントを横断します。ログを個別に見るだけでは「どこで遅いのか」「どのサービスがエラーを返したか」がわかりません。X-Ray は：

• リクエストの流れを1本のトレースとして串刺しで可視化する
• どのサービス間で遅延（レイテンシ）が発生しているかを特定する
• エラーや例外、スロットリングの発生箇所を切り分ける

主要概念と用語

• トレース: 1つのリクエストがシステム全体を通過した記録の集合
• セグメント: 個々のサービスやリソースが行った処理の単位。リクエストの開始から終了までの情報を持つ
• サブセグメント: セグメント内のさらに細かい処理（DynamoDB 呼び出し、外部 HTTP リクエストなど）
• サービスマップ: トレースから自動生成される、サービス間の依存関係と遅延・エラー率を示す図
• トレースヘッダ: リクエスト間でトレース ID を伝播させる HTTP ヘッダ（X-Amzn-Trace-Id）
• サンプリング: 全リクエストではなく一部だけを記録するルール。記録量とコストを制御する
• アノテーション / メタデータ: トレースに付与する情報。アノテーションはインデックス化され検索・フィルタに使える、メタデータは検索対象外の補足情報
• OpenTelemetry Collector / CloudWatch agent: アプリのスパンを受け、加工・バッチ化して X-Ray へ転送する現在の主経路
• X-Ray デーモン: 旧 X-Ray SDK のセグメントを転送する従来エージェント。新規採用せず移行対象として扱う

仕様・制限・クォータ

• トレースデータには保持期間があり、一定期間を過ぎた古いトレースは自動的に削除される
• 1トレースのサイズやセグメントのドキュメントサイズに上限があり、過度に大きなメタデータは送信できない
• アノテーションは検索キーとして使えるが、付与できる項目数には上限がある
• リージョン単位でデータが保持される。クロスリージョンでまたぐ場合は構成に注意する

内部の仕組み

横にスクロール

各サービスやアプリを OpenTelemetry SDK／自動計装で計測し、処理区間をスパンとして生成します。スパンは CloudWatch agent、ADOT Collector、または OpenTelemetry Collector でバッチ化して X-Ray へ送ります。X-Ray 側は共通のトレース ID と親子関係を使い、別プロセスのスパンを1本のトレースとして再構成します。

トレース ID はリクエストの入口で発行され、後続のサービス呼び出しにトレースヘッダとして伝播します。これにより、別々のサービスが出したセグメントが同じトレースに紐づきます。集まったトレースから依存関係を集計し、サービスマップとして遅延やエラー率を可視化します。

• Lambda、API Gateway、ECS、EC2 などの統合と OpenTelemetry 計装を組み合わせられる
• 旧 X-Ray SDK／デーモンからは、計装ライブラリ、伝播形式、転送先を段階的に OpenTelemetry へ置き換える

設計パターン / ベストプラクティス

• OpenTelemetry を標準にする: 新規コードはベンダー固有 SDK ではなく標準計装を使い、Collector 側で X-Ray への送信を構成する
• 入口から計装する: API Gateway やロードバランサなど、リクエストの最前段で計装してトレース ID を発行する
• サンプリングルールを設計する: 重要なエンドポイントは記録率を上げ、ヘルスチェックなど不要なものは記録しない
• アノテーションでビジネス文脈を付与: ユーザー種別やテナント、処理結果などを付けて後から絞り込めるようにする
• CloudWatch との併用: X-Ray でボトルネックを特定し、CloudWatch のメトリクス・ログで原因を深掘りする

運用・監視

• サービスマップで遅延が大きいエッジ（サービス間の矢印）やエラー率が高いノードを起点に調査する
• フィルタ式でエラーを含むトレース、特定アノテーションを持つトレースだけを抽出する
• レイテンシ分布（ヒストグラム）で外れ値の遅いリクエストを見つける
• トレースが届かない場合は、OpenTelemetry の計装、Collector／CloudWatch agent、IAM 権限、サンプリング設定を順に確認する

コスト

• 課金は主に記録されたトレース数と、取得・スキャンしたトレース数に基づく
• 一定量までの無料利用枠が用意されている
• 全件トレースはコストを押し上げるため、サンプリングで記録量を抑えるのが基本
• 不要なエンドポイント（ヘルスチェック等）をサンプリング対象から外すと効果的

セキュリティ

• Collector／CloudWatch agent には IAM ロールを付与し、X-Ray への送信権限を最小権限で与える
• トレースに個人情報や機密値を入れない。メタデータやアノテーションに認証情報を含めないよう注意する
• データは保存時に暗号化され、KMS の管理キーを使った暗号化も選択できる
• API 操作の監査は CloudTrail で記録する

Well-Architected の観点

• 運用上の優秀性: リクエスト単位のトレースで観測性を高め、障害調査の時間を短縮する
• パフォーマンス効率: サービスマップとレイテンシ分布でボトルネックを特定し継続的に改善する
• セキュリティ: 最小権限の IAM、機密値の非送信、暗号化で保護する
• コスト最適化: サンプリングで記録量を制御し過剰な課金を避ける

試験で問われるポイント

関連サービス・比較

性能・ログ監視の中核である CloudWatch とよく対比されます。両者は競合ではなく補完関係です。

ハンズオン / CLI例

# サンプリングルールを作成（特定パスを高い割合で記録）
aws xray create-sampling-rule --sampling-rule '{
  "RuleName": "high-priority",
  "Priority": 100,
  "FixedRate": 0.5,
  "ReservoirSize": 5,
  "ServiceName": "*",
  "ServiceType": "*",
  "Host": "*",
  "HTTPMethod": "*",
  "URLPath": "/api/checkout*",
  "ResourceARN": "*",
  "Version": 1
}'

# 直近のトレース概要を取得し、サービスマップ用のグラフを確認
aws xray get-trace-summaries \
  --start-time 1718200000 --end-time 1718203600 \
  --filter-expression 'error = true'