AWS X-Ray

解決する課題

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

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

主要概念と用語

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

仕様・制限・クォータ

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

内部の仕組み

各サービスやアプリに組み込んだ SDK（または計装ライブラリ）が、処理ごとにセグメントを生成します。セグメントはまず X-Ray デーモンへ送られ、デーモンがバッファリングして X-Ray サービスへバッチ送信します。X-Ray 側は受け取ったセグメントを共通のトレース ID で束ね、1本のトレースとして再構成します。

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

• Lambda、API Gateway、ECS、EC2 など多くのサービスと統合され、計装を有効化するだけでトレースが流れる
• AWS Distro for OpenTelemetry（ADOT）経由でも X-Ray にトレースを送信できる

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

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

運用・監視

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

コスト

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

セキュリティ

• アプリやデーモンには 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'