AWS X-Ray Java 用自動計測エージェント

AWS X-Ray Java 用自動計測エージェントは、最小限の開発作業で Java ウェブアプリケーションを計測するトレースソリューションです。エージェントは、サーブレットベースのアプリケーションと、サポートされているフレームワークおよびライブラリで作成されたエージェントのすべてのダウンストリームリクエストのトレースを可能にします。これには、ダウンストリーム Apache HTTP リクエスト、AWS SDK リクエスト、および JDBC ドライバーを使用して作成された SQL クエリが含まれます。エージェントは、すべてのアクティブなセグメントとサブセグメントを含む X-Ray コンテキストをスレッド間で伝播します。X-Ray SDK のすべての設定と汎用性は、Java エージェントで引き続き使用できます。エージェントが最小限の労力で動作するように、適切なデフォルトが選択されました。

X-Ray エージェントソリューションは、サーブレットベースの要求応答 Java ウェブアプリケーションサーバーに最適です。アプリケーションが非同期フレームワークを使用している場合、または要求/応答サービスとして適切にモデル化されていない場合は、代わりに SDK を使用した手動計測を検討することをお勧めします。

X-Ray エージェントは、分散システム理解ツールキット (DiSCo) を使用して構築されます。DiSCo は、分散システムで使用できる Java エージェントを構築するためのオープンソースフレームワークです。X-Ray エージェントを使用するために DiSCo を理解する必要はありませんが、GitHub のホームページにアクセスすれば、このプロジェクトについて詳しく知ることができます。X-Ray エージェントも完全にオープンソース化されています。ソースコードの表示、寄付、またはエージェントに関する問題の提起を行うには、GitHub のリポジトリにアクセスします。

サンプルアプリケーション

eb-java-scorekeep サンプルアプリケーションは、X-Ray エージェントによる計測ができるように適応されます。このブランチにはサーブレットフィルターやレコーダー構成は含まれません。これらの機能はエージェントによって行われるためです。ローカルまたは AWS リソースを使用してアプリケーションを実行するには、サンプルアプリケーションの Readme ファイルに記載されている手順に従います。サンプルアプリを使用して X-Ray トレースを生成する方法は、サンプルアプリのチュートリアルに記載されています。

使用開始方法

自分のアプリケーションで X-Ray 自動計測 Java エージェントを使用するには、次の手順を実行します。

ご使用の環境で X-Ray デーモンを実行します。詳細については、「AWS X-Ray デーモン」を参照してください。

エージェントの最新ディストリビューションをダウンロードします。アーカイブを解凍し、ファイルシステム内の場所を記録します。その内容は次のようになります。

disco 
├── disco-java-agent.jar 
└── disco-plugins 
    ├── aws-xray-agent-plugin.jar 
    ├── disco-java-agent-aws-plugin.jar 
    ├── disco-java-agent-sql-plugin.jar 
    └── disco-java-agent-web-plugin.jar

下記を含めるようアプリケーションの JVM 引数を変更します。それにより、エージェントが有効になります。該当する場合は、-javaagent 引数が -jar 引数の前に配置されていることを確認します。JVM 引数を変更するプロセスは、Java サーバーの起動に使用するツールやフレームワークによって異なります。具体的なガイダンスについては、サーバーフレームワークのドキュメントを参照してください。
```
-javaagent:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins
```
X-Ray コンソールでのアプリケーション名の表示方法を指定するには、AWS_XRAY_TRACING_NAME 環境変数または com.amazonaws.xray.strategy.tracingName システムプロパティを設定します。名前が指定されていない場合は、デフォルト名が使用されます。
サーバーまたはコンテナを再起動します。着信要求とそのダウンストリーム呼び出しがトレースされるようになりました。期待した結果が表示されない場合は、「トラブルシューティング」を参照してください。

構成

X-Ray エージェントは、ユーザー提供の外部の JSON ファイルによって設定されます。デフォルトでは、このファイルはユーザーのクラスパスのルート（たとえば、ユーザーの resources ディレクトリ）に xray-agent.jsonという名前で存在します。com.amazonaws.xray.configFile システムプロパティに、設定ファイルの絶対ファイルシステムパスを設定することで、設定ファイルのカスタムロケーションを設定できます。

次に、設定ファイルの例を示します。


{     
    "serviceName": "XRayInstrumentedService", 
    "contextMissingStrategy": "LOG_ERROR", 
    "daemonAddress": "127.0.0.1:2000", 
    "tracingEnabled": true, 
    "samplingStrategy": "CENTRAL",     
    "traceIdInjectionPrefix": "prefix",     
    "samplingRulesManifest": "/path/to/manifest",     
    "awsServiceHandlerManifest": "/path/to/manifest",     
    "awsSdkVersion": 2,     
    "maxStackTraceLength": 50,     
    "streamingThreshold": 100,     
    "traceIdInjection": true,     
    "pluginsEnabled": true,     
    "collectSqlQueries": false 
}

