AWS X-Rayの使い方｜Lambda・APIのトレースとサービスマップ

AWS X-Ray は、1つのリクエストが API Gateway → Lambda → DynamoDB のように複数のサービスを通る道のりを記録し、どこで時間がかかったか・どこで失敗したかを見せるサービスです。 Lambda と API Gateway（REST API）は設定を1つ変えるだけでトレースが始まり、サービス同士のつながりは「サービスマップ（トレースマップ）」として図になります。

# Lambda：アクティブトレースを有効にする
aws lambda update-function-configuration --function-name orders-api \
  --tracing-config Mode=Active

# API Gateway（REST API）：ステージで有効にする
aws apigateway update-stage --rest-api-id abc123 --stage-name prod \
  --patch-operations op=replace,path=/tracingEnabled,value=true

確認環境：aws-xray-sdk 2.15.0・aws-lambda-powertools 3.35.0・boto3 1.43.112・moto 5.2.4・Python 3.11（Linux）。UDP 2000 番で受ける擬似の X-Ray デーモンを Python で書き、SDK が送るセグメントの JSON を受け取りました。TCP 2000 番には、サンプリングルールを返す擬似のエンドポイントを立てて、SDK のルール取得とサンプリングの結果を数えました。boto3 の呼び出しは moto の DynamoDB に向け、自動で付くサブセグメントを確かめています。有効化の手順・サンプリングの既定値・上限・移行の方針は AWS のドキュメントで確認しました（確認日 2026年10月13日）。

X-Ray の用語：セグメント・サブセグメント・注釈・メタデータ

注釈とメタデータの違いは「フィルター式で探せるかどうか」です。

トレースIDは 1- ＋ リクエスト時刻（Unix 秒の 16 進 8 桁）＋ 96 ビットの乱数（16 進 24 桁）です。サービスの間では HTTP ヘッダー X-Amzn-Trace-Id で受け渡されます。

X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1

有効化①：Lambda

CLI・SAM・CloudFormation

aws lambda update-function-configuration --function-name orders-api \
  --tracing-config Mode=Active

aws lambda get-function-configuration --function-name orders-api \
  --query TracingConfig        # {"Mode": "Active"}

# SAM
Resources:
  OrdersFunction:
    Type: AWS::Serverless::Function
    Properties:
      Tracing: Active

# CloudFormation（AWS::Lambda::Function）
      TracingConfig:
        Mode: Active

実行ロールに X-Ray へ書き込む権限が要ります。 コンソールで有効にすると Lambda が自動で足しますが、CLI・IaC では自分で付けます。

aws iam attach-role-policy --role-name orders-api-role \
  --policy-arn arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess
# 中身は xray:PutTraceSegments・xray:PutTelemetryRecords など

Lambda が作るセグメント

1回の呼び出しで、Lambda は2つのセグメントを作ります。

関数のセグメントの中は、ドキュメントでは2つの形が説明されています。

ドキュメントには、中国と GovCloud 以外のリージョンで新しい形へ順に切り替えていると書かれています。Initialization（Init）が長いトレースはコールドスタートです。対策は関連記事「Lambdaコールドスタート対策｜SnapStartとプロビジョンド同時実行の比較」で扱っています。

Lambda に用意される環境変数

Lambda の中では、デーモンを自分で動かす作業はありません。SDK はこの環境変数の宛先へ UDP で送ります。

有効化②：API Gateway（REST API）

# 作成済みのステージで有効にする
aws apigateway update-stage --rest-api-id abc123 --stage-name prod \
  --patch-operations op=replace,path=/tracingEnabled,value=true

# ステージを作るときに有効にする
aws apigateway create-stage --rest-api-id abc123 --stage-name prod \
  --deployment-id dep123 --tracing-enabled=true

有効にすると、AWSServiceRoleForAPIGateway（サービスリンクロール）が無ければ作られます。HTTP API は X-Ray に対応していません。 HTTP API の後ろの Lambda でアクティブトレースを有効にすると、Lambda から先は記録されます。REST API と HTTP API の違いは、関連記事「API Gateway Lambda｜REST APIとHTTP APIの違い」で扱っています。

ECS・EC2 で動くアプリは、X-Ray デーモン（または CloudWatch エージェント・OpenTelemetry Collector）を横で動かし、アプリの SDK からそこへ送ります。

Python の X-Ray SDK（aws-xray-sdk）

Lambda の中で使う

pip install aws-xray-sdk

import boto3
from aws_xray_sdk.core import xray_recorder, patch_all

