AWS X-Ray
開発者ガイド

AWS X-Ray のユースケースと要件

X-Ray SDK および AWS サービス統合を使用して、ローカルか、Amazon EC2、Elastic Beanstalk、Amazon ECS、AWS Lambda などの AWS コンピューティングサービスで実行されているアプリケーションへのリクエストを計測します。

アプリケーションコードを計測するには、X-Ray SDK を使用します。SDK は受信および送信リクエストに関するデータを記録し、それを X-Ray デーモンに送信します。デーモンはデータをバッチで X-Ray に中継します。たとえば、アプリケーションが DynamoDB テーブルからユーザーの情報を取得するために DynamoDB を呼び出す場合、X-Ray SDK はクライアントリクエストと DynamoDB へのダウンストリーム呼び出し両方のデータを記録します。


      X-Ray SDK は、クライアントリクエストと DynamoDB へのダウンストリーム呼び出し両方のデータを記録します。

その他の AWS のサービスを X-Ray と統合することで、アプリケーションのコンポーネントの計測が簡単になります。サービスの統合により、受信リクエストにトレースヘッダーを追加したり、トレースデータを X-Ray に送信したり、X-Ray デーモンを実行したりできます。たとえば、AWS Lambda は、リクエストに関するトレースデータを Lambda 関数に送信したり、X-Ray SDK を使用しやすくするためにワーカーで X-Ray デーモンを実行したりできます。


      Lambda と X-Ray SDK の統合

多くの計測シナリオで必要となるのは、設定の変更のみです。たとえば、すべての受信 HTTP リクエスト、および Java アプリケーションで行われる AWS サービスへのダウンストリーム呼び出しを計測します。計測するには、X-Ray SDK for Java のフィルタをサーブレット設定に追加し、ビルド依存関係として AWS SDK for Java Instrumentor サブモジュールを含めます。高度な計測の場合、アプリケーションコードを変更して、SDK から X-Ray に送信されるデータをカスタマイズしたり注釈を入れたりできます。

サポートされている言語とフレームワーク

AWS X-Ray では、さまざまな言語、フレームワークおよびプラットフォームをサポートするツールと統合を提供しています。

C#

Windows Server で、X-Ray SDK for .NET を使用して、受信リクエスト、AWS SDK クライアント、SQL クライアント、および HTTP クライアントを計測できます。AWS Lambda では、Lambda X-Ray 統合を使用して受信リクエストを計測できます。

詳細については、「.NET 対応 AWS X-Ray SDK」を参照してください。

Go

すべての Go アプリケーションで、X-Ray SDK for Go クラスを使用して、受信リクエスト、AWS SDK クライアント、SQL クライアント、HTTP クライアントを計測できます。自動リクエスト計測は、HTTP ハンドラーを使用するアプリケーションで使用できます。

AWS Lambda では、Lambda X-Ray 統合を使用して受信リクエストを計測できます。完全な計測のためには、X-Ray SDK for Go を関数に追加します。

詳細については、「Go 対応 AWS X-Ray SDK」を参照してください。

  • Go ウェブアプリケーションX-Ray SDK for Go HTTP ハンドラーを使用して、ルートで受信リクエストを処理します。

  • AWS Lambda の Go – Lambda 関数設定の X-Ray が受信リクエストを計測できるようにします。X-Ray SDK for Go を追加して、AWS SDK、HTTP、SQL クライアントを計測します。

Java

すべての Java アプリケーションで、受信リクエスト、AWS SDK クライアント、SQL クライアント、HTTP クライアントを計測する X-Ray SDK for Java クラスを使用できます。自動リクエスト計測は、Java サーブレットをサポートするフレームワークで利用できます。自動 SDK 計測は、Instrumentor サブモジュールを通して使用できます。

AWS Lambda では、Lambda X-Ray 統合を使用して受信リクエストを計測できます。完全な計測のためには、X-Ray SDK for Java を関数に追加します。

詳細については、「AWS X-Ray SDK for Java」を参照してください。

  • Tomcatサーブレットフィルタをデプロイ記述子 (web.xml) に追加して受信リクエストを計測します。

  • Spring Bootサーブレットフィルタを WebConfig クラスに追加して受信リクエストを計測します。

  • AWS Lambda の Java – Lambda 関数の X-Ray が受信リクエストを計測できるようにします。X-Ray SDK for Java を追加して、AWS SDK、HTTP、SQL クライアントを計測します。

  • その他のフレームワーク – フレームワークでサーブレットがサポートされている場合はサーブレットフィルタを追加するか、受信リクエストごとに手動でセグメントを作成します。

Node.js

すべての Node.js アプリケーションで、X-Ray SDK for Node.js クラスを使用して、受信リクエスト、AWS SDK クライアント、SQL クライアント、HTTP クライアントを計測できます。自動リクエスト計測は、Express および Restify フレームワークを使用するアプリケーションで使用できます。

AWS Lambda では、Lambda X-Ray 統合を使用して受信リクエストを計測できます。完全な計測のためには、X-Ray SDK for Node.js を関数に追加します。

詳細については、「X-Ray SDK for Node.js」を参照してください。

  • Express または RestifyX-Ray SDK for Node.js ミドルウェアを使用して受信リクエストを計測します。

  • AWS Lambda の Node.js – Lambda 関数の X-Ray が受信リクエストを計測できるようにします。X-Ray SDK for Node.js を追加して、AWS SDK、HTTP、SQL クライアントを計測します

  • その他のフレームワーク – 受信リクエストごとに手動でセグメントを作成します。

Python

