AWS X-Rayとは？分散トレーシングの仕組みと設定手順【入門ガイド】

AWS監視・オブザーバビリティ
2026.04.18

マイクロサービス構成で障害が起きたとき、「どのサービスでエラーが発生したのか」を特定するのに何時間もかかった経験はないでしょうか。

ログを各サービスで個別に確認し、タイムスタンプを突き合わせ、原因にたどり着く頃には深夜になっている——このような状況は、分散システムを運用するチームでよくあるパターンです。

この問題を解決するのが 分散トレーシング であり、AWSが提供するマネージドサービスが AWS X-Ray です。この記事では、AWS X-Rayの仕組みから設定手順まで、実務で即使えるレベルで解説します。

この記事でわかること
– 分散トレーシングとAWS X-Rayの基本概念
– セグメント・サブセグメント・サービスマップの読み方
– X-Ray SDKの組み込みとデーモンの設定手順
– サンプリングルールの設計指針
– 本番運用でのベストプラクティス

前提条件: AWS基礎知識（IAM・Lambda・EC2いずれかの操作経験）があると理解しやすい内容です。

microservices distributed system architecture overview, multiple connected service nodes with reques

AWS X-Rayとは何か

AWS X-Rayは、分散アプリケーションのリクエストを追跡・可視化するマネージドサービスです。

従来のメトリクス監視（CloudWatch）やログ監視では「何かがおかしい」という事実は検知できますが、「どのサービスのどの処理でボトルネックが発生しているか」を特定するには限界があります。X-Rayはこのギャップを埋めます。

