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

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

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

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

この問題を解決するのが 分散トレーシング であり、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 の場合）

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: X-Ray SDK の組み込み（Python/Node.js）

アプリケーションコードにSDKを組み込むことで、詳細なサブセグメント情報を記録できます。

Python（aws-xray-sdk）:

pip install aws-xray-sdk

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

# AWSクライアント（boto3など）を自動インスツルメント
patch_all()

@xray_recorder.capture('process_order')
def process_order(order_id):
    # この関数の処理がサブセグメントとして記録される
    result = dynamodb.get_item(...)
    return result

Node.js（aws-xray-sdk-node）:

npm install aws-xray-sdk

const AWSXRay = require('aws-xray-sdk');
const AWS = AWSXRay.captureAWS(require('aws-sdk'));

// AWS SDKの呼び出しが自動的にトレースされる
const dynamodb = new AWS.DynamoDB.DocumentClient();
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
  }
}

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

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

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

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

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

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

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

原因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のトレースを紐付けた調査が可能になります。

import logging
from aws_xray_sdk.core import xray_recorder

logger = logging.getLogger()

def handler(event, context):
    trace_id = xray_recorder.current_trace_id()
    logger.info(f"trace_id={trace_id} Processing request")
    # ... 処理 ...

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はデーモン＋SDK組み込みが必要
– サービスマップのノード色とレスポンスタイム分布でヘルス状態を一目確認できる
– サンプリングルールでコストとデータ量のバランスを調整する

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

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

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

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

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

コメント

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