すべての Python アプリケーションで、X-Ray SDK for Python クラスを使用して、受信リクエスト、AWS SDK クライアント、SQL クライアント、HTTP クライアントを計測できます。自動リクエスト計測は、Django および Flask フレームワークを使用するアプリケーションで使用できます。

AWS Lambda では、Lambda X-Ray 統合を使用して受信リクエストを計測できます。完全な計測のためには、X-Ray SDK for Python を関数に追加します。

詳細については、「Python 用 AWS X-Ray SDK」を参照してください。

  • Django または FlaskX-Ray SDK for Python ミドルウェアを使用して受信リクエストを計測します。

  • AWS Lambda の Python – Lambda 関数設定の X-Ray が受信リクエストを計測できるようにします。X-Ray SDK for Python を追加して、AWS SDK、HTTP、SQL クライアントを計測します。

  • その他のフレームワーク – 受信リクエストごとに手動でセグメントを作成します。

Ruby

すべての Ruby アプリケーションで、X-Ray SDK for Ruby クラスを使用して、受信リクエスト、AWS SDK クライアント、SQL クライアント、HTTP クライアントを計測できます。自動リクエスト計測は、Rails フレームワークを使用するアプリケーションで使用できます。

  • Rails – X-Ray SDK for Ruby gem と railtie を gemfile に追加し、イニシャライザで受信リクエストを計測するようにレコーダーを設定します。

  • その他のフレームワーク – 受信リクエストごとに手動でセグメントを作成します。

使用している言語またはプラットフォームで X-Ray SDK を使用できない場合は、トレースデータを手動で生成して、X-Ray デーモンまたは直接 X-Ray API に送信することが可能です。

サポート対象の AWS サービス

いくつかの AWS サービスでは、X-Ray 統合が提供されます。統合されたサービスにより、受信リクエストのサンプリングとヘッダーの追加、X-Ray デーモンの実行、X-Ray へのトレースデータの自動送信といった、さまざまなレベルの統合が提供されます。

  • アクティブ計測 – 受信リクエストをサンプリングして計測します。

  • パッシブ計測 – 別のサービスですでにサンプリングされているリクエストを計測します。

  • リクエストのトレース – すべての受信リクエストにトレースヘッダーを追加してダウンストリームに伝達します。

  • ツール – X-Ray デーモンを実行して X-Ray SDK からセグメントを受信します。

以下のサービスでは、X-Ray 統合が提供されます。

  • AWS Lambda – すべてのランタイムの受信リクエストのアクティブ計測およびパッシブ計測。AWS Lambda は、AWS Lambda サービス用と関数用の 2 つのノードをサービスマップに追加します。計測を有効にすると、AWS Lambda は、X-Ray SDK で使用するために、Java ランタイムおよび Node.js ランタイムの X-Ray デーモンをも実行します。詳細はこちら

  • Amazon API Gateway – アクティブ計測およびパッシブ計測。API Gateway は、サンプリングルールを使用して記録するリクエストを決定し、ゲートウェイステージ用のノードをサービスマップに追加します。詳細はこちら

  • Elastic Load Balancing – アプリケーションのロードバランサーのリクエストをトレースします。アプリケーションロードバランサーはトレース ID をリクエストヘッダーに追加してからターゲットグループに送信します。詳細はこちら

  • AWS Elastic Beanstalk – ツール。Elastic Beanstalk には以下のプラットフォームの X-Ray デーモンが含まれています。

    • Java SE – 2.3.0 以降の設定

    • Tomcat – 2.4.0 以降の設定

    • Node.js – 3.2.0 以降の設定

    • Windows Server – Windows Server Core を除く、2016 年 12 月 9 日以降にリリースされたすべての設定。

    Elastic Beanstalk コンソールを使用してこれらのプラットフォームでデーモンを実行するように Elastic Beanstalk に指示を出すか、aws:elasticbeanstalk:xray 名前空間で XRayEnabled オプションを使用できます。詳細はこちら

コードおよび設定の変更

コードに対して機能を変更をすることなく、大量のトレースデータを生成できます。フロントエンドおよびダウンストリーム呼び出しの詳細なトレースは、構築およびデプロイ時間を最小限変更するだけで設定できます。

コードおよび設定変更の例

  • AWS リソースの設定 – AWS リソースの設定を変更して Lambda 関数へのリクエストを計測します。Elastic Beanstalk 環境内のインスタンスで X-Ray デーモンを実行するには、オプション設定を変更します。

  • 構築設定 – X-Ray SDK for Java サブモジュールをコンパイル時間依存関係として、AWS のサービスとリソース (Amazon DynamoDB テーブル、Amazon SQS キュー、Amazon S3 バケットなど) へのすべてのダウンストリームリクエストを計測します。

  • アプリケーション設定 – 受信 HTTP リクエストを計測するには、Java アプリケーションにサーブレットフィルタを追加するか、X-Ray SDK for Node.js をミドルウェアとして Express アプリケーションで使用します。サンプリングルールを変更してプラグインを有効にし、アプリケーションを実行する Amazon EC2、Amazon ECS、および AWS Elastic Beanstalk リソースを計測します。

  • クラスまたはオブジェクトの設定 – Java で送信 HTTP 呼び出しを計測するには、Apache.org バージョンの代わりに HttpClientBuilder の X-Ray SDK for Java バージョンをインポートします。

  • 機能の変更 – AWS SDK クライアントにリクエストハンドラーを追加して、AWS のサービスに対する呼び出しを計測します。サブセグメントを作成してダウンストリーム呼び出しをグループ化し、注釈またはメタデータを使用してセグメントにデバッグ情報を追加します。