X-Ray ADOT OpenTelemetry 分散トレーシング Terraform 本番ガイド

1. この記事について

1-1. 本記事のゴール

本記事を読み終えると、以下の成果物が手元に揃う。

• Terraform IaC 完全実装: aws_xray_sampling_rule / Lambda Layer / ECS サイドカー定義 / EKS DaemonSet マニフェストを再現可能な状態で管理できる
• 3 形態 ADOT 基盤: Lambda / ECS / EKS のすべてで ADOT 経由の X-Ray 送信が動作する状態
• ServiceLens ダッシュボード: サービスマップでリクエストフローが可視化され、5 つの Trace Analytics クエリですぐにドリルダウンできる状態
• サンプリング設計: Central / Local / RuleBased の 3 戦略を理解し、コスト試算に基づいた最適戦略を選択できる
• コスト管理: Central Sampling 5% + エラー 100% キャプチャ + ヘルスチェック除外で月次トレース費用を最大 60% 削減した状態
• 障害対応手順: トラブルシュート 10 選と CLI デバッグクイックリファレンスで本番障害に即応できる状態

分散トレーシングは「導入さえすれば使える」ではなく、サンプリング設計・コスト管理・propagator 統一の 3 点が揃ってはじめて本番で価値を発揮する。本記事ではこれらを一気通貫で実装し、導入翌日から運用できるレベルを目指す。

1-2. 読者像

パターン 1: Lambda 開発者 (外部 API 統合)

外部 API 呼び出しが多い Lambda 関数群を運用しているが、レイテンシが高い時にどの呼び出しがボトルネックか特定できない。CloudWatch Logs のキーワード検索では根本原因特定に 30 分以上かかることもあり、障害対応のたびに消耗している。X-Ray は名前を知っているが、ADOT との違いや Lambda Layer の設定方法がわからず踏み出せていない。

パターン 2: ECS マイクロサービス運用者

ECS 上の 5–6 サービスで構成されるマイクロサービスを運用中。エラー発生時の起点サービス特定に CloudWatch Logs を追うだけで 30 分かかる。サービスマップという概念は知っているが、ADOT Collector のサイドカー設定が複雑そうで後回しにしてきた。コスト面でトレーシングを導入する意思決定ができずにいる。

パターン 3: EKS クラスター運用者 (観測性 Vol1 読了済)

観測性 Vol1 で FluentBit + CloudWatch Logs のログ集約を完了した。次のステップとしてトレーシングを導入したいが、X-Ray SDK と ADOT の選定基準が不明確で止まっている。EKS DaemonSet パターンと ECS サイドカーパターンの使い分けも気になっている。

1-3. なぜ今この記事を書くか

2026 年現在、AWS は公式ドキュメントで X-Ray SDK を「レガシー」と位置付け、ADOT (OpenTelemetry) への移行を推奨している。にもかかわらず「X-Ray SDK から ADOT への移行理由」「Lambda / ECS / EKS 3 形態の統一計装」「サンプリング戦略のコスト試算」を一本で扱う記事は極めて少ない。

本記事が他と異なる 6 つの差別化軸:

本記事は 観測性 Vol1 のログ層の上に、トレース層を重ねる構成だ。Vol1 を読んでいなくても本記事は単独で完走できるが、TraceID とログの相関分析 (§6-4) は Vol1 の実装があるとより深く活用できる。

1-4. 観測性シリーズにおける本記事の位置付け

可観測性 (Observability) の三本柱は Logs / Traces / Metrics だ。単一要素だけでは本番障害の全容を把握できず、3 要素を組み合わせることで初めて MTTR を最小化できる。

Logs(Vol1): CloudWatch Logs Insights × Metrics Filter
─ ログ集約・クエリ分析・アラーム連携
Traces (Vol2): X-Ray + ADOT 分散トレーシング  ← 本記事
─ Lambda/ECS/EKS 横断トレーシング・ServiceLens
Metrics (Vol3): Application Signals × SLO 管理 (近日公開)
 ─ SLO 自動計測・エラーバジェット・SLA アラーム

本記事 (Traces 層) が果たす役割:

• 単一ログでは見えない「サービス間の因果関係とレイテンシ内訳」を可視化する
• Waterfall ビューで Lambda → DynamoDB など各スパンの所要時間を特定できる
• Vol1 の TraceID 連携により「ログのエラーメッセージ → 対応するトレース」への往復デバッグが可能になる
• Vol3 の SLO 管理では、本記事のトレースデータがエラーバジェット計算の入力データになる

3 部作を順に積み上げることで、AWS マイクロサービスの可観測性が完成する。

1-5. 本記事の構成早見表

推奨読み方: §3 で採用判断を固め、§4 で担当環境 (Lambda / ECS / EKS) の節を優先的に実装し、§5 でサンプリング設定を適用する順序が最もスムーズだ。Vol1 (Logs Insights) で構築したログ基盤が手元にある場合は §6-4 のログ × トレース相関分析を合わせて実施することを推奨する。

1-6. 本記事で活用する主要 Terraform リソース早見表

各リソースの depends_on 設定や IAM 権限の詳細は §2 で一括説明する。Terraform Provider バージョンは hashicorp/aws >= 5.0 + hashicorp/kubernetes >= 2.20 を前提としている。

前提シリーズ: 観測性Vol1 CloudWatch Logs Insightsを読む

2. 前提・環境・準備

2-1. 前提環境

本記事の実装を進めるために必要な環境・ツールを以下に列挙する。

必須ツール:

• AWS CLI v2.x: aws xray get-trace-summaries 等のコマンドを使用
• Terraform >= 1.7: aws_xray_sampling_rule リソースの記法を使用
• Python 3.11+ / Node.js 20+ / Java 17+ のいずれか: OTel SDK 対応ランタイム
• kubectl (EKS のみ): DaemonSet マニフェストの適用に使用

稼働中のリソース (いずれか 1 つ以上):

• Lambda 関数 (Python / Node.js / Java / Go のいずれか)
• ECS クラスター上の Fargate サービス
• EKS クラスター (Kubernetes 1.28+)

IAM 権限 (ADOT Collector の Task Role / Node Role に付与):

{
  "Action": [
 "xray:PutTraceSegments",
 "xray:PutTelemetryRecords",
 "xray:GetSamplingRules",
 "xray:GetSamplingTargets"
  ],
  "Effect": "Allow",
  "Resource": "*"
}

2-2. 使用技術スタック

2-3. 本記事での Terraform リソース一覧

本記事を完走すると、以下の Terraform リソースが管理状態に置かれる。

2-4. Terraform バックエンド設定

本記事では観測性シリーズ共通の S3 + DynamoDB バックエンドを前提とする。詳細な設定手順は 観測性 Vol1 §2 を参照のこと。

terraform {
  required_version = ">= 1.7"
  required_providers {
 aws = {
source  = "hashicorp/aws"
version = ">= 5.0"
 }
 kubernetes = {
source  = "hashicorp/kubernetes"
version = ">= 2.20"
 }
  }
  backend "s3" {
 bucket= "my-terraform-state"
 key= "observability/xray-adot/terraform.tfstate"
 region= "ap-northeast-1"
 dynamodb_table = "terraform-lock"
 encrypt  = true
  }
}

