AWS X-Ray
開発者ガイド

AWS X-Ray の開始方法

AWS X-Ray を開始するには、Elastic Beanstalk でサンプルアプリを起動します。これはすでにトレースデータを生成するために計測済みです。数分でサンプルアプリが起動され、トラフィックが生成されてセグメントが X-Ray に送信され、AWS マネジメントコンソール でサービスグラフとトレースを確認できます。

このチュートリアルでは、サンプル Java アプリケーションを使用してセグメントを生成し、X-Ray に送信します。アプリケーションは Spring フレームワークを使用して JSON ウェブ API を実装し、AWS SDK for Java を使用して Amazon DynamoDB にデータを維持します。アプリケーション内のサーブレットフィルターは、アプリケーションで処理されるすべての受信リクエストを計測します。AWS SDK クライアントのリクエストハンドラーは DynamoDB に対するダウンストリーム呼び出しを計測します。


      Scorekeep のサンプルアプリケーションのフロー

X-Ray コンソールを使用してクライアント、サーバー、DynamoDB 間の接続をサービスマップに表示します。サービスマップは、ウェブアプリケーションを構成するサービスが視覚的に表示されたものです。処理したリクエストから生成されたトレースデータから生成されています。


      サービスマップのクライアント、サーバー、DynamoDB 間の接続を表示する

X-Ray SDK for Java を使用すると、2 つの設定を変更するだけでアプリケーションのすべてのプライマリおよびダウンストリーム AWS リソースをトレースできます。

  • X-Ray SDK for Java のトレースフィルタを WebConfig クラスのサーブレット設定または web.xml ファイルに追加します。

  • Maven または Gradle の構築設定で X-Ray SDK for Java のサブモジュールをビルド依存関係に設定します。

AWS CLI を使用して X-RayAPI を呼び出すことで、未加工のサービスマップやトレースデータにアクセスすることもできます。サービスマップおよびトレースデータは JSON であり、これをクエリして、アプリケーションがデータを送信していることを確認したり、特定のフィールドがテスト自動化の一部であることをチェックしたりできます。

前提条件

このチュートリアルでは、Elastic Beanstalk を使用して、サンプルアプリケーションと X-Ray デーモンを実行するリソースを作成および設定します。制限されたアクセス許可を持つ IAM ユーザーを使用する場合は、Elastic Beanstalk 管理ユーザーポリシーを追加して Elastic Beanstalk を使用するためのアクセス許可を IAM ユーザーに付与するとともに、AWSXrayReadOnlyAccess 管理ポリシーを追加して X-Ray コンソールでサービスマップとトレースを読み取るためのアクセス許可を付与します。

サンプルアプリケーション用の Elastic Beanstalk 環境を作成します。Elastic Beanstalk を使用したことがない場合は、ここでアプリケーション用のサービスロールとインスタンスプロファイルも作成します。