graph TD

  A["クライアント
（ブラウザ/API）"]

  B["API Gateway"]

  C["Lambda
（認証サービス）"]

  D["Lambda
（注文サービス）"]

  E["RDS
（データベース）"]

  F["SNS
（通知サービス）"]

  A --> B --> C --> D --> E

  D --> F

このような構成でリクエストが流れるとき、X-Rayは各サービス間の処理時間・エラー率・スロットルをトレースとして記録し、サービスマップとして可視化します。

CloudWatchとの違いと使い分け

項目 CloudWatch AWS X-Ray
観測対象 メトリクス・ログ リクエストの流れ（トレース）
強み 時系列の傾向把握・アラート 原因サービスの特定・レイテンシ分析
主な用途 「いつ異常が起きたか」 「どこで異常が起きたか」
組み合わせ X-Rayのトレースデータ→CloudWatchに連携可能

CloudWatchで「エラーレートが上昇した」と検知したあと、X-Rayで「どのサービスで何ミリ秒かかっているか」を掘り下げる——この2段階の運用が実務標準です。

X-Ray trace hierarchy diagram showing Trace containing Segments and Subsegments as nested boxes, eac

X-Rayの基本概念：トレース・セグメント・サブセグメント

X-Rayを使いこなすには3つのデータ構造を理解する必要があります。

トレース（Trace）

1つのリクエストの処理全体を記録したものがトレースです。クライアントからのリクエストが複数のサービスを経由して完了するまでの、すべての処理記録が1つのトレースIDで紐付けられます。

セグメント（Segment）

トレースを構成する各サービスの処理単位がセグメントです。たとえばLambda関数1つがセグメント1つに相当します。セグメントには以下の情報が含まれます。

  • 開始時刻・終了時刻（レイテンシの計算に使用）
  • HTTP ステータスコード
  • エラー・フォールト・スロットルのフラグ
  • メタデータ（任意の追加情報）

サブセグメント（Subsegment）

セグメント内のさらに細かい処理単位がサブセグメントです。たとえば「DynamoDBへのクエリ」「外部APIへのHTTPリクエスト」などをサブセグメントとして記録することで、どの処理がボトルネックになっているかを特定できます。

Trace（リクエスト全体）
├── Segment: API Gateway （12ms）
├── Segment: Lambda（認証） （45ms）
│   ├── Subsegment: DynamoDB GetItem （38ms） ← ここが遅い
│   └── Subsegment: JWT検証ロジック （5ms）
└── Segment: Lambda（注文処理） （23ms）

この例では「DynamoDB GetItemが38ms」とひと目でわかるため、チューニングの優先順位がすぐに決まります。

AWS X-Ray setup flow diagram, three steps: IAM role configuration, X-Ray daemon installation, SDK in

X-Rayの設定手順

Step 1: IAMポリシーの設定

X-Rayへのデータ送信には xray:PutTraceSegments と xray:PutTelemetryRecords の権限が必要です。Lambda・EC2・ECSそれぞれの実行ロールにAWS管理ポリシー AWSXRayDaemonWriteAccess をアタッチしてください。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "xray:PutTraceSegments",
        "xray:PutTelemetryRecords",
        "xray:GetSamplingRules",
        "xray:GetSamplingTargets"
      ],
      "Resource": "*"
    }
  ]
}

Step 2: X-Ray デーモンの設定（EC2/ECS の場合）

⚠️ X-Ray Daemon について
X-Ray Daemon はメンテナンスモードへ移行しています。新規実装では ADOT Collector の使用を推奨します。詳細は AWS公式ドキュメント を参照してください。

EC2やECSで動くアプリケーションの場合、X-Rayデーモンがローカルのポート 2000/UDP でトレースデータを受け取り、X-Ray APIに転送します。

# EC2でX-Rayデーモンをインストール・起動
wget https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm
sudo rpm -U aws-xray-daemon-3.x.rpm
sudo systemctl start xray

ECSの場合はサイドカーコンテナとしてデーモンを起動するのが標準パターンです。

# docker-compose例（ローカル開発用）
services:
  xray-daemon:
    image: amazon/aws-xray-daemon
    ports:
      - "2000:2000/udp"
    command: "-o"  # ローカル開発時はEC2メタデータをスキップ

Lambdaの場合はデーモン不要です。コンソールまたはSAM/CDKで Tracing: Active を設定するだけで有効化されます。

# SAM template.yaml
Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active  # これだけ

Step 3: アプリケーションの計装（AWS Distro for OpenTelemetry）

アプリケーションコードにトレース計装を組み込むことで、詳細なサブセグメント情報を記録できます。現在AWSは AWS Distro for OpenTelemetry（ADOT） を使った計装を推奨しています。

⚠️ X-Ray SDK について
X-Ray SDK（Python/Node.js等）は2026年2月よりメンテナンスモードへ移行しています。新規実装では ADOT / OpenTelemetry SDK の使用を推奨します。詳細はOpenTelemetryとADOTの解説記事を参照してください。

ADOT を使った Python の計装例：

pip install opentelemetry-sdk opentelemetry-instrumentation-botocore aws-opentelemetry-distro

from opentelemetry import trace
from opentelemetry.instrumentation.botocore import BotocoreInstrumentor

# AWSクライアントを自動インスツルメント
BotocoreInstrumentor().instrument()

tracer = trace.get_tracer(__name__)

def process_order(order_id):
    with tracer.start_as_current_span("process_order") as span:
        span.set_attribute("order.id", order_id)
        result = dynamodb.get_item(...)
        return result

Node.js の計装例：

npm install @opentelemetry/sdk-node @opentelemetry/instrumentation-aws-sdk

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { AwsInstrumentation } = require('@opentelemetry/instrumentation-aws-sdk');

const sdk = new NodeSDK({
  instrumentations: [new AwsInstrumentation()],
});
sdk.start();
// 以降のAWS SDK呼び出しは自動的にトレースされる

ADOTの詳細な設定方法（Collectorの構成・X-Rayへのエクスポート設定）は OpenTelemetryとADOTの解説記事 を参照してください。

AWS X-Ray service map console screenshot style illustration, circular nodes with green/yellow/red he

サービスマップの読み方

X-Rayコンソールの サービスマップ は、各サービスのヘルス状態をリアルタイムで可視化します。

ノードの色の意味

色 意味
緑 正常（エラーなし）
黄 スロットル（4xx エラー）
赤 フォールト（5xx エラー）
灰 データなし（トレース未計測）

レスポンスタイム分布の見方

各ノードにはレスポンスタイムのヒストグラムが表示されます。95パーセンタイル（p95）が平均値と大きく乖離している場合、一部のリクエストで極端に遅い処理が発生している（テールレイテンシ問題）サインです。

正常なパターン:  p50=50ms, p95=80ms, p99=100ms  → 差が小さい
問題のあるパターン: p50=50ms, p95=500ms, p99=2000ms → p95以降が跳ね上がる

テールレイテンシが大きい場合は、X-Rayのトレース一覧でレスポンスタイムの降順に並べ替え、遅いリクエストのサブセグメントを確認することで原因を特定できます。

サンプリングルールの設計

本番環境で全リクエストをトレースするとコストが大きくなります。X-Rayのサンプリングルールで「どのリクエストをどの割合でトレースするか」を制御します。

デフォルトルール

デフォルトでは「毎秒最初の1リクエスト＋それ以降は5%」がサンプリングされます。

デフォルトルール:
  - 1リクエスト/秒（リザーバー）は必ずトレース
  - それ以上のリクエストは5%をランダムサンプリング

カスタムルールの設定例

重要なAPIパスは高めのサンプリングレートを設定し、ヘルスチェックのような低価値なリクエストは除外するのが実務の定石です。

{
  "version": 2,
  "rules": [
    {
      "description": "決済APIは高めにサンプリング",
      "host": "*",
      "http_method": "POST",
      "url_path": "/api/payment/*",
      "fixed_target": 10,
      "rate": 0.5
    },
    {
      "description": "ヘルスチェックはスキップ",
      "host": "*",
      "http_method": "GET",
      "url_path": "/health",
      "fixed_target": 0,
      "rate": 0
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.05
  }
}

Adaptive Sampling（発展）

X-Ray Adaptive Samplingは、トラフィックパターンを自動的に学習し、サンプリングレートを動的に調整する機能です。

  • Sampling Boost: 急激なリクエスト増加やレイテンシ上昇を検知した際に、自動でサンプリング率を引き上げ、問題の状況を見逃さないようにします
  • Anomaly Span Capture: エラーや異常なレイテンシを示すスパンが発生した場合、そのトレース全体を優先的にキャプチャします

本番環境では、重要なイベント（エラー・スロットル・高レイテンシ）が発生したタイミングほどトレースデータが必要です。Adaptive Samplingを活用することで、静かな時間帯はコストを抑えつつ、問題発生時には自動的に詳細なトレースを収集できます。

💡 Adaptive Samplingは [X-Ray コンソール] → [サンプリングルール] → [インサイトの有効化] から設定できます。

よくあるエラーとトラブルシューティング

トレースデータがコンソールに表示されない

原因1: IAM権限不足
実行ロールに xray:PutTraceSegments が付与されているか確認します。

# IAMロールのポリシーを確認
aws iam list-attached-role-policies --role-name your-lambda-role

原因2: デーモンへの接続失敗（EC2/ECSでX-Ray Daemon使用時）
X-Ray Daemon を使用している場合、デーモンがUDPポート2000でリッスンしているか確認します。

# デーモンの状態確認
sudo systemctl status xray

# ポートのリッスン確認
sudo netstat -ulnp | grep 2000

💡 ADOT Collector を使用している場合 は、Daemon ではなく OTLP エンドポイント（デフォルト: 4317/grpc または 4318/http）の設定を確認してください。ADOT設定ガイドはこちら

原因3: サンプリングレートが低すぎる
開発環境では一時的にサンプリングレートを100%に上げて動作確認します。

セグメントの一部しか表示されない

X-Rayデーモンへのデータ送信に失敗したセグメントは表示されません。CloudWatch Logsでデーモンのログを確認してください。

# X-Rayデーモンのログ確認
sudo tail -f /var/log/xray/xray.log

本番環境でのベストプラクティス

1. X-Ray Insightsを有効化する

X-Ray Insightsは、トレースデータを自動分析してレイテンシ異常やエラーレートの変化を検知する機能です。有効化するだけで異常検知のアラートが得られるため、設定コストが低いわりに効果が大きい機能です。

2. トレースIDをログに含める

X-RayのトレースIDをアプリケーションログに含めることで、CloudWatch LogsとX-Rayのトレースを紐付けた調査が可能になります。OpenTelemetry APIを使った実装例は以下の通りです。

import logging
from opentelemetry import trace

logger = logging.getLogger()

def handler(event, context):
    span = trace.get_current_span()
    trace_id = format(span.get_span_context().trace_id, '032x')
    logger.info(f"trace_id={trace_id} Processing request")
    # ... 処理 ...

ログとトレースの紐付けにより、CloudWatch Logsのログ検索からX-Rayのトレース詳細へ直接ジャンプできるようになります。

3. OpenTelemetryとの統合を検討する

AWS Distro for OpenTelemetry（ADOT）を使うと、X-Ray形式とOTLP形式の両方でトレースを送信できます。将来的にDatadogやJaegerへの移行を検討している場合、最初からOpenTelemetry準拠で実装しておくとベンダーロックインを避けられます。

graph TD

  A["アプリケーション
（SDK組み込み）"]

  B["ADOT Collector"]

  C["AWS X-Ray"]

  D["Amazon CloudWatch"]

  E["外部ツール
（Datadog/Jaeger等）"]

  A --> B

  B --> C

  B --> D

  B --> E

まとめ

この記事では、AWS X-Rayを使った分散トレーシングの基礎から実装手順までを解説しました。

ポイントの整理
– X-Rayは「どのサービスのどの処理が遅いか・エラーを出しているか」を可視化するサービス
– データ構造はトレース→セグメント→サブセグメントの3階層
– LambdaはActiveトレーシングをONにするだけ、EC2/ECSはデーモン＋計装が必要
– 計装の実装にはADOT（AWS Distro for OpenTelemetry）を推奨。X-Ray SDK・X-Ray Daemonはともにメンテナンスモードへ移行済み（公式ドキュメント）
– サービスマップのノード色とレスポンスタイム分布でヘルス状態を一目確認できる
– サンプリングルールでトレースのコスト（保存量）を調整する。性能への影響は実質ゼロ
– Adaptive Samplingを活用すると、問題発生時に自動でサンプリング率を引き上げられる

分散トレーシングはオブザーバビリティの3本柱（メトリクス・ログ・トレース）の中でも、マイクロサービス環境では特に効果が高い施策です。CloudWatchのメトリクス監視と組み合わせることで、検知から原因特定までの時間を大幅に短縮できます。

AWSのオブザーバビリティ設計をゼロから体系的に学びたい方は、以下のUdemyコースも参考にしてください。CloudWatch・X-Ray・OpenTelemetryを使った実践的な監視設計を動画で学べます。

📚 SRE実務で使えるAWS監視設計を動画で学ぶ

AWS SRE実践コース – 監視・オブザーバビリティ完全ガイド（Udemy）

CloudWatch・X-Ray・コスト最適化まで、実務ベースのハンズオンで習得できます。

コメント

タイトルとURLをコピーしました