📝

AWS X-Ray とは

に公開
AWS
xray
tech

AWS X-Ray とは - AWS X-Ray

AWS X-Ray はアプリケーションが処理するリクエストに関するデータを収集するサービスです。データを表示、フィルタリング、洞察を取得して問題の識別や最適化の機会を識別するために使用するツールを提供します。アプリケーションに対するトレース対象のリクエストの場合、リクエストとレスポンスに関する情報だけではなく、アプリケーションがダウンストリーム AWS リソース、マイクロサービス、データベース、および ウェブ API に対して行う呼び出しの詳細な情報も表示できます。

アプリケーションのリクエストをトレースできるサービスです。

機能概要

  • アプリケーションのリクエストを CloudWatch コンソールで可視化可能
  • AWS X-Ray と統合された AWS サービスも存在する
  • X-Ray API も提供されている
  • レスポンスコードを分析して自動的にバグを特定

ユースケース

Deep dive into AWS X-Ray groups and use cases | AWS Developer Tools Blog

  • 分散アプリケーションの分析とデバッグ
  • パフォーマンス評価やボトルネックの特定
  • エラーのトラブルシューティング

主要な用語

[AWS Black Belt Online Seminar] AWS X-Ray

  • セグメント: 動作に関するデータ
    • リソース名、リクエストの詳細、行った作業の詳細など
  • サブセグメント: 呼び出しに関する追加の詳細な情報
    • AWS のサービス、外部 HTTP API、SQL データベースなど
  • トレース: 1 つのリクエストで生成されたセグメントの全てを収集したもの
  • サンプリング: トレースするリクエストを決定するルール
    • デフォルトでは 1 秒ごとに最初のリクエストを記録し、追加のリクエストの 5% を記録
  • トレースヘッダー: トレース ID などを含む HTTP ヘッダー
    • リクエストの伝搬に使用
  • フィルタ式: トレースを絞り込むための機能
  • グループ: フィルタ式で定義されるトレースのコレクション
  • 注釈: フィルタ式で使用するためインデックス化されたキーと値のペア
    • 例 "aws:api_stage": "prod"
  • メタデータ: 任意のタイプの値を持つことができるキーと値のペア
    • 例 "game": {"id": "abcdefg", "session": "xxxyyyzzz"}

AWS X-Ray SDK および Daemon のサポート終了

AWS X-Ray SDK / Daemon のサポート終了と OpenTelemetry 移行のお知らせ | Amazon Web Services ブログ

AWS X-Ray 用の SDK と Daemon は2026年2月25日にメンテナンスモードに入り、2027年2月25日にサポート終了となります。OpenTelemetry ベースの計装ソリューションへ移行することで、AWS 内でアプリケーションのトレースを継続して生成できます。

上記 AWS ブログで発表されている通り、X-Ray SDK と X-Ray デーモンはサポート終了が予定されています。
移行先としては AWS Distro for OpenTelemetry (ADOT) や OpenTelemetry をご検討ください。
詳細については上記 AWS ブログや以下の移行に関するドキュメントをご参照ください。
Migrating from X-Ray instrumentation to OpenTelemetry instrumentation - AWS X-Ray

試してみた

Lambda から DynamoDB の値を取得するアプリケーションで AWS X-Ray を使ってみました。

01. DynamoDB テーブルの作成

以下の設定で作成しました。

  • テーブル名: Users
  • パーティションキー: userId (文字列)

上記以外はデフォルト設定です。
テーブルの作成完了後、以下のデータを追加します。

  • userId: user001
  • name: taro (文字列)
  • email: taro@example.com (文字列)

02. Lambda 関数の作成

以下の設定で作成しました。

  • 関数名: GetUserFunction
  • ランタイム: Python 3.13
  • 実行ロール: AdministratorAccess 権限を付与したロール
  • コード: 以下の通り
import json
import boto3

dynamodb = boto3.resource('dynamodb')
table = dynamodb.Table('Users')

def lambda_handler(event, context):
    try:
        response = table.get_item(
            Key={
                'userId': 'user001'
            }
        )
        
        item = response.get('Item')
        
        if item:
            return {
                'statusCode': 200,
                'body': json.dumps({
                    'message': 'Success',
                    'data': item
                }, ensure_ascii=False)
            }
        else:
            return {
                'statusCode': 404,
                'body': json.dumps({'message': 'User not found'})
            }
            
    except Exception as e:
        return {
            'statusCode': 500,
            'body': json.dumps({'message': str(e)})
        }

03. トレースの有効化

Lambda コンソールの設定から Lambda サービストレースを有効化します。

04. テスト実行

Lambda コンソールからテスト実行します。

以下のデータを取得できることを確認します。

{
  "statusCode": 200,
  "body": "{\"message\": \"Success\", \"data\": {\"email\": \"taro@example.com\", \"name\": \"taro\", \"userId\": \"user001\"}}"
}

05. トレースデータの確認

CloudWatch コンソールからトレースを確認します。

トレース ID をクリックするとトレースマップが表示されます。

トレースマップの各セグメントをクリックすることでより詳細な情報を確認できます。

ADOT でも試してみた

AWS Distro for OpenTelemetry Lambda | AWS Distro for OpenTelemetry
X-Ray SDK などの移行先である AWS Distro for OpenTelemetry (ADOT) も試してみました。

01. レイヤーの追加

作成済みの GetUserFunction 関数に以下のレイヤーを追加します。

  • arn:aws:lambda:ap-northeast-1:615299751070:layer:AWSOpenTelemetryDistroPython:18

なお、最新のレイヤー ARN やリージョンごとの ARN については以下のドキュメントでご確認ください。
AWS Distro for OpenTelemetry Lambda | AWS Distro for OpenTelemetry

02. 環境変数の追加

作成済みの GetUserFunction 関数に以下の環境変数を追加します。

  • キー: AWS_LAMBDA_EXEC_WRAPPER
  • 値: /opt/otel-instrument

03. トレースデータの確認

再度関数をテスト実行後、CloudWatch コンソールでトレースデータを確認します。
Lambda サービストレースのみの場合と比較すると、トレースマップやメタデータに違いがありました。

まとめ

今回は AWS X-Ray について紹介しました。
どなたかの参考になれば幸いです。

参考資料

Discussion