Elastic Beanstalk 環境を作成するには

  1. この事前設定されたリンク (https://console.aws.amazon.com/elasticbeanstalk/#/newApplication?applicationName=scorekeep&solutionStackName=Java) を使用して Elastic Beanstalk マネジメントコンソールを開きます。

  2. [Create application] を選択して、Java 8 SE プラットフォームを実行する環境でアプリケーションを作成します。

  3. 環境の準備が完了したら、コンソールは環境ダッシュボードにリダイレクトされます。

  4. ページの上部にある URL をクリックしてサイトを開きます。

環境内のインスタンスには、AWS X-Ray サービスにデータを送信するアクセス権限が必要です。また、サンプルアプリケーションでは Amazon S3 と DynamoDB を使用します。デフォルトの Elastic Beanstalk インスタンスプロファイルを変更して、これらのサービスを使用するためのアクセス権限を含めます。

Elastic Beanstalk 環境に X-Ray、Amazon S3、および DynamoDB のアクセス権限を追加するには

  1. Elastic Beanstalk のインスタンスプロファイルは、IAM コンソールで開きます。aws-elasticbeanstalk-ec2-role をクリックします。

  2. [Attach Policy] を選択します。

  3. [AWSXrayFullAccess]、[AmazonS3FullAccess]、および [AmazonDynamoDBFullAccess] をロールにアタッチします。

Elastic Beanstalk へのデプロイおよびトレースデータの生成

Elastic Beanstalk 環境にサンプルアプリケーションをデプロイします。サンプルアプリケーションは Elastic Beanstalk 設定ファイルを使用して X-Ray で使用する環境を設定し、それが使用する DynamoDB を自動的に作成します。

ソースコードをデプロイするには

  1. サンプルアプリのダウンロード: eb-java-scorekeep-xray-gettingstarted-v1.3.zip

  2. Open the Elastic Beanstalk console.

  3. Navigate to the management console for your environment.

  4. [Upload and Deploy] を選択します。

  5. eb-java-scorekeep-xray-gettingstarted-v1.3.zip をアップロードして、[Deploy (デプロイ)] を選択します。

サンプルアプリケーションには、フロントエンドのウェブアプリケーションが含まれています。ウェブアプリケーションを使用して API へのトラフィックを生成し、トレースデータを X-Ray に送信します。

トレースデータを生成するには

  1. 環境ダッシュボードで、ウェブアプリケーションを開くための URL をクリックします。

  2. [Create] を選択して、ユーザーとセッションを作成します。

  3. [game name] を入力し、[Rules] を [Tic Tac Toe] に設定したら、[Create] を選択して、ゲームを作成します。

  4. [Play] を選択してゲームを開始します。

  5. ゲームの状態を移行および変更するには、タイルを選択します。

これらの各ステップで、API への HTTP リクエスト、および DynamoDB へのダウンストリーム呼び出しが生成され、ユーザー、セッション、ゲーム、移動、および状態データが読み書きされます。

X-Ray コンソールでサービスマップを表示する

X-Ray コンソールで、サンプルアプリケーションによって生成されたサービスマップとトレースを確認できます。

X-Ray コンソールを使用するには

  1. X-Ray コンソールのサービスマップページを開きます。

  2. コンソールには、X-Ray によってアプリケーションから送信されたトレースデータから生成されたサービスグラフの表現が表示されます。

    
            アプリケーションによって送信されるトレースデータから生成されるサービスグラフ X-Ray の表現

サービスマップに表示されるのは、ウェブアプリケーションクライアント、Elastic Beanstalk で実行されている API、DynamoDB サービス、アプリケーションで使用される各 DynamoDB テーブルです。アプリケーションに対するすべてのリクエストは、1 秒あたりのリクエストの設定可能な最大数まで、API にヒットした際にトレースされ、ダウンストリームサービスへのリクエストを生成して、完了します。

サービスグラフの任意のノードを選択すると、そのノードに対してトラフィックを生成したリクエストのトレースを表示できます。現在、Amazon SNS ノードは赤くなっています。理由を調べるために掘り下げます。

エラーの原因を見つけるには

  1. [SNS] という名前のノードを選択します。[サービスの詳細] パネルが右側に開きます。

  2. [トレースの表示] を選択して、[トレースの概要] 画面にアクセスします。

  3. [Trace のリスト] からトレースを選択します。受信リクエストに応答するのではなく起動時に記録されているため、トレースには、メソッドまたは URL はありません。

    
            トレースリストからトレースを選択する
  4. 赤い状態のアイコンを選択して、SNS サブセグメントの [Exceptions] ページを開きます。

    
            赤の状態アイコンを選択して、SNS サブセグメントの [例外] ページを開く
  5. X-Ray SDK は、計測された AWS SDK クライアントによってスローされた例外を自動的にキャプチャし、スタックトレースを記録します。

    
            キャプチャされた例外と記録されたスタックトレースを示す [例外] タブ

この原因は、WebConfig クラスで行われた createSubscription の呼び出しで指定された E メールアドレスが無効であることを意味します。修正しましょう。

Amazon SNS 通知の設定

Scorekeep では、ユーザーがゲームを達成すると、Amazon SNS で通知が送信されます。アプリケーション起動時、環境変数で定義された E メールアドレスのサブスクリプションが作成されます。この呼び出しが失敗したことで、サービスマップの Amazon SNS ノードは赤くなっています。通知を有効にし、サービスマップが緑になるように、環境変数で通知メールを設定します。

Scorekeep の Amazon SNS 通知を設定するには

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management console for your environment.

  3. Choose Configuration.

  4. [Software Configuration] を選択します・

  5. [Environment Properties] で、デフォルトの値を E メールアドレスに置き換えます。

    
            環境プロパティの設定

    注記

    デフォルト値では、AWS CloudFormation 関数を使用して、設定ファイルに保存されているパラメータ (この場合はダミー値) を取得します。

  6. [Apply] を選択します。

更新が完了すると、Scorekeep が再起動し、SNS トピックへのサブスクリプションが作成されます。E メールとサブスクリプションを確認して、ゲーム達成時にアップデートの有無を確認します。


        アップデート後のサービスマップ

サンプルアプリケーションの詳細

サンプルアプリケーションは、X-Ray SDK for Java を使用するように設定された Java の HTTP ウェブ API です。アプリケーションを Elastic Beanstalk にデプロイする際に、DynamoDB テーブルが作成され、API が Gradle でコンパイルされ、nginx プロキシサーバーがルートパスで静的にウェブアプリケーションを提供するように設定されます。同時に、Elastic Beanstalk は /api で始まるパスにリクエストをルーティングして API に送信します。

受信 HTTP リクエストを測定するには、アプリケーションで SDK によって提供された TracingFilter を追加します。

例 src/main/java/scorekeep/WebConfig.java - サーブレットフィルタ

import javax.servlet.Filter; import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter; ... @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } ...