設定仕様

次の表は、各プロパティの有効な値を説明しています。プロパティ名は大文字と小文字が区別されますが、キーは区別されません。環境変数とシステムプロパティで上書きできるプロパティの場合、優先順位の順序は常に環境変数、システムプロパティ、構成ファイルになります。上書きできるプロパティについては、「環境変数」を参照してください。すべてのフィールドはオプションです。

プロパティ名	タイプ	有効値	説明	環境変数	システムプロパティ	デフォルト
serviceName	文字列	任意の文字列	X-Ray コンソールに表示される計測済みサービス名。	AWS_XRAY_TRACING_NAME	com.amazonaws.xray.strategy.tracingName	XRayInstrumentedService
contextMissingStrategy	文字列	LOG_ERROR、IGNORE_ERROR	エージェントが X-Ray セグメントコンテキストを使用しようとするが、存在しないときに実行するアクション。	AWS_XRAY_CONTEXT_MISSING	com.amazonaws.xray.strategy.contextMissingStrategy	LOG_ERROR
DaemonAddress	文字列	フォーマットされた IP アドレスとポート、または TCP および UDP アドレスのリスト	X-Ray デーモンとの通信にエージェントが使用するアドレス。	AWS_XRAY_DAEMON_ADDRESS	com.amazonaws.xray.emitter.daemonAddress	127.0.0.1:2000
tracingEnabled	ブール値	True、False	X-Ray エージェントによる計測を有効にします。	AWS_XRAY_TRACING_ENABLED	com.amazonaws.xray.tracingEnabled	TRUE
samplingStrategy	文字列	CENTRAL、LOCAL、NONE、ALL	エージェントが使用するサンプリング戦略。ALL はすべてのリクエストをキャプチャし、NONE はリクエストをキャプチャしません。サンプリングルールを参照してください。。	該当なし	該当なし	CENTRAL
traceIdInjectionPrefix	文字列	任意の文字列	ログに注入されたトレース ID の前に指定されたプレフィクスを含めます。	該当なし	該当なし	なし (空の文字列)
samplingRulesManifest	文字列	絶対ファイルパス	ローカルサンプリング戦略のサンプリングルール、または中央戦略のフォールバックルールのソースとして使用されるカスタムサンプリングルールファイルへのパス。	該当なし	該当なし	DefaultSamplingRules.json
awsServiceHandlerManifest	文字列	絶対ファイルパス	AWS SDK クライアントから追加情報を取得するためのカスタムパラメータ許可リストへのパス。	該当なし	該当なし	DefaultOperationParameterWhitelist.json
awsSdkVersion	整数	1、2	使用している AWS SDK for Java のバージョン。`awsServiceHandlerManifest` も設定されていない場合は無視されます。	該当なし	該当なし	2
maxStackTraceLength	整数	非負整数	トレースに記録するスタックトレースの最大行数。	該当なし	該当なし	50
streamingThreshold	整数	非負整数	この数以上のサブセグメントが閉じられた後、チャンクが大きすぎるのを避けるために、それらはデーモンアウトオブバンドにストリーミングされます。	該当なし	該当なし	100
traceIdInjection	ブール値	True、False	ログ作成設定に記述された依存関係や設定も追加されている場合、ログへの X-Ray トレース ID の注入を有効にします。それ以外の場合は、何もしません。	該当なし	該当なし	TRUE
pluginsEnabled	ブール値	True、False	操作元となっている AWS 環境についてのメタデータを記録するプラグインを有効にします。プラグインを参照してください。	該当なし	該当なし	TRUE
collectSqlQueries	ブール値	True、False	SQL クエリ文字列を SQL サブセグメントにベストエフォートベースで記録します。	該当なし	該当なし	FALSE
contextPropagation	ブール値	True、False	True の場合、スレッド間で X-Ray コンテキストを自動的に伝播します。それ以外の場合、は Thread Local を使用してコンテキストを保存し、スレッド間での手動伝播が必要です。	該当なし	該当なし	TRUE

ログ作成設定

X-Ray エージェントのログレベルは、X-Ray SDK for Java と同じ方法で設定できます。X-Ray SDK for Java でのログ作成設定については、ログ記録を参照してください。

手動実装

エージェントの自動計測に加えて手動計測を実行する場合は、プロジェクトへの依存関係として X-Ray SDK を追加します。受信リクエストのトレースに記述した SDK のカスタムサーブレットフィルターは、X-Ray エージェントと互換性がないことに注意してください。

注記

エージェントを使用しながら、手動計測を実行するには、X-Ray SDK の最新バージョンを使用する必要があります。

Maven プロジェクトで作業している場合は、以下の依存関係を pom.xml ファイルに追加します。