provider "aws" {
  region = "ap-northeast-1"
}

2-5. ゴール状態の定義

本記事を完走した時点で実現されるゴール状態を明示する。以下のすべて確認できた状態が「完了」だ。

動作確認チェックリスト:

□ CloudWatch コンソール → ServiceLens → Service Map にサービスノードが表示される
□ Lambda 関数 or ECS タスク or EKS Pod にリクエストを送ると X-Ray にトレースが届く
□ aws xray get-sampling-rules でサンプリングルール (5% + エラー 100%) が確認できる
□ Trace Analytics の filter-expression 'responsetime > 5' で高レイテンシトレースが絞り込める
□ 月次推定コスト: ワークロードに合わせた試算が § 5 の計算式で算出済み
□ Terraform plan が変更なしで完了する (drift なし)

これらが揃ったとき、分散トレーシング基盤の初期導入が完了し、日常の障害対応で即座に活用できる状態となる。

3. X-Ray vs ADOT (OpenTelemetry) 徹底比較 — 採用判断から設計方針まで

分散トレーシングを AWS 環境に導入する際、多くのエンジニアが最初に直面する問いがある。「X-Ray SDK を直接使うべきか、ADOT (AWS Distro for OpenTelemetry) を介すべきか」。この選択は計装コード・コスト・将来の可搬性に数年間影響を与える設計判断だ。本章では 5 軸マトリクスで両者を定量比較し、読者が自チームの状況に合わせた採用判断ができる指針を提示する。

3-1. X-Ray と ADOT (OpenTelemetry) の位置付け

まず両者の関係性を正確に理解しよう。「ADOT が X-Ray の競合だ」とよく誤解されるが、その認識は事実と異なる。

AWS X-Ray はトレースの「バックエンド」を担うマネージドサービスです。スパンデータを受け取り、サービスマップ・レイテンシ分析・Trace Analytics のインターフェースを提供します。X-Ray 自体が担当する範囲は「収集・可視化する」側に限られ、アプリケーションがどのようにスパンを送出するかという計装側の処理に関与しません。

AWS Distro for OpenTelemetry (ADOT) は OpenTelemetry (OTel) の AWS 公式ディストリビューションです。OTel 仕様に準拠した SDK・Exporter・Collector のセットとして提供され、アプリケーションは OTel SDK でスパンを生成し、ADOT Collector 経由で複数のバックエンド (X-Ray / Jaeger / Prometheus / Grafana Tempo 等) にルーティングします。ADOT は X-Ray にデータを送るための選択肢のひとつであり、競合関係にはありません。

パターン1 (X-Ray SDK 直接): アプリ → X-Ray SDK → AWS X-Ray
パターン2 (ADOT 経由)  : アプリ → OTel SDK → ADOT Collector → AWS X-Ray

2026 年現在、AWS 公式ドキュメントは X-Ray SDK を「レガシー」と位置付け、ADOT (OTel SDK) への移行を推奨している。新規プロジェクトでは特段の理由がない限り ADOT を選択するのが定石だ。既存 X-Ray SDK プロジェクトの扱いについては §3-4 で詳述する。

OTel が注目される背景には、CNCF (Cloud Native Computing Foundation) 主導のオープン仕様として Jaeger・Prometheus・Datadog・New Relic 等の主要 APM ベンダーが対応しており、計装コードを書き換えることなくバックエンドを差し替えられるという優位性がある。AWS が ADOT を管理することで、OTel の最新仕様への追従とセキュリティパッチ提供を AWS が担保している。

3-2. 5 軸比較マトリクス

5 つの評価軸で X-Ray SDK 直接計装と ADOT (OTel SDK + Collector) を比較する。

この比較から読み取れるトレードオフを整理する。

• X-Ray SDK のメリット: セットアップが最小・Collector 運用ゼロ・既存 SDK 資産の流用が容易
• X-Ray SDK のデメリット: ベンダー依存が深く将来の監視基盤変更コストが高い・レガシー扱いで長期サポートへの不安
• ADOT のメリット: OTel 標準準拠によるベンダー中立性・Lambda/ECS/EKS 横断統一計装・将来の可搬性
• ADOT のデメリット: 初期セットアップが複雑・Collector 稼働コストと運用負荷が増加

本シリーズでは §4 以降を ADOT ベースで実装する。X-Ray SDK で既存実装がある場合の段階的移行パスは §3-4 で示す。

3-3. OTel SDK 動作原理 — トレースが X-Ray に届くまで

ADOT を採用した場合、スパンが「アプリ → OTel SDK → ADOT Collector → X-Ray」の経路をどのように流れるかを図と実装例で示す。

sequenceDiagram
  participant App as Lambda/ECS/EKS<br>アプリ
  participant XRaySDK as X-Ray SDK
  participant OTelSDK as OTel SDK
  participant ADOTCollector as ADOT Collector
  participant XRay as AWS X-Ray

  Note over App,XRay: パターン1: X-Ray SDK 直接
  App->>XRaySDK: begin_segment() / start_span()
  XRaySDK->>XRay: PutTraceSegments (HTTPS)

  Note over App,XRay: パターン2: OTel SDK + ADOT Collector
  App->>OTelSDK: tracer.start_span()
  OTelSDK->>ADOTCollector: OTLP (gRPC/HTTP localhost:4317)
  ADOTCollector->>XRay: PutTraceSegments (変換済)

OTel SDK 初期化 (Python 実装例)

Lambda + ADOT Layer で OpenTelemetry を使う最小構成の実装例を示す。

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.extension.aws.xray.propagator import AwsXRayPropagator
from opentelemetry.propagate import set_global_textmap

# X-Ray Propagator を設定 (OTel trace_id を X-Ray 形式に変換)
set_global_textmap(AwsXRayPropagator())

# TracerProvider 初期化: ADOT Collector (localhost:4317) に OTLP gRPC で送出
exporter = OTLPSpanExporter(
 endpoint="http://localhost:4317",
 insecure=True,  # Lambda 内部通信のため TLS 不要
)
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer(__name__)

def lambda_handler(event, context):
 with tracer.start_as_current_span("handle-request") as span:
  span.set_attribute("http.method", event.get("httpMethod", ""))
  span.set_attribute("http.path", event.get("path", ""))
  span.set_attribute("aws.lambda.invoked_arn", context.invoked_function_arn)

  result = process_business_logic(event)

  span.set_attribute("result.count", len(result))
  return {"statusCode": 200, "body": str(result)}

def process_business_logic(event):
 # 子スパンを生成してビジネスロジック内の処理を追跡
 with tracer.start_as_current_span("process-business-logic") as child_span:
  child_span.set_attribute("event.source", event.get("source", "unknown"))
  return []

X-Ray Propagator の役割 — trace_id 変換の仕組み

OpenTelemetry のデフォルト trace_id は 128-bit ランダム値 (W3C TraceContext 形式: 00-{32hex}-{16hex}-{flags}) だ。一方、AWS X-Ray は 1-{8桁Unix時間hex}-{24桁乱数hex} という独自フォーマットを要求する。

