はじめに
今回は X-Ray SDK for Python の使い方と、実際にAWS上で設定してどのようなデータが取得できるのかについて深掘りします。
今回利用する環境
API GatewayにAPIリクエストをすると、LambdaがDynamoDBとS3に書き込みを行う構成を作成しました。
また、CloudShellからCloudFormation(SAM)を実行し環境デプロイを行います。

- AWS構成: API Gateway + Lambda + DyanmoDB / S3
- SAM CLI: 1.131.0
- Python: 3.9
- aws-xray-sdk: 2.14.0
目次
AWS X-Ray SDK for Python 設定方法
まずはじめに、AWS X-Ray SDK for Python の使い方を確認します。
参照: aws-xray-sdk - Basic Usage
https://docs.aws.amazon.com/xray-sdk-for-python/latest/reference/basic.html#manually-create-segment-subsegment
X-Ray SDK for Python のドキュメントに記載の通りですが、下記の設定を行うことで各箇所の計測が可能となります。
設定方法は3つあるので、それぞれの設定についてみてみます。
その1: 手動で開始位置と終了位置を指定する
特定の箇所のトレースを取得したい場合やフレームワーク・ライブラリがサポートされていない場合に利用できます。
segments / subsegments をスクリプトの任意の箇所に設定することでbegin~endまでの計測が可能となります。
その2: 関数にデコレータを設定する
プログラムの各所に開始と終了のコードを埋め込んでいくのは非常に手間です。関数にデコレータを付与することで関数をサブセグメントとし計測することが可能です。特定の関数にかかる時間を計測したいときはこちらの capture を使用します。
その3: SDKでサポートされたサードパーティライブラリを使用する
サポートされているライブラリを使用している場合、patch_all() でリクエスト~レスポンスの計測が可能となります。
サービス・システムが分割管理されているマイクロサービスアーキテクチャの場合、DB接続やHTTPリクエストなど外部へのリクエストが頻繁に発生しますが、その処理を自動で計測してくれるのは非常に便利です。
下記の通り、必要なライブラリのみを指定することも可能です。
サポートされているライブラリは下記の通りで、AWSサービスやデータベース、HTTPリクエストなどコンポーネント接続は一通り利用可能となります。
参照:Third Party Library Support
https://docs.aws.amazon.com/xray-sdk-for-python/latest/reference/thirdparty.html--
SUPPORTED_MODULES = (
'aioboto3',
'aiobotocore',
'boto3',
'botocore',
'pynamodb',
'requests',
'sqlite3',
'mysql',
'httplib',
'pymongo',
'pymysql',
'psycopg2',
'pg8000',
'sqlalchemy_core',
'httpx',
)
また、今回は詳細までは触れませんが、
X-Ray SDK for Python では下記ミドルウェアがサポートされています。
- Django
- Flask
- Aiohttp
その他の設定
他にも、アノテーション・メタデータといった情報をトレースに追加することもできます。
例えば、セッションに含まれるユーザーIDやセッションIDなどの情報を追加することで、特定のユーザーのリクエストパターンや問題発生時の状況を分析が可能となります。
たとえば、下記のような設定をすると subsegment_1 にアノテーション・メタデータ情報を追加することができます。
実際のX-Rayでの表示は下記のようになります。

実際に確認してみる
API Gateway のX-Rayトレースを有効にしつつ、LambdaでX-Rayを有効にしたものとしていないものでコンソールを見比べてみます。
アプリケーションとしては、APIにリクエストするとユーザー情報をDynamoDBに保存し、関連ファイルをS3に保存するという簡単なものを用意しました。
アプリケーションの構成:
- API Gateway: RESTful APIのエンドポイント
- Lambda: ユーザー情報の処理
- DynamoDB: ユーザー情報の保存
- S3: ユーザー関連ファイルの保存

CloudFormationで作成したので下記の通りデプロイしてください。
デプロイ手順
CloudFormation実行に必要なファイルの作成
CloudShellから下記の通り実行して環境デプロイを実施します。
下記構成となるようにファイルを作成します。
- template.yaml
- src/app.py
- src/requirements.txt
2. 必要なモジュールのインストール
aws-xray-sdkは展開してLambdaへ一緒にアップロードする必要があるので下記コマンドを実行します。
3. デプロイの実行
ファイルが準備できたらSAMデプロイを実行します。
※sam-cliがインストールされていない環境の場合はインストールしてから実行してください。
参考までに下記の通り実行しました。

