MENU

aws x-ray 使い方を徹底解説！初心者でも安心活用法ガイド

大規模情報サイト運営
aws x-ray 使い方
2025/11/30
目次

はじめに

本書の目的

本ドキュメントは、AWS X-Rayを初めて扱う方から導入を検討している運用担当者・開発者までを対象に、基本概念から実践的な設定手順までを分かりやすく解説することを目的としています。トレース収集、可視化、ボトルネックの特定といった作業を具体例を交えて説明します。

想定読者

  • アプリケーションの遅延やエラー原因を把握したい開発者
  • サーバーレスやマイクロサービスの運用に関わるエンジニア
  • X-Ray導入を検討する技術責任者
    専門用語は最小限に抑え、手順は実務で使える形で示します。

この章の読み方

各章は独立して参照できますが、初めての方は順に読むと理解が深まります。実践パートでは設定例やコードスニペットを示しますので、手元の環境で試しながら進めてください。

AWS X-Rayとは

概要

AWS X-Rayは、分散した処理の流れ（リクエスト）がどのようにアプリケーション内を移動したかを追跡するサービスです。サーバーレスやマイクロサービスで発生する遅延やエラーの場所を見つけやすくします。具体例としては、APIの呼び出しがどのサービスで時間を使っているかを可視化できます。

主な機能

  • サービスマップ：各サービス間の接続や遅延を図として表示します。視覚的にボトルネックを見つけられます。
  • トレース分析：個別リクエストの経路と各処理時間、エラー情報を確認できます。
  • サンプリングとフィルタ：すべてのリクエストを集めずに代表的なデータだけを送る設定が可能です。

仕組みの簡単な説明

アプリケーションはトレースデータ（セグメント）を生成してX-Rayに送ります。X-Rayはそれをつなぎ合わせてトレースを作り、サービスマップや詳細ビューを提供します。ライブラリやAWSのマネージド設定で自動送信できます。

利用シーンと注意点

  • レスポンス遅延の原因追及やエラー発生箇所の特定に向きます。小規模なテスト環境でも効果を発揮します。通信量やコストが増えるため、サンプリング設定や収集対象を調整することをおすすめします。

トレース情報の送信方法の選択

概要

X-Rayにトレースを送る方法は主に3つあります。用途や言語、運用方針で最適な方法が変わります。ここでは特徴と選び方をわかりやすく説明します。

1. X-Ray SDK（推奨）

  • 対応言語：Java、.NET、Node.js、Python、Ruby、Goなど
  • 特長：自動計測が充実し導入が簡単です。SDKがHTTPクライアントやフレームワークと連携して、トレースを自動生成します。
  • 向くケース：サーバーサイドアプリやLambdaで素早く始めたいとき。

2. ADOT SDK（OpenTelemetryベース）

  • 特長：OpenTelemetry標準を使うため、複数のバックエンドへ柔軟にデータを送れます。ベンダーロックインを避けたい場合に有効です。
  • 向くケース：既にOpenTelemetryを採用している、または将来移行を見据えるチーム。

3. X-Ray API（手動送信）

  • 特長：SDK非対応の言語や細かなカスタマイズが必要な場合に有効です。送信コードを自分で書きます。
  • 向くケース：特殊な環境や軽量なエージェントのみを使いたい場合。

選び方のポイント

  • 使いやすさ重視：X-Ray SDKをまず検討してください。
  • 標準化／移植性重視：ADOT（OpenTelemetry）を検討します。
  • 柔軟性／非対応言語：X-Ray APIを使います。

実用例（短く）

  • Node.jsのWebアプリ：X-Ray SDKで数分で導入できます。
  • マルチベンダー監視環境：ADOTで一元送信が楽です。
  • レガシー言語：X-Ray APIで必要なデータだけ送れます。

注意点

トレースは詳細な情報を含みます。不要な個人情報や機密データを送らないようにフィルタリング設定を行ってください。導入後はテストで期待どおりにトレースが出るか確認してください。

Lambda関数でのX-Ray有効化

概要

LambdaでX-Rayを有効にすると、関数実行のトレースがX-Rayに送られます。コンソールの設定だけで基本的なトレーシングが始まるため、まずは有効化から始めると分かりやすいです。

有効化手順（コンソール）

  1. Lambdaの関数を開く
  2. 「Configuration」タブを選択
  3. 「Monitoring and operations tools」セクションを開き、「Active tracing」をオンにする
  4. 設定を保存
    これだけでLambda実行時にトレースが送られます。