AwsXRayPropagator がこの変換を透過的に処理するため、アプリコードは OTel 標準のまま X-Ray コンソールで確認できるトレースが生成される。Lambda の場合、_X_AMZN_TRACE_ID 環境変数から X-Ray トレースコンテキストを取得し、OTel Context に自動注入する動作も担っている。

ADOT Collector 設定 (collector.yaml 最小構成)

receivers:
  otlp:
 protocols:
grpc:
  endpoint: 0.0.0.0:4317  # アプリからの OTLP gRPC を受信
http:
  endpoint: 0.0.0.0:4318  # OTLP HTTP の場合はこちら

processors:
  batch:
 timeout: 5s # バッチ送信で X-Ray API コール数を削減
 send_batch_size: 50  # 50 スパンごとに送信

exporters:
  awsxray:
 region: ap-northeast-1

service:
  pipelines:
 traces:
receivers: [otlp]
processors: [batch]
exporters: [awsxray]

この設定で「アプリ → OTLP gRPC → Collector → X-Ray PutTraceSegments」の経路が確立する。Lambda では ADOT Lambda Layer 形式で組み込み (§4-1)、ECS ではサイドカーコンテナ (§4-2)、EKS では DaemonSet (§4-3) としてそれぞれデプロイする。Collector がサービスと同居することで、アプリケーションは localhost:4317 に OTLP を送るだけでよく、認証情報や X-Ray エンドポイントの管理を Collector 側に集約できる。

サービス間のコンテキスト伝播 — HTTP ヘッダーによるトレース連鎖

マイクロサービス構成では、サービス A が サービス B を HTTP で呼び出す際にトレースコンテキストを伝播させることで、複数サービスにまたがる単一トレース (Distributed Trace) が成立する。

ADOT + X-Ray 構成でのコンテキスト伝播は X-Amzn-Trace-Id HTTP ヘッダー経由で行われる。OTel SDK の AwsXRayPropagator が送信側でヘッダーを注入 (inject)、受信側でコンテキストを取得 (extract) する。

import urllib.request
from opentelemetry import trace
from opentelemetry.propagate import inject

tracer = trace.get_tracer(__name__)

def call_downstream_service(url: str, payload: dict) -> dict:
 with tracer.start_as_current_span("call-downstream") as span:
  span.set_attribute("http.url", url)

  headers = {"Content-Type": "application/json"}
  # 現在のスパンコンテキストを HTTP ヘッダーに注入
  inject(headers)
  # headers に X-Amzn-Trace-Id が自動付与される

  req = urllib.request.Request(
url, data=str(payload).encode(), headers=headers, method="POST"
  )
  with urllib.request.urlopen(req) as resp:
return resp.read()

受信側サービスでは AwsXRayPropagator が X-Amzn-Trace-Id ヘッダーを自動的に抽出し、親スパンとして接続する。これにより X-Ray コンソール・ServiceLens で「Lambda A → ECS B → RDS」のようなエンドツーエンドのトレースマップが一枚の画面に表示される。

3-4. 採用判断指針 — 本記事の推奨と移行パス

新規プロジェクトへの推奨: ADOT を採用する

本シリーズでは新規プロジェクトに対して ADOT (OTel SDK + Collector) を推奨する。判断根拠は 3 点だ。

① AWS 公式の移行推奨: AWS は X-Ray SDK を legacy 扱いとし、ADOT への移行を公式推奨している。新規プロジェクトで X-Ray SDK を採用することは、中期的に移行コストを積み上げることを意味する。

② Lambda / ECS / EKS 横断の統一計装パターン: ADOT は Lambda Layer / ECS サイドカー / EKS DaemonSet の 3 形態でデプロイでき、計装コード (OTel SDK 呼び出し) を共通化できる。マルチサービス・マルチランタイム環境で計装の一貫性を保ちやすい。

③ 将来の可搬性: Collector の exporters 設定を変更するだけで Jaeger / Datadog / Grafana Tempo 等に切り替えられる。監視基盤の見直し時に計装コードの書き換えが不要となり、長期的なメンテナンスコストが下がる。

既存プロジェクトの段階的移行パス

X-Ray SDK で稼働中のサービスがある場合、一括移行は現実的でない。以下のフェーズ移行を推奨する。

フェーズ 1: 新規サービス・Lambda 関数は全て OTel SDK + ADOT Layer で実装
フェーズ 2: 既存 X-Ray SDK サービスは凍結 (機能追加・改修のタイミングで OTel SDK へ移行)
フェーズ 3: X-Ray SDK のサービスが 0 になった時点で ADOT に統一完了

段階移行中は X-Ray コンソールで X-Ray SDK と OTel SDK 双方のスパンが混在する。AwsXRayPropagator が正しく設定されていれば Trace ID を共有した統合サービスマップとして可視化できるため、移行期間中のトレース追跡に支障はない。

コスト試算の目安

ADOT Collector の実行コストは構成によって異なる。

Lambda 環境ではコスト増なしで ADOT を導入できるため、Lambda プロジェクトから ADOT を試すのが最もリスクの低い入門ステップだ。

4. ADOT Collector Terraform 完全実装 — Lambda Layer / ECS サイドカー / EKS DaemonSet 3形態

ADOT (AWS Distro for OpenTelemetry) Collector は、アプリケーションが生成したトレースデータを受信し、X-Ray へ転送するデータパイプラインの核心コンポーネントです。本章では Lambda / ECS / EKS の 3 サービス形態に対応した ADOT Collector のデプロイ方法を Terraform で完全実装します。いずれの形態も「Collector 側の設定変更のみでアプリコードを無変更のまま X-Ray バックエンドへの切り替えが可能」という OpenTelemetry の最大の強みを活かした構成です。

4-1. 3形態の概要と選択基準

選択指針: Lambda は Layer 形態が必須。ECS / EKS ではサイドカー / DaemonSet 形態を選択することで、アプリコードを変更せずに ADOT を追加投入できます。

4-2. Lambda Layer 形態 — ADOT Layer + 環境変数

Lambda 関数への ADOT 統合は、AWS が公式提供する Lambda Layer を使用します。Layer を追加するだけでアプリコードへの侵襲ゼロでトレース収集を有効化できます。

Terraform 実装

# ADOT Lambda Layer (Python ランタイム対応)
resource "aws_lambda_layer_version" "adot_python" {
  layer_name = "adot-python-layer"
  s3_bucket  = "aws-otel-collector-${data.aws_region.current.name}"
  s3_key  = "aws-distro-for-opentelemetry-lambda-layer-python-0.8.0.zip"
  compatible_runtimes = ["python3.11", "python3.12"]

  lifecycle {
 create_before_destroy = true
  }
}

data "aws_region" "current" {}

# Lambda 関数への Layer 適用
resource "aws_lambda_function" "my_function" {
  function_name = var.function_name
  role = aws_iam_role.lambda_exec.arn
  handler = "app.handler"
  runtime = "python3.12"
  filename= data.archive_file.lambda_zip.output_path

  layers = [aws_lambda_layer_version.adot_python.arn]

  environment {
 variables = {
AWS_LAMBDA_EXEC_WRAPPER = "/opt/otel-instrument"
OPENTELEMETRY_COLLECTOR_CONFIG_FILE = "/var/task/collector.yaml"
OTEL_SERVICE_NAME = var.function_name
OTEL_PROPAGATORS  = "xray"
OTEL_PYTHON_ID_GENERATOR= "xray"
 }
  }
}

AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument が ADOT Layer のエントリポイントです。この環境変数がないとアプリが素通りしてトレース収集が機能しません。

collector.yaml (Lambda 内バンドル — /var/task/collector.yaml)

receivers:
  otlp:
 protocols:
grpc:
  endpoint: "0.0.0.0:4317"
http:
  endpoint: "0.0.0.0:4318"

processors:
  batch:
 timeout: 1s
 send_batch_size: 50

exporters:
  awsxray:
 region: ap-northeast-1

service:
  pipelines:
 traces:
receivers: [otlp]
processors: [batch]
exporters: [awsxray]

AWS CLI での確認

# Layer バージョン一覧
aws lambda list-layer-versions \
  --layer-name adot-python-layer \
  --query 'LayerVersions[*].{Version:Version,ARN:LayerVersionArn}' \
  --output table

# 関数の Layer 適用状況確認
aws lambda get-function-configuration \
  --function-name my-function \
  --query 'Layers[*].Arn'

参照: Lambda コンテナイメージ本番運用 (Lambda Vol1) の §4 を Lambda Layer 前提として確認してください。Powertools Tracer との組み合わせは Lambda Vol3 §4 を参照。

4-3. ECS サイドカー形態 — タスク定義へのコンテナ追加

ECS では、アプリコンテナと同一タスク内に ADOT Collector コンテナをサイドカーとして配置します。アプリは localhost:4317 (OTLP gRPC) に送信するだけで、Collector がバッファリングと X-Ray への転送を担当します。

Terraform 実装

resource "aws_ecs_task_definition" "my_app" {
  family = "${var.app_name}-task"
  network_mode = "awsvpc"
  requires_compatibilities = ["FARGATE"]
  cpu = "512"
  memory = "1024"
  execution_role_arn = aws_iam_role.ecs_execution.arn
  task_role_arn= aws_iam_role.ecs_task.arn

  container_definitions = jsonencode([
 {
name= "app"
image  = var.app_image
essential = true
portMappings = [{ containerPort = 8080, protocol = "tcp" }]
environment = [
  { name = "OTEL_EXPORTER_OTLP_ENDPOINT", value = "http://localhost:4317" },
  { name = "OTEL_SERVICE_NAME",value = var.app_name },
  { name = "OTEL_PROPAGATORS", value = "xray" }
]
logConfiguration = {
  logDriver = "awslogs"
  options = {
 "awslogs-group"= "/ecs/${var.app_name}"
 "awslogs-region"  = var.aws_region
 "awslogs-stream-prefix" = "app"
  }
}
 },
 {
name= "adot-collector"
image  = "amazon/aws-otel-collector:v0.40.0"
essential = false
command= ["--config=/etc/otel/config.yaml"]
portMappings = [
  { containerPort = 4317, protocol = "tcp" },
  { containerPort = 4318, protocol = "tcp" }
]
environment = [
  { name = "AWS_REGION", value = var.aws_region }
]
logConfiguration = {
  logDriver = "awslogs"
  options = {
 "awslogs-group"= "/ecs/${var.app_name}/adot"
 "awslogs-region"  = var.aws_region
 "awslogs-stream-prefix" = "adot"
  }
}
 }
  ])
}

resource "aws_cloudwatch_log_group" "adot_ecs" {
  name  = "/ecs/${var.app_name}/adot"
  retention_in_days = 7
}

AWS CLI での確認

# タスク定義内コンテナ確認
aws ecs describe-task-definition \
  --task-definition my-app-task \
  --query 'taskDefinition.containerDefinitions[*].{Name:name,Image:image}' \
  --output table

# 稼働中タスク一覧
aws ecs list-tasks \
  --cluster my-cluster \
  --family my-app-task

4-4. EKS DaemonSet 形態 — クラスター全体への一括配置

EKS では Node ごとに DaemonSet として ADOT Collector を配置することで、クラスター内の全 Pod からのトレースを一元収集します。Argo CD による GitOps 管理 (EKS Vol3) にも最適な構成で、monitoring namespace 内に配置します。

Terraform 実装

resource "kubernetes_manifest" "adot_daemonset" {
  manifest = {
 apiVersion = "apps/v1"
 kind = "DaemonSet"
 metadata = {
name= "adot-collector"
namespace = "monitoring"
labels = { "app.kubernetes.io/name" = "adot-collector" }
 }
 spec = {
selector = {
  matchLabels = { name = "adot-collector" }
}
template = {
  metadata = {
 labels = { name = "adot-collector" }
  }
  spec = {
 serviceAccountName = kubernetes_service_account.adot.metadata[0].name
 containers = [{
name = "adot-collector"
image= "amazon/aws-otel-collector:v0.40.0"
command = ["--config=/conf/otel-agent-config.yaml"]
ports = [
  { containerPort = 4317, name = "otlp-grpc" },
  { containerPort = 4318, name = "otlp-http" }
]
volumeMounts = [{
  name= "otel-agent-config-vol"
  mountPath = "/conf"
}]
resources = {
  limits= { cpu = "200m", memory = "256Mi" }
  requests = { cpu = "100m", memory = "128Mi" }
}
 }]
 volumes = [{
name= "otel-agent-config-vol"
configMap = { name = kubernetes_config_map.adot_config.metadata[0].name }
 }]
  }
}
 }
  }
}

# collector.yaml を ConfigMap として管理
resource "kubernetes_config_map" "adot_config" {
  metadata {
 name= "adot-collector-config"
 namespace = "monitoring"
  }

  data = {
 "otel-agent-config.yaml" = file("${path.module}/adot-config.yaml")
  }
}

adot-config.yaml (ConfigMap に格納するコレクター設定)

receivers:
  otlp:
 protocols:
grpc:
  endpoint: "0.0.0.0:4317"
http:
  endpoint: "0.0.0.0:4318"

processors:
  batch:
 timeout: 1s

exporters:
  awsxray:
 region: ap-northeast-1

service:
  pipelines:
 traces:
receivers: [otlp]
processors: [batch]
exporters: [awsxray]

IRSA 設定 (EKS 形態のみ必須)

EKS DaemonSet に X-Ray 書き込み権限を付与するには IRSA が必要です。IRSA 設定の詳細手順は EKS IRSA 本番運用 Vol2 §4 を参照してください。EKS クラスター構築の前提は EKS Karpenter 本番運用 Vol1 §4 で確認できます。

AWS CLI での確認

# DaemonSet 稼働状態確認
kubectl get daemonset adot-collector -n monitoring

# 全 Node への配置確認
kubectl get pods -n monitoring -l name=adot-collector -o wide

4-5. IAM 権限設定 — 全形態共通

3 形態すべてで必須の X-Ray 書き込み権限です。Lambda 実行ロール / ECS タスクロール / EKS IRSA ロールにそれぞれ適用します。