<dependencies> 
  <dependency> 
    <groupId>com.amazonaws</groupId> 
    <artifactId>aws-xray-recorder-sdk-core</artifactId> 
    <version>2.11.0</version> 
  </dependency> 
  </dependencies>

Gradle プロジェクトで作業している場合は、以下の依存関係を build.gradle ファイルに追加します。


implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0'

通常の SDK と同様に、エージェントを使用しながら、注釈、メタデータ、ユーザー ID に加えて、カスタムサブセグメントを追加することができます。エージェントはスレッド間でコンテキストを自動的に伝播するため、マルチスレッドアプリケーションを操作するときにコンテキストを伝播するための回避策は必要ありません。

トラブルシューティング

エージェントは全自動計測を行うため、問題が発生した場合、根本原因を特定することが困難な場合があります。X-Ray エージェントが期待通りに動作しない場合は、以下の問題点と解決策を確認してください。X-Ray エージェントと SDK は Jakarta Commons Logging (JCL) を使用しています。ログ作成出力を表示するには、次の例（log4j-jcl または jcl-over-slf4j）のように、JCL をログ作成バックエンドに接続するブリッジがクラスパスにあることを確認します。

問題: アプリケーションで Java エージェントを有効にしたが、X-Ray コンソールに何も表示されない

X-Ray デーモンは同じマシンで動作していますか？

そうでない場合は、X-Ray デーモンドキュメントを参照して設定します。

アプリケーションログに「X-Ray エージェントレコーダーの初期化」というメッセージが表示されますか？

アプリケーションにエージェントを正しく追加した場合、このメッセージはアプリケーションの起動時に、リクエストを受け取り始める前に INFO レベルでログに記録されます。このメッセージが表示されない場合、Java エージェントは Java プロセスで実行されていません。入力ミスがない状態で、すべてのセットアップ手順を正しく実行していることを確認してください。

アプリケーションのログに、「AWS X-Ray コンテキスト欠落例外の抑制」のようなエラーメッセージが表示されていませんか？

これらのエラーは、エージェントが AWS SDK リクエストまたは SQL クエリのようなダウンストリームリクエストを計測しようとしているにもかかわらず、エージェントが自動的にセグメントを作成できなかったために発生します。これらのエラーが多く見られる場合、エージェントはユースケースに最適なツールではない可能性がありますので、代わりに X-Ray SDK を使用した手動計測を検討することをお勧めします。また、X-Ray SDK のデバッグログを有効にすると、コンテキスト欠落例外が発生している場所のスタックトレースを確認できます。コードのこれらの部分をカスタムセグメントでラップできます。これにより、これらのエラーを解決できます。ダウンストリームリクエストをカスタムセグメントでラップする例については、スタートアップコードの計測のサンプルコードを参照してください。

問題: 期待していたセグメントの一部が、X-Ray コンソールに表示されない

アプリケーションでマルチスレッドを使用していますか？

作成される予定のセグメントがコンソールに表示されない場合は、アプリケーションのバックグラウンドスレッドが原因である可能性があります。アプリケーションが、AWS SDKで Lambda 関数を 1 回だけ呼び出したり、HTTP エンドポイントを定期的にポーリングするなど、「ファイア・アンド・フォーゲット」のバックグラウンドスレッドを使用してタスクを実行する場合、スレッド間でコンテキストを伝播する際にエージェントが混乱する可能性があります。この問題が発生しているかどうかを確認するには、X-Ray SDK のデバッグログを有効にして、次のようなメッセージがないかどうかを確認してください。「進行中のサブセグメントの親となる、<NAME> という名前のセグメントを出力していません」 この問題を回避するには、サーバーが戻る前にバックグラウンドスレッドに参加して、そのスレッドで行われたすべての作業が記録されるようにします。または、エージェントの contextPropagation の設定を false にすると、バックグラウンドスレッドでのコンテキスト伝播を無効にすることができます。この場合、カスタムセグメントをもつスレッドを手動で計測するか、それらのスレッドが生成するコンテキスト欠落例外を無視する必要があります。

サンプリングルールを設定しましたか？

X-Ray コンソールに一見ランダムな、または予期しないセグメントが表示される場合、あるいはコンソールに表示されるはずのセグメントが表示されない場合は、サンプリングの問題が発生している可能性があります。X-Ray エージェントは、X-Ray コンソールのルールを使用して、作成したすべてのセグメントに集中サンプリングを適用します。デフォルトのルールは、1 秒あたり 1 セグメントが、それ以降はセグメントの 5% がサンプリングされます。つまり、エージェントで迅速に作成されたセグメントはサンプリングされない可能性があります。これを解決するには、目的のセグメントを適切にサンプリングするカスタムサンプリングルールを X-Ray コンソールで作成する必要があります。詳しくは、サンプリングを参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

X-Ray SDK for Java

構成