必要な権限

実行ロールに「AWSXRayDaemonWriteAccess」などのX-Ray送信権限を付与してください。権限が不足するとトレースが記録されません。

アプリ側での補足設定

より詳細を取得するには言語別のX-Ray SDKを導入し、外部API呼び出しやDBアクセスをサブセグメントとして記録します（例：Node.jsのaws-xray-sdk、Pythonのaws_xray_sdk）。依存関係はLambdaのデプロイパッケージかレイヤーで追加します。

確認とトラブル対応

X-Rayコンソールでサービスマップやトレースを確認します。トレースが出ない場合は実行ロールの権限、Active tracingの有効化、CloudWatch Logsのエラーを順に確認してください。

注意点

トレース取得で実行時間やコストがわずかに増えることがあります。必要な範囲だけ有効にすることをおすすめします。

API GatewayでのX-Ray有効化

概要

API GatewayでX-Rayを有効にすると、API経由のリクエストがX-Rayで追跡できます。これにより、API呼び出しの遅延やエラー発生箇所を可視化できます。

手順（コンソール操作）

  1. AWSコンソールでAPI Gatewayを開きます。
  2. 対象のAPIを選び、左のメニューで「Stages（ステージ）」をクリックします。
  3. 有効にしたいステージを選択し、上部の「Logs/Tracing」タブを開きます。
  4. 「Enable X-Ray Tracing」にチェックを入れ、「Save Changes」をクリックします。
  5. 変更後、ステージを再デプロイして設定を反映します。

実務上のポイント

  • API Gateway単体で有効化しても、バックエンド（例：LambdaやEC2）がX-Rayに対応していないと、エンドツーエンドの追跡はできません。バックエンド側もX-Rayを有効にしてください。
  • サンプリング：大量のリクエストでは全件追跡しません。必要に応じてX-Rayのサンプリングルールを調整します。
  • ログ連携：CloudWatch Logsと組み合わせると、エラー発生時の詳細情報を補完できます。

確認方法とトラブルシュート

  • X-Rayコンソールでサービスマップやトレースを確認します。API Gatewayからのセグメントが見えると有効化成功です。
  • トレースが出ない場合は、ステージの再デプロイ、バックエンドのX-Ray設定、IAMロールの権限（X-Rayへ送信できるか）を確認してください。

これでAPI Gateway側の準備は完了です。次はバックエンド側のX-Ray有効化も確認しましょう。

プログラミング言語別の実装方法

Python

1) 準備
– パッケージ: pip install aws-xray-sdk
– IAMロールと環境変数でX-Ray送信を許可します。

2) 手動設定（セグメント/サブセグメントの明示）
– xray_recorder.begin_segment() / end_segment()で囲み、外部呼び出しや重い処理を明示的に計測します。
– 例: データベース呼び出し前後でサブセグメントを作ると詳細が見やすくなります。

3) デコレータ使用
– @xray_recorder.capture(‘名前’) を関数に付けるだけで、その関数の実行が自動でトレースされます。簡単で読みやすい実装です。

4) 自動計測（パッチ）
– xray.patch((‘requests’, ‘boto3’)) などでサードパーティライブラリを自動計測します。手間を減らせますが、計測粒度は設定依存です。

Go

1) SDK取得
– go get -u github.com/aws/aws-xray-sdk-go/

2) 基本的な使い方
– HTTPハンドラを xray.Handler(http.DefaultServeMux, “サービス名”) でラップするとリクエストごとにセグメントが作られます。
– 詳細な処理は xray.Capture(ctx, “操作名”, func(ctx context.Context) error { … }) でサブセグメントを作成します。

3) 注意点
– 両言語ともにローカルでのテスト時はX-Rayデーモンまたは代替エンドポイントの設定が必要です。
– ネットワーク呼び出しやDBアクセスはサブセグメントに分けるとボトルネック特定が容易になります。

CloudWatch Agentの設定

概要

EC2などのサーバー環境でX-Rayを使う場合、CloudWatch Agent側でトレース収集を有効にします。AgentはX-Rayデーモン（ローカルかサイドカー）に接続してトレースを取得し、CloudWatchに送信します。主要な作業はAgentの設定ファイルにtraces_collectedのxray設定を追加することです。

前提と準備

  • X-Rayデーモンをインストールして起動しておきます（デフォルトはUDPポート2000）。
  • EC2のIAMロールにAWSXRayDaemonWriteAccess（X-Ray送信）とCloudWatchAgentServerPolicy（Agentの送信）を付与します。