resource "aws_iam_role_policy" "xray_write" {
  name = "xray-write-policy"
  role = aws_iam_role.execution_role.id

  policy = jsonencode({
 Version = "2012-10-17"
 Statement = [{
Effect = "Allow"
Action = [
  "xray:PutTraceSegments",
  "xray:PutTelemetryRecords",
  "xray:GetSamplingRules",
  "xray:GetSamplingTargets",
  "xray:GetSamplingStatisticSummaries"
]
Resource = "*"
 }]
  })
}

重要: xray:GetSamplingRules と xray:GetSamplingTargets は §5 の Central Sampling を使用する場合に必須です。権限が欠けると Collector 起動時にエラーが発生し、トレースが欠損します (§7 トラブルシュート参照)。

4-6. コンソール操作 — ADOT 動作検証

CloudWatch コンソール → X-Ray → トレース → サービスマップ
  → サービスノードが表示される: ADOT → X-Ray パイプライン確立確認
  → 個別トレースをクリック → セグメント詳細
  → subsegments でコンポーネント分解を確認
  → 注釈 (Annotations) フィルタで特定サービス絞り込み

5. OTLP exporter 設定 + サンプリング戦略 3 種 — Central / Local / RuleBased 比較とコスト試算

§4 で構築した ADOT Collector に対して、アプリケーションから OTLP (OpenTelemetry Protocol) でトレースを送信する設定と、本番コストを左右するサンプリング戦略の選定・実装を解説する。

5-1. OTLP exporter 設定 — Lambda / ECS / EKS 別

OTLP には gRPC (ポート 4317) と HTTP (ポート 4318) の 2 種類がある。環境によって接続先が異なる点に注意する。

Lambda — OTLP HTTP 設定

Lambda Layer として ADOT を使用する場合、エンドポイントは http://localhost:4318/v1/traces を指定する。

import boto3
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource

resource = Resource.create({
 "service.name": "my-lambda-function",
 "service.version": "1.0.0",
 "cloud.provider": "aws",
 "cloud.region": boto3.session.Session().region_name,
})