patch_all()                     # boto3・requests などを自動で記録する
ddb = boto3.client("dynamodb")

@xray_recorder.capture("load_order")     # 関数をサブセグメントにする
def load_order(order_id):
    xray_recorder.put_annotation("order_id", order_id)
    item = ddb.get_item(TableName="orders", Key={"id": {"S": order_id}})
    xray_recorder.put_metadata("item", item.get("Item"), "orders")
    return item

def lambda_handler(event, context):
    # Lambda がセグメントを作るので begin_segment は呼ばない
    xray_recorder.put_annotation("customer_id", event.get("customer_id", "unknown"))
    load_order(event["order_id"])
    return {"ok": True}

Lambda の中では、関数のセグメントは Lambda が作ります。 コードからは、その下にサブセグメントを足すだけです。Powertools の Tracer を使うと、同じことをデコレーターで書けます。関連記事「Lambda Powertools Pythonの使い方｜Logger・Tracer」で扱っています。

デーモンに届く中身（実物）

Lambda の外で、セグメントを自分で開いて送った例です。サブセグメントの中で boto3（moto の DynamoDB）を呼び、別のサブセグメントで例外を起こしました。

from aws_xray_sdk.core import xray_recorder, patch
xray_recorder.configure(service="orders-api", sampling=False)   # 全部記録
patch(["boto3"])

seg = xray_recorder.begin_segment("orders-api")
seg.put_http_meta("method", "GET")
seg.put_http_meta("url", "https://api.example.com/orders/1")
xray_recorder.put_annotation("customer_id", "c-001")

with xray_recorder.in_subsegment("load_order") as sub:
    sub.put_annotation("order_id", "1")
    sub.put_metadata("raw", {"id": "1", "qty": 2}, "orders")
    ddb.get_item(TableName="orders", Key={"id": {"S": "1"}})

try:
    with xray_recorder.in_subsegment("charge"):
        raise ValueError("card declined")
except ValueError:
    pass

seg.put_http_meta("status", 502)
xray_recorder.end_segment()

UDP 2000 番で受け取ったデータです（1つのデータグラム、1,861 バイト。見やすく改行し、一部を ... で省いています。ID は実行ごとに変わります）。

{"format":"json","version":1}
{"id": "0f675dd47872f47b", "name": "orders-api",
 "http": {"request": {"method": "GET", "url": "https://api.example.com/orders/1"}, "response": {"status": 502}},
 "annotations": {"customer_id": "c-001"},
 "aws": {"xray": {"sdk": "X-Ray for Python", "sdk_version": "2.15.0"}},
 "subsegments": [
   {"id": "57fe305a7b3855c8", "name": "load_order", "parent_id": "0f675dd47872f47b",
    "annotations": {"order_id": "1"},
    "metadata": {"orders": {"raw": {"id": "1", "qty": 2}}},
    "subsegments": [
      {"id": "7bd4c65ded92ac96", "name": "dynamodb", "parent_id": "57fe305a7b3855c8",
       "http": {"response": {"status": 200}},
       "aws": {"operation": "GetItem", "region": "ap-northeast-1", "request_id": "o711ustJC9...", "table_name": "orders"},
       "type": "subsegment", "namespace": "aws", ...}],
    "type": "subsegment", "namespace": "local", ...},
   {"id": "692fa3333e441afe", "name": "charge", "parent_id": "0f675dd47872f47b",
    "cause": {"working_directory": "/var/task",
              "exceptions": [{"id": "80386ab557fe43b8", "message": "card declined", "type": "ValueError",
                              "remote": false, "stack": [{"path": "app.py", "line": 19, "label": "<module>"}]}]},
    "type": "subsegment", "namespace": "local", "fault": true, ...}],
 "trace_id": "1-6acdc654-2f4c235ac0840c2053e10411",
 "service": {"runtime": "CPython", "runtime_version": "3.11.15"},
 "fault": true, ...}

Lambda の中で動かしたとき（環境変数 AWS_LAMBDA_FUNCTION_NAME と _X_AMZN_TRACE_ID を与えたとき）は、セグメントではなくサブセグメントが1つずつ、"type": "subsegment" と trace_id・parent_id 付きで送られました。parent_id は _X_AMZN_TRACE_ID の Parent の値でした。ドキュメントでいう「独立したサブセグメント」の形です。

セグメントが大きすぎると黙って落ちる

セグメント文書の上限は 64 KB です。 70,000 文字のメタデータを入れて end_segment() すると、SDK は次のログを出して送るのをあきらめ、処理はそのまま続きました（デーモンには何も届かない）。