このフィルタは、アプリケーションが処理するすべての受信リクエストに関するトレースデータを送信します。リクエスト URL、メソッド、レスポンスステータス、開始時間、終了時間が含まれます。


        コンソールのプライマリサービスノード

また、アプリケーションは AWS SDK for Java を使用して DynamoDB に対するダウンストリーム呼び出しを行います。これらの呼び出しを計測するには、アプリケーションは単純に AWS SDK 関連のサブモジュールを依存関係として受け取り、X-Ray SDK for Java はすべての AWS SDK クライアントを自動的に計測します。

アプリケーションは Buildfile ファイルを使用してオンインスタンスで Gradle を使用するソースコードを構築し、Procfile ファイルを使用して Gradle が生成する実行可能 JAR を実行します。Buildfile および Procfile のサポートは Elastic Beanstalk Java SE プラットフォームの機能です。

例 [Buildfile]

build: gradle build

例 [Procfile]

web: java -Dserver.port=5000 -jar build/libs/scorekeep-api-1.0.0.jar

SDK サブモジュールを依存関係として宣言することで、コンパイル中に build.gradle ファイルによって SDK サブモジュールが Maven からダウンロードされます。

例 build.gradle -- 依存関係

... dependencies { compile("org.springframework.boot:spring-boot-starter-web") testCompile('org.springframework.boot:spring-boot-starter-test') compile('com.amazonaws:aws-java-sdk-dynamodb') compile("com.amazonaws:aws-xray-recorder-sdk-core") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor") ... } dependencyManagement { imports { mavenBom("com.amazonaws:aws-java-sdk-bom:1.11.67") mavenBom("com.amazonaws:aws-xray-recorder-sdk-bom:2.2.0") } }

コア、AWS SDK、および AWS SDK Instrumentor サブモジュールはすべて、AWS SDK を使用して送信されたダウンストリーム呼び出しを自動的に計測するために必要です。

X-Ray デーモンを実行するために、アプリケーションは Elastic Beanstalk の別の機能である設定ファイルを使用します。設定ファイルは、デーモンを実行するように Elastic Beanstalk に指示し、そのログをオンデマンドで送信します。

例 .ebextensions/xray.config

option_settings: aws:elasticbeanstalk:xray: XRayEnabled: true files: "/opt/elasticbeanstalk/tasks/taillogs.d/xray-daemon.conf" : mode: "000644" owner: root group: root content: | /var/log/xray/xray.log

X-Ray SDK for Java は、AWSXRay という名前のクラスを提供します。これはコードを計測するために使用する TracingHandler というグローバルレコーダーを提供します。グローバルレコーダーを設定して、受信 HTTP 呼び出しのセグメントを作成する AWSXRayServletFilter をカスタマイズできます。サンプルには、プラグインとサンプリングルールでグローバルレコーダーを設定する WebConfig クラスの静的ブロックが含まれています。

例 src/main/java/scorekeep/WebConfig.java - レコーダー

import com.amazonaws.xray.AWSXRay; import com.amazonaws.xray.AWSXRayRecorderBuilder; import com.amazonaws.xray.plugins.EC2Plugin; import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin; import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy; @Configuration public class WebConfig { ... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } }

この例では、ビルダーを使用して sampling-rules.json という名前のファイルからサンプリングルールをロードします。サンプリングルールは、SDK が受信リクエストのセグメントを記録するレートを決定します。

例 src/main/java/resources/sampling-rules.json

{ "version": 1, "rules": [ { "description": "Resource creation.", "service_name": "*", "http_method": "POST", "url_path": "/api/*", "fixed_target": 1, "rate": 1.0 }, { "description": "Session polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/session/*", "fixed_target": 0, "rate": 0.05 }, { "description": "Game polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/game/*/*", "fixed_target": 0, "rate": 0.05 }, { "description": "State polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/state/*/*/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } }

サンプリングルールファイルでは、4 つのカスタムサンプリングルールおよびデフォルトルールが定義されます。各受信リクエスト用に、SDK は定義された順にカスタムルールを適用します。SDK は、リクエストのメソッド、パス、サービス名に一致する最初のルールを適用します。Scorekeep の場合、最初のルールは、1 秒あたり 1 リクエストの固定ターゲット、および固定ターゲットが満たされた後の 1.0 または 100% のリクエストのレートを適用して、すべての POST リクエスト (リソース作成呼び出し) をキャッチします。

他の 3 つのカスタムルールでは、固定ターゲットなしで、セッション、ゲーム、および状態の読み取り (GET リクエスト) に 5% のレートを適用します。これにより、フロントエンドが、コンテンツが最新であることを確認するために数秒ごとに自動的に行う周期的呼び出しのトレース数を最小限に抑えることができます。他のすべてのリクエストの場合は、ファイルは、1 秒あたり 1 リクエストのデフォルトレートおよび 10% のレートを定義します。

また、サンプルアプリケーションでは、手動 SDK クライアント計測、追加サブセグメントの作成、HTTP 呼び出しの出力など、高度な機能の使用方法も説明します。詳細については、「AWS X-Ray サンプルアプリケーション」を参照してください。

クリーンアップ

Elastic Beanstalk 環境を終了し、Amazon EC2 インスタンス、DynamoDB テーブル、およびその他のリソースをシャットダウンします。

Elastic Beanstalk 環境を終了するには

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management console for your environment.

  3. [Actions] を選択します。

  4. [Terminate Environment] を選択します。

  5. [Terminate] を選択します。

30 days 後、トレースデータは自動的に X-Ray から削除されます。

次のステップ

次の章「AWS X-Ray の概念」で X-Ray の詳細をご覧ください。

独自のアプリケーションを計測するには、X-Ray SDK for Java または他の X-Ray SDK のいずれかの詳細を確認してください。

X-Ray デーモンをローカルまたは AWS で実行する場合は、「AWS X-Ray デーモン」を参照してください。

サンプルアプリケーションを GitHub に投稿するには、eb-java-scorekeep を参照してください。