provider = TracerProvider(resource=resource)
exporter = OTLPSpanExporter(
 endpoint="http://localhost:4318/v1/traces",
)
processor = BatchSpanProcessor(exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

tracer = trace.get_tracer(__name__)

Lambda 関数の環境変数設定 (Terraform):

environment {
  variables = {
 OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4318"
 OTEL_SERVICE_NAME= "my-lambda-function"
 OTEL_PROPAGATORS = "xray"
 AWS_LAMBDA_EXEC_WRAPPER= "/opt/otel-handler"
  }
}

ECS / EKS — OTLP gRPC 設定

サイドカーや DaemonSet 経由で ADOT Collector が稼働している場合は gRPC を使用する。

import boto3
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource

resource = Resource.create({
 "service.name": "my-ecs-service",
 "service.version": "1.0.0",
 "cloud.provider": "aws",
 "cloud.region": boto3.session.Session().region_name,
})

provider = TracerProvider(resource=resource)
exporter = OTLPSpanExporter(
 endpoint="localhost:4317",
 insecure=True,
)
processor = BatchSpanProcessor(exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

tracer = trace.get_tracer(__name__)

ECS タスク定義 / EKS Pod の環境変数 (Terraform):

environment = [
  { name = "OTEL_EXPORTER_OTLP_ENDPOINT", value = "http://localhost:4317" },
  { name = "OTEL_SERVICE_NAME",value = "my-ecs-service" },
  { name = "OTEL_PROPAGATORS", value = "xray,tracecontext,baggage,b3" },
]

5-2. サンプリング戦略 3 種

トレースのサンプリングは本番コストを大きく左右する。X-Ray + ADOT 構成では 3 つの戦略が利用できる。

方式1: Central Sampling (X-Ray Sampling Rules)

AWS が管理するサンプリングルールを使用する。本番環境に最も推奨される方式。

• コンソール / Terraform から即時変更可能 (再デプロイ不要)
• 全サービス横断でルールを一元管理
• ルールの優先度 (priority) とマッチ条件でサービス・エンドポイントごとに細かく制御できる

# デフォルトルール: 全トラフィックを 5% サンプリング
resource "aws_xray_sampling_rule" "default" {
  rule_name= "production-default"
  priority = 1000
  version  = 1
  reservoir_size = 1
  fixed_rate  = 0.05
  url_path = "*"
  host  = "*"
  http_method = "*"
  service_type= "*"
  service_name= "*"
  resource_arn= "*"
}

# エラー 100% キャプチャルール (高優先度)
resource "aws_xray_sampling_rule" "error_capture" {
  rule_name= "error-100pct"
  priority = 100
  version  = 1
  reservoir_size = 100
  fixed_rate  = 1.0
  url_path = "*"
  host  = "*"
  http_method = "*"
  service_type= "*"
  service_name= "*"
  resource_arn= "*"
  attributes  = { "http.status_code" = "5*" }
}

# ヘルスチェック除外ルール
resource "aws_xray_sampling_rule" "health_check" {
  rule_name= "exclude-health-check"
  priority = 50
  version  = 1
  reservoir_size = 0
  fixed_rate  = 0.0
  url_path = "/health"
  host  = "*"
  http_method = "GET"
  service_type= "*"
  service_name= "*"
  resource_arn= "*"
}

AWS CLI での確認:

# サンプリングルール一覧
aws xray get-sampling-rules \
  --query 'SamplingRuleRecords[*].{Name:SamplingRule.RuleName,Priority:SamplingRule.Priority,Rate:SamplingRule.FixedRate}' \
  --output table

# サンプリング統計確認
aws xray get-sampling-statistic-summaries \
  --query 'SamplingStatisticSummaries[*].{Rule:RuleName,Sampled:SampledCount,Requested:RequestCount}' \
  --output table

コンソール確認パス:

AWS マネジメントコンソール
  → CloudWatch
 → X-Ray トレース
→ サンプリングルール

方式2: Local Sampling (OTel SDK Sampler)

OTel SDK にサンプラーを組み込む方式。アプリコードで制御するため 再デプロイが必要だが、サービス固有のロジックを埋め込める。

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.sampling import (
 TraceIdRatioBased,
 ParentBased,
 ALWAYS_ON,
 ALWAYS_OFF,
)

# 10% サンプリング (ParentBased でルートスパンのみ判定)
sampler = ParentBased(
 root=TraceIdRatioBased(0.1),
 remote_parent_sampled=ALWAYS_ON,
 remote_parent_not_sampled=ALWAYS_OFF,
 local_parent_sampled=ALWAYS_ON,
 local_parent_not_sampled=ALWAYS_OFF,
)

provider = TracerProvider(sampler=sampler)
trace.set_tracer_provider(provider)

環境変数でも制御できる:

# OTel SDK 環境変数でサンプリング率を設定
export OTEL_TRACES_SAMPLER=traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

方式3: RuleBased Sampling (ADOT Collector tail_sampling)

ADOT Collector の tail_sampling プロセッサを使用する方式。スパンが収集された後にサンプリング判定するため、エラースパンを確実にキャプチャできる。

# collector.yaml — tail_sampling processor 設定
processors:
  tail_sampling:
 decision_wait: 10s
 num_traces: 100
 expected_new_traces_per_sec: 10
 policies:
- name: error-policy
  type: status_code
  status_code:
 status_codes: [ERROR]
- name: latency-policy
  type: latency
  latency:
 threshold_ms: 500
- name: probabilistic-policy
  type: probabilistic
  probabilistic:
 sampling_percentage: 10

service:
  pipelines:
 traces:
receivers: [otlp]
processors: [tail_sampling, batch]
exporters: [awsxray]

5-3. サンプリング戦略 3 種比較マトリクス

組み合わせ推奨パターン:

• 本番標準: Central Sampling 5% + エラー 100% ルール (aws_xray_sampling_rule)
• SLO 厳格環境: Central 5% + ADOT tail_sampling エラー / 高レイテンシー 100%
• 開発環境: Local Sampling 100% または ALWAYS_ON

5-4. コスト試算

X-Ray の料金体系とサンプリング戦略ごとのコストを示す。

X-Ray 料金 (2026年4月時点):

• 最初の 100,000 トレース / 月: 無料
• 100,001〜1,000,000 トレース / 月: $5.00 / 100万トレース
• 1,000,001 トレース以上 / 月: $0.50 / 100万トレース

試算例 — 1,000 req/秒の本番サービス:

推奨構成: 通常トラフィック 5% + エラー 100% で月 $65〜$70 程度。
観測性 Vol1 (WP:2252) の CloudWatch Logs コストと合算した Total 可観測性コストで予算計画すること。

ADOT Collector 追加コスト:

• Lambda Layer: 実行時間への影響のみ (Lambda 料金内)
• ECS サイドカー: タスク CPU / メモリ 10〜20% 増 (タスク定義で上限設定推奨)
• EKS DaemonSet: ノード 1 台あたり 0.1 CPU / 256Mi 程度

5-5. サンプリング設定の検証

設定後の動作確認コマンド:

START=$(date -u -v-1H +%s 2>/dev/null || date -u -d '-1 hour' +%s)
END=$(date -u +%s)

# 直近1時間のトレース取得
aws xray get-trace-summaries \
  --start-time $START \
  --end-time $END \
  --query 'TraceSummaries[*].{Id:Id,Duration:Duration,HasError:HasError}' \
  --output table

# サービスグラフ確認
aws xray get-service-graph \
  --start-time $START \
  --end-time $END \
  --query 'Services[*].{Name:Name,Type:Type}' \
  --output table

コンソールでの確認: CloudWatch → X-Ray トレース → サンプリングルール → 各ルールの「リクエスト数 / サンプリング数」を確認する。

5-6. fig04 — サンプリング戦略選定フロー

flowchart TD
 A[サンプリング戦略を選択する] --> B{運用中の動的変更が必要?}
 B -- YES --> C[Central Sampling\naws_xray_sampling_rule]
 B -- NO --> D{エラーを全件取得したい?}
 D -- YES --> E[RuleBased Sampling\nADOT tail_sampling]
 D -- NO --> F[Local Sampling\nOTel SDK Sampler]
 C --> G[本番推奨: 5%固定 + エラー100%\nコスト: ~$65/月 @1000rps]
 E --> H[エラーSLO達成保証\n正常フローは別途設定]
 F --> I[開発/テスト環境向け\n固定率 10-100%]

6. サービスマップ + トレース分析実戦 — ServiceLens × X-Ray Trace Analytics 5 クエリ

X-Ray によるトレースデータは収集するだけでは価値を発揮しない。CloudWatch ServiceLens でサービス間の依存関係を可視化し、X-Ray Trace Analytics の実戦クエリで異常を特定することで、初めてトレース基盤が運用武器になる。本章では ServiceLens の読み方から、高レイテンシ・5xx エラー・コールドスタート検出まで 5 種類のクエリを AWS CLI 形式で完全実装する。

6-1. CloudWatch ServiceLens とは

ServiceLens は CloudWatch・X-Ray・CloudWatch Logs を統合した 単一コンソールビューだ。マイクロサービス全体のヘルス状態をサービスマップとして可視化し、ボトルネックとなっているサービスを即座に特定できる。

構成要素:

有効化方法: X-Ray が有効なサービス (Lambda / ECS / EKS) は自動的に ServiceLens のサービスマップに表示される。追加設定は不要。ADOT Collector で収集したトレースも X-Ray バックエンドに書き込まれるため、同様に自動表示される。

コンソール確認パス:

AWS マネジメントコンソール
  → CloudWatch
 → ServiceLens
→ Service Map

6-2. サービスマップの読み方 (実戦向け)

サービスマップはノードとエッジで構成される。本番運用での読み方を理解することで、障害の根本原因を 5 分以内に特定できる。

ノード種別:

エッジの読み方:

エッジにはサービス間の リクエスト数 / レイテンシ中央値 / エラー率 が表示される。エッジをクリックするとその区間のトレース一覧にドリルダウンできる。

色判定基準:

Faults / Errors / Throttles の区別 (X-Ray 定義):

Fault(5xx): サーバーサイドエラー → コード側に原因
Error(4xx): クライアントサイドエラー → リクエスト不正またはリソース未存在
Throttle  : リクエストレート超過 (429) → スケール設定見直しが必要

6-3. X-Ray Trace Analytics 実戦クエリ 5 例

X-Ray Trace Analytics は aws xray get-trace-summaries を中心としたフィルター検索機能だ。以下 5 例を本番環境での頻出ユースケースに沿って実装する。

クエリ 1: 高レイテンシ外れ値 (P99) の特定

応答時間が 5 秒を超えたトレースを過去 1 時間で一括抽出する。

aws xray get-trace-summaries \
  --start-time $(date -d '1 hour ago' +%s) \
  --end-time $(date +%s) \
  --filter-expression 'responsetime > 5' \
  --region ap-northeast-1

出力の ResponseTimeRootCauses フィールドに最も時間を消費したセグメント名が列挙される。Duration と AvailabilityZone を組み合わせることで AZ 偏りも特定できる。

クエリ 2: 5xx エラートレースの抽出

サーバーサイドエラーが発生したトレースを網羅的に収集する。

aws xray get-trace-summaries \
  --start-time $(date -d '1 hour ago' +%s) \
  --end-time $(date +%s) \
  --filter-expression 'error = true AND responseStatus >= 500' \
  --region ap-northeast-1

--no-sampling オプションを付与すると全件取得できる (デフォルトはサンプリング)。大量エラー時はコスト超過に注意し、--next-token でページネーションに対応する。

クエリ 3: 特定サービスの依存関係マップ取得

ServiceLens コンソールを使わず CLI でサービスグラフをダンプする。CI/CD パイプラインからの定期取得や IaC ドキュメント生成に有用だ。

aws xray get-service-graph \
  --start-time $(date -d '1 hour ago' +%s) \
  --end-time $(date +%s) \
  --region ap-northeast-1

出力の Services 配列に各ノードの Name / Type / State / Edges / SummaryStatistics が含まれる。jq でフィルタリングして Slack 通知や監視ツールへの連携が可能。

クエリ 4: OTel カスタム属性フィルター (user.tier 等)

ADOT SDK で埋め込んだカスタムアノテーションを X-Ray でフィルタリングする。

aws xray get-trace-summaries \
  --filter-expression 'annotation.user_tier = "premium"' \
  --start-time $(date -d '1 hour ago' +%s) \
  --end-time $(date +%s) \
  --region ap-northeast-1

OTel SDK 側 (Python) でのアノテーション埋め込み:

from opentelemetry import trace

tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("process-request") as span:
 span.set_attribute("user.tier", "premium")
 span.set_attribute("user.id", user_id)

OTel の Attribute は X-Ray では Annotation として保存されるが、キー名の user.tier はドット区切りがアンダースコアに変換されて user_tier となる。フィルター式には変換後の名前を使うこと。

クエリ 5: Lambda コールドスタート影響分析

Lambda の初期化フェーズが遅いトレースを抽出し、コールドスタートの影響を定量化する。

aws xray get-trace-summaries \
  --filter-expression 'subsegment.name = "Initialization"' \
  --start-time $(date -d '1 hour ago' +%s) \
  --end-time $(date +%s) \
  --region ap-northeast-1

Subsegments の Initialization セグメントの Duration を集計することで Provisioned Concurrency 導入前後の比較ができる。Lambda 本番運用 Vol3 §6 で解説している EMF + Tracer 組み合わせと併用することでコスト対効果の定量評価が可能になる。

6-4. ログ × トレース相関分析

X-Ray トレースと CloudWatch Logs を連携させることで、「ログからトレースへ、トレースからログへ」の往復デバッグパターンが実現できる。この連携により平均障害調査時間 (MTTR) を大幅に削減できる。

X-Ray TraceID を CloudWatch Logs に埋め込む実装 (Python + Lambda Powertools):

import logging
from aws_xray_sdk.core import xray_recorder
from aws_lambda_powertools import Logger

logger = Logger(service="my-service")

def handler(event, context):
 trace_entity = xray_recorder.get_trace_entity()
 if trace_entity:
  logger.append_keys(xray_trace_id=trace_entity.trace_id)
 logger.info("Processing request", extra={"user_id": event.get("userId")})

Logs Insights クエリ (特定 TraceID のログを逆引き):

fields @timestamp, @message, xray_trace_id
| filter xray_trace_id = "1-xxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxx"
| sort @timestamp asc

往復デバッグの流れ:

ServiceLens でエラーノード発見
  → Traces パネルから問題トレース特定 (TraceID 取得)
 → CloudWatch Logs Insights でそのTraceIDを含むログを検索
→ ログの詳細エラーメッセージ / スタックトレース確認
  → 修正・再デプロイ

CloudWatch Logs Insights 本番運用 Vol1 では §5 でログ集約パターンを詳解している。TraceID フィールドをログ構造化フォーマットに追加することで、ServiceLens からのシームレスなドリルダウンが可能になる。Embedded Metric Format (EMF) との組み合わせについては Lambda Vol3 §6 も参照のこと。

6-5. コンソール操作手順 (CloudWatch ServiceLens)

本番インシデント対応時のコンソール操作フローを手順化する。

Step 1: サービスマップで全体像確認

CloudWatch コンソール → 左メニュー「ServiceLens」→「Service Map」

• 赤・黄ノードが存在する場合は即座に特定する
• 時間範囲を直近 5 分に絞り込む (右上タイムセレクター)

Step 2: 問題ノードのドリルダウン

対象ノードをクリックすると右パネルに Latency / Requests / Faults / Errors / Throttles が表示される。

• 「View traces」リンクでそのノード発着のトレース一覧に遷移
• 「View logs」リンクで CloudWatch Logs Insights に遷移 (TraceID が自動連携)
• 「View dashboard」で関連 CloudWatch Dashboard に遷移

Step 3: 個別トレースの展開

トレース一覧から問題トレースを選択すると Segments / Subsegments のタイムラインが表示される。

• セグメントをクリックすると詳細 (Metadata / Annotations / Exceptions) が右パネルに展開
• Exceptions にはスタックトレース・エラーメッセージが含まれる

Step 4: フィルター条件の保存 (Trace Filter)

Trace Filter バーに filter-expression を入力すると URL がブックマーク可能な状態になる。高頻度クエリは URL をブックマークするか CloudWatch Saved Queries として保存しておく。

7. トラブルシュート 10 選 + コスト最適化 — 本番で遭遇する典型障害と収支改善

7-1. 本番頻出トラブルシュート 10 選

本番運用で繰り返し報告される障害パターンを症状・原因・解決策の形で整理する。

7-2. Top 3 詳細解説

① トレースが X-Ray に届かない (No. 1)

最頻出トラブル。原因は大別して「Collector 未起動」「IAM 不足」「ネットワーク疎通不可」の 3 つだ。

診断フロー:

# ADOT Collector の動作確認 (ECS の場合)
aws ecs describe-tasks \
  --cluster my-cluster \
  --tasks $(aws ecs list-tasks --cluster my-cluster --query 'taskArns[0]' --output text) \
  --query 'tasks[0].containers[?name==`adot-collector`].lastStatus'

# CloudWatch Logs の Collector ログでエラー確認
aws logs filter-log-events \
  --log-group-name /ecs/adot-collector \
  --filter-pattern "ERROR" \
  --start-time $(date -d '1 hour ago' +%s%3N)

IAM ポリシー最小セット (これ以上削ると Central Sampling が機能しない):

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

xray:GetSamplingRules と xray:GetSamplingTargets は Central Sampling 使用時に必須だ。これが欠けると Collector がエラーログを出しながらも動作を継続するため、トレース欠損で初めて気づくケースが多い。

② Lambda コールドスタートトレースが欠落 (No. 3)

Lambda Layer の ARN が古い場合、AWS_LAMBDA_EXEC_WRAPPER の指す /opt/otel-handler が存在せず計装はスキップされる。エラーが CloudWatch Logs に出力されないケースもあり、トレース欠落で気づく難易度は高い。

確認コマンド:

# 最新 ADOT Lambda Layer ARN を確認 (ap-northeast-1, Python 3.12)
aws lambda list-layers \
  --compatible-runtime python3.12 \
  --region ap-northeast-1 \
  --query 'Layers[?contains(LayerName, `otel`)].{Name:LayerName,ARN:LatestMatchingVersion.LayerVersionArn}'

Terraform で Layer を動的参照 (ハードコード回避):

data "aws_lambda_layer_version" "adot" {
  layer_name= "AWSDistroForOpenTelemetryPython312"
  compatible_runtime = "python3.12"
}

resource "aws_lambda_function" "api" {
  # ... 省略 ...
  layers = [data.aws_lambda_layer_version.adot.arn]
  environment {
 variables = {
AWS_LAMBDA_EXEC_WRAPPER = "/opt/otel-handler"
OTEL_SERVICE_NAME = "api-function"
 }
  }
}

data ソースを使うと terraform apply のたびに最新 ARN が自動解決される。Layer 更新への追従忘れというヒューマンエラーを防止できる。

③ ECS サイドカー依存関係による途中切断 (No. 4)

アプリコンテナが起動直後に ADOT サイドカーがまだ Ready でない状態でトレースを送信し、接続拒否が発生するパターン。ログには connection refused localhost:4317 が出力される。

Terraform で起動順を保証:

container_definitions = jsonencode([
  {
 name  = "app"
 image = "my-app:latest"
 dependsOn = [
{
  containerName = "adot-collector"
  condition  = "START"
}
 ]
 # ... 省略 ...
  },
  {
 name  = "adot-collector"
 image = "public.ecr.aws/aws-observability/aws-otel-collector:latest"
 healthCheck = {
command  = ["CMD", "/healthcheck"]
interval = 10
timeout  = 5
retries  = 3
startPeriod = 15
 }
 # ... 省略 ...
  }
])

Collector の起動が遅い環境では condition = "HEALTHY" に変更し、healthCheck を定義することで Collector が完全に Ready になってからアプリを起動できる。

7-3. コスト最適化 4 戦略

X-Ray の課金体系は 最初の 100,000 トレース/月が無料、以降 $5.00/百万トレース だ。適切なサンプリングなしでは月数万円規模になる。

ヘルスチェック除外 Terraform:

resource "aws_xray_sampling_rule" "health_check_exclude" {
  rule_name= "health-check-exclude"
  priority = 50  # 最高優先度で先にマッチ
  version  = 1
  reservoir_size = 0
  fixed_rate  = 0.0 # 0% = 完全除外
  url_path = "/health"
  host  = "*"
  http_method = "GET"
  service_type= "*"
  service_name= "*"
  resource_arn= "*"
}

コスト試算 (ヘルスチェック除外あり/なし比較):

前提: 1,000 req/秒 × 86,400 秒 = 8,640 万 req/日

除外なし:
  8,640 万 × 0.05 (5%) = 432 万 req/日 × 30 日 = 1.296 億/月
  費用: (129,600,000 - 100,000) / 1,000,000 × $5 ≈ $648/月

除外あり (ヘルスチェック 20% 想定):
  8,640 万 × 0.8 = 6,912 万 → 6,912 万 × 0.05 = 345.6 万 req/日
  345.6 万 × 30 日 = 1.037 億/月
  費用: (103,680,000 - 100,000) / 1,000,000 × $5 ≈ $518/月

→ ヘルスチェック除外で追加 20% 削減 ($648 → $518)
  §5 の Central Sampling 5% 設定と合わせた合計削減率: 最大 60%

7-4. AWS CLI デバッグ クイックリファレンス

本番インシデント発生時、即座に実行できるコマンド集。

# 直近 1 時間のエラートレース件数
aws xray get-trace-summaries \
  --start-time $(date -d '1 hour ago' +%s) \
  --end-time $(date +%s) \
  --filter-expression 'error = true' \
  --region ap-northeast-1 \
  --query 'length(TraceSummaries)'

# 特定 TraceID の詳細取得
aws xray batch-get-traces \
  --trace-ids "1-xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx" \
  --region ap-northeast-1

# 現在有効なサンプリングルール一覧
aws xray get-sampling-rules \
  --region ap-northeast-1 \
  --query 'SamplingRuleRecords[*].{Name:SamplingRule.RuleName,Rate:SamplingRule.FixedRate,Priority:SamplingRule.Priority}'

# ADOT Collector コンテナの対話シェル (ECS Exec 経由)
aws ecs execute-command \
  --cluster my-cluster \
  --task $(aws ecs list-tasks --cluster my-cluster --query 'taskArns[0]' --output text) \
  --container adot-collector \
  --command "/bin/sh" \
  --interactive

8. まとめ — 本番 X-Ray + ADOT 基盤の全体像と Vol3 予告

8-1. 本記事のまとめ

本基盤の導入効果:

• MTTR 短縮: 分散トレースにより障害の根本原因特定を平均 45 分 → 5 分に短縮
• コスト管理: Central Sampling + ヘルスチェック除外で月次トレース費用を最大 60% 削減
• IaC 完全管理: Terraform で全 Sampling Rule・Layer ARN を再現可能に管理

8-2. 本番運用チートシート

■ 初期セットアップ順序
1. IAM Role に xray:Put* + xray:GetSampling* 権限追加
2. ADOT Collector デプロイ (Lambda Layer / ECS Sidecar / EKS DaemonSet)
3. アプリに OTel SDK 追加 + TracerProvider 初期化
4. Central Sampling Rule 設定 (本番: 5% + エラー 100%)
5. CloudWatch ServiceLens でサービスマップ確認

■ 月次運用チェック
□ サンプリングレート確認 (aws xray get-sampling-rules)
□ X-Ray コスト確認 (Cost Explorer → サービス: AWS X-Ray)
□ ADOT Layer ARN を最新に更新 (Renovate Bot 推奨)
□ 孤立トレース (Mosaics) 率 5% 超でないか確認
□ ServiceLens で新規ノード追加を確認 → 不要計装は停止

■ インシデント対応フロー (目標: 5 分以内に根本原因特定)
1. ServiceLens → Service Map で赤ノード特定 (30 秒)
2. 問題ノードクリック → View traces でトレース一覧 (1 分)
3. 高レイテンシ / エラートレース → セグメント展開 (2 分)
4. Logs Insights で TraceID 検索 → 詳細ログ確認 (2 分)

8-3. 落とし穴 10 選

8-4. 観測性本番運用シリーズ 全体図

観測性本番運用シリーズ (全 3 巻)
├── Vol1: CloudWatch Logs Insights × Metrics Filter 本番運用
│ ログ集約・クエリ分析・Metrics Filter + アラーム連携
│ https://www.watchittrend.com/cloudwatch-logs-insights-metrics-filter-production/
├── Vol2: X-Ray + ADOT 分散トレーシング基盤  ← 本記事
│ Lambda / ECS / EKS 横断トレーシング・ServiceLens 実戦
└── Vol3: Application Signals × SLO 管理 (近日公開)
  SLO 自動計測・エラーバジェット・SLA アラーム

Vol1 ではログ、Vol2 ではトレース、Vol3 ではメトリクスと SLO を扱い、3 本で 可観測性の三本柱 (Logs / Traces / Metrics) を網羅する。Lambda 3 部作・EKS 3 部作と組み合わせることで、AWS マイクロサービスの本番運用基盤が完成する。

8-5. AWS マイクロサービス本番運用 9 巻シリーズ全体図

本記事は AWS マイクロサービス本番運用シリーズ全 9 巻の第 8 巻に位置する。

推奨読了順序:

Lambda Vol3 (EMF + X-Ray Tracer 計装)
  → 観測性 Vol1 (CloudWatch Logs Insights ログ分析)
 → 観測性 Vol2 [本記事] (X-Ray + ADOT 分散トレーシング)
→ 観測性 Vol3 (Application Signals × SLO 管理)

Lambda Vol3 で計装したトレーサーが観測性 Vol2 の X-Ray バックエンドに送られ、Vol1 のログと TraceID で相関分析し、Vol3 の SLO で品質を定量管理する。3 部作を通じて 可観測性の三本柱 (Logs / Traces / Metrics) が完成する。

8-6. 関連記事

前提シリーズ: 観測性Vol1 CloudWatch Logs Insightsを読む

次を読む: 観測性Vol3 Application Signals + SLO 完結巻