Failed to send entity to Daemon.
Traceback (most recent call last):
  ...
  File ".../aws_xray_sdk/core/emitters/udp_emitter.py", line 63, in _send_data
    self._socket.sendto(data.encode('utf-8'), (self._ip, self._port))
OSError: [Errno 90] Message too long

大きなレスポンスや本文はメタデータに入れず、件数や ID だけを入れます。

セグメントが無いとき（context missing）

セグメントを開く前に記録しようとしたときの動きです。

patch_all() したあと、セグメントの外（モジュールの読み込み時など）で boto3 を呼ぶと、No segment found, cannot begin subsegment dynamodb. が出ます。Lambda の初期化処理でよく見るメッセージで、処理自体は失敗しません。

SDK の環境変数

サンプリングルール

すべてのリクエストを記録すると料金が増えるため、X-Ray は一部だけを記録します。 既定のルールは「1秒に最初の1件（リザーバー）＋それを超えた分の 5%（レート）」です。

ヘルスチェックを記録しないルール

{
  "SamplingRule": {
    "RuleName": "health",
    "ResourceARN": "*",
    "Priority": 1,
    "FixedRate": 0.0,
    "ReservoirSize": 0,
    "ServiceName": "*",
    "ServiceType": "*",
    "Host": "*",
    "HTTPMethod": "GET",
    "URLPath": "/health",
    "Version": 1
  }
}

aws xray create-sampling-rule --cli-input-json file://health.json
aws xray get-sampling-rules --query 'SamplingRuleRecords[].SamplingRule.[RuleName,Priority,ReservoirSize,FixedRate]' --output table

ドキュメントの get-sampling-rules の出力例では、Default ルールは Priority: 10000・ReservoirSize: 1・FixedRate: 0.05 です。

SDK がルールを取りに行く様子

X-Ray SDK は、最初にサンプリングの判断をした時点で、デーモンの TCP 2000 番 に POST /GetSamplingRules を送りました（擬似のエンドポイントで受信）。上の health ルールと Default ルールを返し、/health と /orders をそれぞれ 200 回判定させた結果です。

POST /GetSamplingRules {}
Counter({('/health', False): 200, ('/orders', False): 192, ('/orders', True): 8})

/health は1件も記録されず、/orders は 200 件中 8 件が記録対象になりました。ルールの取得前（最初の1回）は、SDK に入っている既定のルールで判断されます。

トレースの読み方

コンソールで見る順番

1. サービスマップ（トレースマップ）：丸がサービス、線が呼び出し。丸の色の割合で、正常・エラー（4xx）・障害（5xx）・スロットリング（429）が分かる
2. 気になる丸や線を選び、トレースの一覧で遅いもの・失敗したものを絞る
3. タイムラインで、どのサブセグメントが長いか、どこで fault が付いたかを見る
4. 例外はサブセグメントの「Exceptions」に、注釈・メタデータはそれぞれのタブに出る

フィルター式の早見表

CLI でトレースを探す

# 直近 1 時間の 5xx を含むトレース
aws xray get-trace-summaries \
  --start-time $(date -d '-1 hour' +%s) --end-time $(date +%s) \
  --filter-expression 'service() { fault }' \
  --query 'TraceSummaries[].[Id,ResponseTime,Http.HttpStatus]' --output table

# 1つのトレースの中身（セグメントの JSON）
aws xray batch-get-traces --trace-ids 1-6acdc654-2f4c235ac0840c2053e10411 \
  | jq -r '.Traces[0].Segments[].Document | fromjson | [.name, (.end_time - .start_time), (.fault // false)] | @tsv'

moto 5.2.4 で試すと、put-trace-segments・get-trace-summaries・batch-get-traces・get-service-graph は動き、create-sampling-rule・get-sampling-rules・create-group は Not yet implemented でした。テストでサンプリングルールを扱うときは、Stubber などで応答を用意します。

ログとトレースを結びつけると、原因を探す時間が短くなります。Lambda のログに _X_AMZN_TRACE_ID のトレースIDを入れておくと、CloudWatch Logs Insights で同じ ID のログを探せます。関連記事「CloudWatch Logs Insightsのクエリ集｜エラー・遅いリクエスト」で扱っています。

X-Ray SDK から OpenTelemetry へ

ドキュメントでは、X-Ray SDK とデーモンは 2026年2月25日に保守モードに入り、セキュリティの修正だけになると書かれています。 新しいアプリにも既存のアプリにも、OpenTelemetry（OTel）で計装し、X-Ray（CloudWatch）に送る形が勧められています。移行しても CloudWatch での見え方は変わらない、と説明されています。

