X-Ray

X-Ray とは

AWS X-Ray は、分散トレーシングサービスで、リクエストが API Gateway → Lambda → DynamoDB のようにどのサービスを通過し、どこで時間がかかっているかを可視化する。マイクロサービスやサーバーレスアーキテクチャのパフォーマンス分析とデバッグに使う。

トレースマップ

トレースマップは、集めたセグメントをサービス単位のノードと呼び出し関係のエッジに集約した図で、ノードごとの平均レイテンシとエラー率が載る。

[API Gateway] → [Lambda A] → [DynamoDB]
  50ms            120ms         30ms
                             → [Lambda B] → [SQS]
                                80ms         10ms
合計: 170ms

エッジに出る時間は呼び出し元から見た往復時間なので、下流ノード自身が報告する処理時間より必ず長い。この差が大きい区間はネットワークやキューでの待ちを疑う。

Tracing: Active で Lambda の X-Ray トレーシングが有効になる。指定しない場合は PassThrough で、トレース用のヘッダーは下流へ渡すが Lambda 自身はトレースを送らない。

トレースの構造

X-Ray のトレースは 1 つのリクエスト全体を表す。計装済みのサービスはそれぞれ自分のセグメントを送り、同じトレース ID を持つセグメントが 1 本のトレースにまとまる。サブセグメントはセグメントの内側の細かい処理、とくに呼び出し元から見た下流呼び出しの記録である。

Trace (1 リクエスト全体)
  ├── Segment (API Gateway)
  │     └── Subsegment (Lambda 呼び出し: 呼び出し元から見た往復時間)
  ├── Segment (AWS::Lambda: 実行環境の準備)
  └── Segment (AWS::Lambda::Function: 関数本体の処理)
        ├── Subsegment (DynamoDB GetItem: 30ms)
        └── Subsegment (外部 API 呼び出し: 200ms) ← ボトルネック

下流サービスをセグメントの入れ子と読むと構造を取り違える。Lambda を呼ぶ場合、Lambda は実行環境の準備を表す AWS::Lambda と関数本体の処理を表す AWS::Lambda::Function の 2 つのセグメントを送るので、マップ上のノードも 2 つ並ぶ。前者にエラーが出ていれば Lambda サービス側、後者なら自分のコード側という切り分けができる。DynamoDB のように自分でセグメントを送らないサービスは、呼び出し元のサブセグメントから推論されたノードとして描かれる。下流が計装済みなら、その下流自身のセグメントが推論されたノードを置き換える。

CloudWatch との連携

X-Ray の画面は CloudWatch コンソールに統合されており、トレースからログ、メトリクスへ同じ画面で辿れる。役割分担は次のとおり。

3 つを組み合わせてオブザーバビリティを実現する。

2026 年 8 月時点では Transaction Search を有効にすると、全スパンを 100% 構造化ログとして aws/spans ロググループへ取り込み、そのうち指定した割合だけをトレースサマリーとして索引する構成が取れる。ログ側には全件残るため、サンプリングから漏れた低頻度のエラーも後から検索できる。この仕組みは CloudWatch Application Signals の性能監視画面の土台にもなっている。

サンプリング

全リクエストをトレースするとコストが増加する。サンプリングルールで一部のリクエストのみトレースする。

{
  "version": 2,
  "default": { "fixed_target": 1, "rate": 0.05 }
}

1 秒あたり 1 リクエスト + 残りの 5% をサンプリング。これが既定値で、コストを抑えるため意図的に控えめに設定されている。

fixed_target は 1 秒あたり必ずトレースする件数 (リザーバ)、rate はそれを超えた分に適用する割合である。同じ 5% を JSON では 0.05 と小数で書き、コンソールでは 5 とパーセントで入力するため、写し間違えると桁が 100 倍ずれる。

落とし穴は判定が行われる場所である。サンプリングするかどうかはリクエストが最初に到達した計装済みサービスで一度だけ決まり、結果は X-Amzn-Trace-Id ヘッダーの Sampled として下流へ伝わる。下流はその判定に従うので、下流側にだけルールを足しても効かないことが多い。Lambda 関数自身のサンプリングレートは変更できず、上流の判定に従う点も押さえておきたい。

Lambda Powertools との統合

Powertools のトレーサーはデコレーターでメソッドを包み、関数本体のセグメントの下にサブセグメントを自動で足す。

import { Tracer } from '@aws-lambda-powertools/tracer';
const tracer = new Tracer();

class MyHandler {
  @tracer.captureMethod()
  async getUser(id: string) { /* 自動的にサブセグメントが作成される */ }
}

検索の対象にしたい値は annotation (キーと値のペア) として付ける。annotation はフィルター式で絞り込める代わりにトレース単位で 50 個までしか索引されず、索引が要らない構造体は metadata へ回す。metadata はトレース詳細画面で読めるがフィルター式では絞り込めない。

2026 年 8 月時点の位置づけ

X-Ray SDK と X-Ray デーモンは 2026 年 2 月 25 日に一般提供が終了してメンテナンスモードへ入り、以降はセキュリティ修正のみが提供され新機能は追加されない。AWS は計装を OpenTelemetry へ移すことを推奨しており、新しく組むなら ADOT (AWS Distro for OpenTelemetry) や CloudWatch エージェント経由でトレースを送る構成を選ぶ。X-Ray 自体はトレースの保存と可視化のバックエンドとして残るため、移行の実務は計装ライブラリと送信経路の入れ替えが中心になる。既存の SDK ベースの構成が動いていても、機能追加が来ない前提で移行時期を決めておきたい。なおトレースとサービスグラフの保持期間は 30 日で、それより長く残したい場合は別途エクスポートが必要になる。