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

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

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

X-Ray エージェントは、分散システム理解ツールキット、つまり D を使用して構築されますiSCo。D iSCo は、分散システムで使用できる Java エージェントを構築するためのオープンソースフレームワークです。X-Ray エージェントiSCo を使用するには D を理解する必要はありませんが、のホームページ 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
traceIdInjectionプレフィックス	文字列	任意の文字列	トレースを挿入する前に提供されたプレフィックスをログIDsに含めます。	該当なし	該当なし	なし (空の文字列)
samplingRulesManifest	文字列	絶対ファイルパス	ローカルサンプリング戦略のサンプリングルール、または中央戦略のフォールバックルールのソースとして使用されるカスタムサンプリングルールファイルへのパス。	該当なし	該当なし	DefaultSamplingRules.json
awsServiceHandlerマニフェスト	文字列	絶対ファイルパス	AWS SDK クライアントから追加情報をキャプチャするカスタムパラメータ許可リストへのパス。	該当なし	該当なし	DefaultOperationParameterWhitelist.json
awsSdkVersion	整数	1、2	使用している AWS SDK for Java のバージョン。`awsServiceHandlerManifest` も設定されていない場合は無視されます。	該当なし	該当なし	2
maxStackTrace長さ	整数	非負整数	トレースに記録するスタックトレースの最大行数。	該当なし	該当なし	50
streamingThreshold	整数	非負整数	少なくともこの数のサブセグメントが閉じられると、チャンクが大きすぎるのを避けるため out-of-band にデーモンにストリーミングされます。	該当なし	該当なし	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 for Java を使用したログ記録の設定の詳細については、SDKログ記録「」を参照してください。

手動実装

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

注記

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

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'

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

トラブルシューティング

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

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

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

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

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

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

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

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

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

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

作成される予定のセグメントがコンソールに表示されない場合は、アプリケーションのバックグラウンドスレッドが原因である可能性があります。アプリケーションで、を使用して Lambda 関数を 1 回だけ呼び出す、または一部のHTTPエンドポイントを定期的にポーリングするなど AWS SDK、「ファイアアンドエフォート」であるバックグラウンドスレッドを使用してタスクを実行すると、スレッド間でコンテキストを伝達している間にエージェントが混乱する可能性があります。これが問題であることを確認するには、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

構成