OTel のスパンの属性は、既定では X-Ray のメタデータになります。注釈にしたい属性は、キーを aws.xray.annotations の一覧に入れます。

今の X-Ray SDK のコードがすぐ止まるわけではありません。新しく書くコードから OTel を使い、既存の関数は作り直すときに移す、という順番が取りやすい方法です。OpenTelemetry の Python での書き方は、関連記事「OpenTelemetry入門｜Pythonで始めるトレース・メトリクス実装」で扱っています。

上限と料金

Lambda は 1秒1件＋5% で記録するため、毎秒 100 リクエストが続く API でも、記録されるのは毎秒およそ 1＋99×0.05 ≒ 6 件です。料金の確かめ方は、関連記事「AWSの料金を確認する方法｜Cost Explorer・CLI・予算アラート」で扱っています。

よくある質問

Q. 有効にしたのにトレースが出ません。 A. 次の順に確かめます。

Q. API Gateway の HTTP API でトレースしたいです。 A. HTTP API は X-Ray に対応していません。後ろの Lambda でアクティブトレースを有効にすると、Lambda から下流は記録されます。API の入口から追う場合は REST API を使います。

Q. 注釈に何を入れるとよいですか。 A. あとで「このユーザーの遅いリクエスト」のように探したい値です。ユーザーID・テナントID・注文ID・機能フラグの名前などです。1トレースで検索できるのは 50 個までなので、デバッグ用の中身はメタデータに入れます。

Q. X-Ray SDK とPowertools の Tracer は、どちらを使えばよいですか。 A. Powertools の Tracer は X-Ray SDK を使う薄い層で、デコレーターでサブセグメント・注釈・コールドスタートの記録ができます。どちらも X-Ray SDK の保守モードの影響を受けるため、新しく計装を広げるなら OpenTelemetry も選択肢に入ります。

まとめ

• Lambda は --tracing-config Mode=Active と AWSXRayDaemonWriteAccess、REST API はステージの tracingEnabled=true。HTTP API は対応していない
• セグメントはサービス1つ分、サブセグメントはその中の区間や下流の呼び出し。注釈は検索でき（50 個まで）、メタデータは検索できない
• SDK はデーモンへ UDP で「ヘッダー行＋セグメントの JSON」を送る。64 KB を超えるとログを出して捨てる
• サンプリングは上流で1回決まる。Lambda は1秒1件＋5%で固定。ルールは Priority の小さい順に評価
• トレースはサービスマップ → 一覧（フィルター式）→ タイムラインの順に読む
• X-Ray SDK とデーモンは 2026年2月25日から保守モード。新しい計装は OpenTelemetry（ADOT）が勧められている

参考・出典

確認日はいずれも 2026年10月13日です。

• AWS X-Ray 開発者ガイド「AWS X-Ray concepts」：https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html
• AWS X-Ray 開発者ガイド「AWS X-Ray segment documents」：https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html
• AWS X-Ray 開発者ガイド「Configuring sampling rules」：https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html
• AWS X-Ray 開発者ガイド「Configuring sampling, groups, and encryption settings with the AWS X-Ray API」：https://docs.aws.amazon.com/xray/latest/devguide/xray-api-configuration.html
• AWS X-Ray 開発者ガイド「Use filter expressions」：https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html
• AWS X-Ray 開発者ガイド「Configuring the X-Ray SDK for Python」：https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-configuration.html
• AWS X-Ray 開発者ガイド「Migrating from X-Ray instrumentation to OpenTelemetry instrumentation」：https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html
• AWS X-Ray 開発者ガイド「X-Ray SDK and Daemon Support timeline」：https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-daemon-timeline.html
• AWS 全般リファレンス「AWS X-Ray endpoints and quotas」：https://docs.aws.amazon.com/general/latest/gr/xray.html
• AWS Lambda 開発者ガイド「Visualize Lambda function invocations using AWS X-Ray」：https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html
• AWS Lambda 開発者ガイド「Instrumenting Python code in AWS Lambda」：https://docs.aws.amazon.com/lambda/latest/dg/python-tracing.html
• AWS Lambda 開発者ガイド「Working with Lambda environment variables」：https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html
• Amazon API Gateway 開発者ガイド「Set up AWS X-Ray with API Gateway REST APIs」：https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-enabling-xray.html
• Amazon API Gateway 開発者ガイド「Choose between REST APIs and HTTP APIs」：https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html
• Amazon CloudWatch の料金：https://aws.amazon.com/cloudwatch/pricing/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。