4. API実行
SAMの実行結果にある、ApiEndpoint の値からAPI Gateway のリクエストURLを確認し、下記の通りリクエストを実施します。
APIリクエストする際のURLについては、sam deployのOutPutsにURLが出力されるのでそちらを利用してください。

5. 動作確認
AWSコンソールから「CloudWatch - X-Rayトレース - トレース」を確認します。
最新のトレースに先ほどのリクエストがあると思うのでそちらを押下してトレースされた情報を確認します。

このようにトレースが確認できれば成功です。
「トレースの詳細」を見ると、
API GatewayからLambdaが呼び出され、それぞれDynamoDBとS3へ接続していることがわかります。

続いて、「セグメントのタイムライン」を見てみます。
それぞれ セグメント(処理)にかかった時間 と 処理が成功・失敗 したかが下記の通りわかります。
API Gatewayがリクエストを受信してからレスポンスを返すまでの時間と、バックエンドのLambdaがそれぞれの処理にかかった時間を簡単に把握することが可能になっています。

また、SDKの計測方法それぞれ3種類については下記のように取得されます。
subsegmentsの入れ子構造や、関数デコレータ内のsubsegementsなど、意図通り計測がされていました。

LambdaでSDKを使用する際の注意点
実行時のLogsにも出力されていましたが、Lambdaでは segments は利用できず、subsegments を設定する必要があるので注意です。
参考までに、下記ログが出力されていました。
[WARNING] Cannot create segments inside Lambda function. Discarded.

AWSサービスでのトレース有効化とSDKの違いを確認する
今回、APIGateway/Lambdaのトレースを有効にし、SDKにて内部のトレース情報を取得しました。
それぞれの設定でどこまで取得できるのかも確認したのでまとめておきます。
- 1: API Gatewayのトレースを有効 /Lambdaトレースを無効 / SDKを無効
- 2: API Gatewayのトレースを有効 / Lambdaトレースを有効 / SDKを無効
- 3: API Gatewayのトレースを有効 / Lambdaトレースを有効 / SDKを有効
先ほどのアプリケーションを利用して、設定とソースコードをAWSコンソール上から修正して利用します。※無効化する方法は今回省略します。

1: API Gatewayのトレースを有効 /Lambdaトレースを無効 / SDKを無効
API Gateway のステージ設定で、「X-Rayトレース」を有効化します。
Lambdaトレースは無効化にしている状態です。

この状態でAPIリクエストを実行すると、
API GatewayとLambdaが表示されました。S3/DynamoDBは表示されず、SDKも設定していないのでLambda内のトレースも表示されない状態です。

2: API Gatewayのトレースを有効 / Lambdaトレースを有効 / SDKを無効
続いて、Lambdaのサービストレースを有効化します。

APIリクエストを実行すると、
今回もAPI GatewayとLambdaが表示されました。S3/DynamoDBは表示されず、SDKも設定していないのでLambda内のトレースも表示されない状態です。
違いといえば一点、Lambda Functionの情報が追加されています。

3: API Gatewayのトレースを有効 / Lambdaトレースを有効 / SDKを有効
最後にLambdaのスクリプトでX-Ray SDKを有効にします。

LambdaをデプロイしてAPIを実行します。
すると、Lambdaがboto3で接続しているDynamoDB・S3が追加されています。

タイムラインにもDynamoDB/S3が追加され、各処理のタイミングや処理にかかった時間などを確認することができます。

まとめ
実際にX-Rayを使ってみたことで実装方法や表示内容など理解することができました。
X-Rayを活用することで、マイクロサービスアーキテクチャにおけるパフォーマンス分析や問題解決が効率的に行えるので是非お試しください。
参考
- https://d1.awsstatic.com/webinars/jp/pdf/services/20200526_BlackBelt_X-Ray.pdf
今回でてきた用語やX-Rayの概念などの詳細に解説されています。
投稿者プロフィール
-
2024 Japan AWS Top Engineers
2025 AWS Community Builders
AWSを使ったサーバレスアーキテクチャ・コンテナサービスの設計・構築を担当。
最新の投稿
AWS2025年3月31日Aurora Provisioned vs Serverless v2:最適な選択と移行ガイド
AWS2025年1月17日AWS X-Ray SDK for Python 実践ガイド:トレース設定から可視化まで深堀りしてみた
NewRelic2024年12月25日【New Relic】アプリ初心者でも大丈夫!インフラエンジニアがはじめるAPM/Browser超入門 〜1時間で始める可視化への第一歩〜
AWS re:Invent 20242024年12月22日Amazon ECSのAmazon CloudWatch Container Insightsでオブザーバビリティ強化されたので、AWS X-Rayとともに検証してみた