インストールと起動（例）

  • Amazon Linux: sudo yum install -y amazon-cloudwatch-agent
  • Ubuntu: wget && sudo dpkg -i amazon-cloudwatch-agent.deb
  • Agent起動コマンド例: sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -c file:/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json -s

設定ファイル例（最小構成）

{
  "agent": { "metrics_collection_interval": 60, "run_as_user": "cwagent" },
  "traces_collected": {
    "xray": { "endpoint": "127.0.0.1:2000" }
  }
}

endpointはX-Rayデーモンのアドレスです。デーモンを別コンテナで動かす場合はそのIP:2000を指定します。

起動後の確認方法

  • Agentログ: /opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log を確認します。
  • ネットワーク: ss -u -lpn でデーモンがUDP2000で待ち受けているか確認します。
  • X-Rayコンソールでトレースが見えるか確認します。

よくある注意点

  • IAM権限が不足すると送信に失敗します。ログに権限エラーが出ます。
  • endpointが正しくないとトレースが取得できません。ローカルのデーモンと同一ネットワークであることを確認してください。
  • AgentとX-Rayデーモンのバージョン互換性に注意してください。

フロントエンドとバックエンドの統合分析

AWS RUM（Real User Monitoring）で取得した実ユーザーのトレースIDを、X-Rayで検索してフロントエンドからバックエンドまでを一貫して可視化します。ここでは実務で使える手順と注意点をやさしく説明します。

  • トレースIDの取得
    RUMのイベントやセッション情報に含まれるtraceIdを取得します。ライブラリが提供するプロパティ名を確認し、コンソールやネットワークリクエストで値を確認してください。

  • フロントエンドからの伝搬
    fetchやXHRでAPIを呼ぶ際、ヘッダー（例: X-Amzn-Trace-Id）にトレースIDを付与します。シングルページアプリではルーティング後もIDを保持してください。

  • バックエンド側の連携
    受け取ったトレースIDをX-Rayのセグメントに関連付けます。言語別SDKでヘッダを読み取ってサブセグメントを生成すると、RUMのIDとバックエンドのスパンが一致します。

  • X-Rayでの検索と可視化
    X-RayコンソールでTrace IDをクエリすると、フロントエンドと各バックエンドサービスのタイムラインが表示されます。遅延箇所や外部呼び出しの影響を横断的に確認できます。

  • 注意点
    サンプリング設定でトレースが捨てられる場合があります。CORSでカスタムヘッダーを許可し、時刻差やログの相関も忘れずに行ってください。

これにより、ユーザー操作からサーバー処理までの全体像を簡単に追跡でき、問題の発見と原因切り分けが速くなります。

ボトルネック特定の実践的手法

概要

X-Rayのサービスマップでサービス間の依存関係と遅延を視覚的に把握します。トレース詳細で個々のリクエスト処理の時間配分を確認し、優先的に改善すべき箇所を決めます。

手順（実践的）

  1. サービスマップを開き、レイテンシが高いノードを特定します。色や太さが目安です。例：API Gateway→Lambda→RDSのうちRDSが太い。
  2. 問題ノードをクリックし、代表的なトレースを選びます。
  3. トレースのタイムラインでサブセグメント（DB、外部API、待機時間）を確認します。どの処理が最も時間を消費しているかを見ます。
  4. 同様トレースを複数抽出し、パターン（例：特定クエリ、外部APIの再試行、Lambdaのコールドスタート）を探します。

見るべき指標と対処例

  • 平均/p95/p99レイテンシ：高い分位での遅延は優先対応。
  • エラー率とタイミング：エラーと遅延が一致する箇所を調査。
  • サブセグメント時間：DBならクエリ最適化、インデックス追加、キャッシュ導入。外部APIなら同時実行制御やリトライ見直し。Lambdaならメモリ増やしコールドスタート低減。

注意点

サンプリングがあるため全リクエストは取得できません。再現性のあるトレースを集め、設定でサンプリング率を調整してください。複数の指標（CloudWatchやアプリログ）と合わせて判断すると確実です。

＼ 最新情報はInstagramで📲 ／

Instagramを見る

人気投稿

大規模情報サイト運営
aws x-ray 使い方
よかったらシェアしてね！
  • URLをコピーしました！

この記事を書いた人

userのアバター user

関連記事

目次