翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS X-Ray Java 用自動計測エージェント
**注記**
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。OpenTelemetry に移行することをお勧めします。OpenTelemetry への移行の詳細については、「[X-Ray による計装から OpenTelemetry による計装への移行](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)」を参照してください。
Java 用 AWS X-Ray 自動計測エージェントは、最小限の開発労力で 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 のホームページ](https://github.com/awslabs/disco)にアクセスすれば、このプロジェクトについて詳しく知ることができます。X-Ray エージェントも完全にオープンソース化されています。ソースコードの表示、寄付、またはエージェントに関する問題の提起を行うには、[GitHub のリポジトリ](https://github.com/aws/aws-xray-java-agent)にアクセスします。
## サンプルアプリケーション
[eb-java-scorekeep](https://github.com/aws-samples/eb-java-scorekeep/tree/xray-agent) サンプルアプリケーションは、X-Ray エージェントによる計測ができるように適応されます。このブランチにはサーブレットフィルターやレコーダー構成は含まれません。これらの機能はエージェントによって行われるためです。ローカルまたは AWS リソースを使用してアプリケーションを実行するには、サンプルアプリケーションの Readme ファイルに記載されている手順に従います。サンプルアプリを使用して X-Ray トレースを生成する方法は、[サンプルアプリのチュートリアル](xray-scorekeep.md)に記載されています。
## 使用開始方法
自分のアプリケーションで X-Ray 自動計測 Java エージェントを使用するには、次の手順を実行します。
1. ご使用の環境で X-Ray デーモンを実行します。詳細については、「[AWS X-Ray デーモン](xray-daemon.md)」を参照してください。
1. [エージェントの最新ディストリビューション](https://github.com/aws/aws-xray-java-agent/releases/latest/download/xray-agent.zip)をダウンロードします。アーカイブを解凍し、ファイルシステム内の場所を記録します。その内容は次のようになります。
```
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
```
1. 下記を含めるようアプリケーションの JVM 引数を変更します。それにより、エージェントが有効になります。該当する場合は、`-javaagent` 引数が `-jar` 引数の *前* に配置されていることを確認します。JVM 引数を変更するプロセスは、Java サーバーの起動に使用するツールやフレームワークによって異なります。具体的なガイダンスについては、サーバーフレームワークのドキュメントを参照してください。
```
-javaagent://disco-java-agent.jar=pluginPath=//disco-plugins
```
1. X-Ray コンソールでのアプリケーション名の表示方法を指定するには、`AWS_XRAY_TRACING_NAME` 環境変数または `com.amazonaws.xray.strategy.tracingName` システムプロパティを設定します。名前が指定されていない場合は、デフォルト名が使用されます。
1. サーバーまたはコンテナを再起動します。着信要求とそのダウンストリーム呼び出しがトレースされるようになりました。期待した結果が表示されない場合は、「[トラブルシューティング](#XRayAutoInstrumentationAgent-Troubleshooting)」を参照してください。
## 設定
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
}
```
### 設定仕様
次の表は、各プロパティの有効な値を説明しています。プロパティ名は大文字と小文字が区別されますが、キーは区別されません。環境変数とシステムプロパティで上書きできるプロパティの場合、優先順位の順序は常に環境変数、システムプロパティ、構成ファイルになります。上書きできるプロパティについては、「[環境変数](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars)」を参照してください。すべてのフィールドはオプションです。
| プロパティ名 | タイプ | 有効値 | 説明 | 環境変数 | システムプロパティ | デフォルト |
| --- | --- | --- | --- | --- | --- | --- |
| serviceName | String | 任意の文字列 | X-Ray コンソールに表示される計測済みサービス名。 | AWS\_XRAY\_TRACING\_NAME | com.amazonaws.xray.strategy.tracingName | XRayInstrumentedService |
| contextMissingStrategy | String | LOG\_ERROR、IGNORE\_ERROR | エージェントが X-Ray セグメントコンテキストを使用しようとするが、存在しないときに実行するアクション。 | AWS\_XRAY\_CONTEXT\_MISSING | com.amazonaws.xray.strategy.contextMissingStrategy | LOG\_ERROR |
| DaemonAddress | String | フォーマットされた 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 | String | CENTRAL、LOCAL、NONE、ALL | エージェントが使用するサンプリング戦略。ALL はすべてのリクエストをキャプチャし、NONE はリクエストをキャプチャしません。[サンプリングルール](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sampling)を参照してください。。 | 該当なし | 該当なし | CENTRAL |
| traceIdInjectionPrefix | String | 任意の文字列 | ログに注入されたトレース ID の前に指定されたプレフィクスを含めます。 | 該当なし | 該当なし | なし (空の文字列) |
| samplingRulesManifest | String | 絶対ファイルパス | ローカルサンプリング戦略のサンプリングルール、または中央戦略のフォールバックルールのソースとして使用されるカスタムサンプリングルールファイルへのパス。 | 該当なし | 該当なし | [DefaultSamplingRules.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-core/src/main/resources/com/amazonaws/xray/strategy/sampling/DefaultSamplingRules.json) |
| awsServiceHandlerManifest | String | 絶対ファイルパス | AWS SDK クライアントから追加情報を取得するためのカスタムパラメータ許可リストへのパス。 | 該当なし | 該当なし | [DefaultOperationParameterWhitelist.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-aws-sdk-v2/src/main/resources/com/amazonaws/xray/interceptors/DefaultOperationParameterWhitelist.json) |
| awsSdkVersion | 整数 | 1、2 | 使用している [AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java/index.html) のバージョン。`awsServiceHandlerManifest` も設定されていない場合は無視されます。 | 該当なし | 該当なし | 2 |
| maxStackTraceLength | 整数 | 非負整数 | トレースに記録するスタックトレースの最大行数。 | 該当なし | 該当なし | 50 |
| streamingThreshold | 整数 | 非負整数 | この数以上のサブセグメントが閉じられた後、チャンクが大きすぎるのを避けるために、それらはデーモンアウトオブバンドにストリーミングされます。 | 該当なし | 該当なし | 100 |
| traceIdInjection | ブール値 | True、False | [ログ作成設定](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) に記述された依存関係や設定も追加されている場合、ログへの X-Ray トレース ID の注入を有効にします。それ以外の場合は、何もしません。 | 該当なし | 該当なし | TRUE |
| pluginsEnabled | ブール値 | True、False | 運用している AWS 環境に関するメタデータを記録するプラグインを有効にします。[プラグイン](xray-sdk-java-configuration.md#xray-sdk-java-configuration-plugins)を参照してください。 | 該当なし | 該当なし | 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 でのログ作成設定については、[ログ記録](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) を参照してください。
### 手動実装
エージェントの自動計測に加えて手動計測を実行する場合は、プロジェクトへの依存関係として X-Ray SDK を追加します。[受信リクエストのトレース](xray-sdk-java-filters.md) に記述した SDK のカスタムサーブレットフィルターは、X-Ray エージェントと互換性がないことに注意してください。
**注記**
エージェントを使用しながら、手動計測を実行するには、X-Ray SDK の最新バージョンを使用する必要があります。
Maven プロジェクトで作業している場合は、以下の依存関係を `pom.xml` ファイルに追加します。
```
com.amazonaws
aws-xray-recorder-sdk-core
2.11.0
```
Gradle プロジェクトで作業している場合は、以下の依存関係を `build.gradle` ファイルに追加します。
```
implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0'
```
通常の SDK と同様に、エージェントを使用しながら、[注釈、メタデータ、ユーザー ID](xray-sdk-java-segment.md) に加えて、[ カスタムサブセグメント](xray-sdk-java-subsegments.md) を追加することができます。エージェントはスレッド間でコンテキストを自動的に伝播するため、マルチスレッドアプリケーションを操作するときにコンテキストを伝播するための回避策は必要ありません。
## トラブルシューティング
エージェントは全自動計測を行うため、問題が発生した場合、根本原因を特定することが困難な場合があります。X-Ray エージェントが期待通りに動作しない場合は、以下の問題点と解決策を確認してください。X-Ray エージェントと SDK は Jakarta Commons Logging (JCL) を使用しています。ログ作成出力を表示するには、次の例（`log4j-jcl` または `jcl-over-slf4j`）のように、JCL をログ作成バックエンドに接続するブリッジがクラスパスにあることを確認します。
### 問題: アプリケーションで Java エージェントを有効にしたが、X-Ray コンソールに何も表示されない
**X-Ray デーモンは同じマシンで動作していますか？**
そうでない場合は、[X-Ray デーモンドキュメント](https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html)を参照して設定します。
**アプリケーションログに「X-Ray エージェントレコーダーの初期化」というメッセージが表示されますか？**
アプリケーションにエージェントを正しく追加した場合、このメッセージはアプリケーションの起動時に、リクエストを受け取り始める前に INFO レベルでログに記録されます。このメッセージが表示されない場合、Java エージェントは Java プロセスで実行されていません。入力ミスがない状態で、すべてのセットアップ手順を正しく実行していることを確認してください。
**アプリケーションログに、 AWS X-Ray 「コンテキスト欠落例外の抑制」のようなエラーメッセージがいくつか表示されていますか?**
これらのエラーは、エージェントが AWS SDK リクエストや SQL クエリなどのダウンストリームリクエストを計測しようとしているが、エージェントがセグメントを自動的に作成できなかったために発生します。これらのエラーが多く見られる場合、エージェントはユースケースに最適なツールではない可能性がありますので、代わりに X-Ray SDK を使用した手動計測を検討することをお勧めします。また、X-Ray SDK の [デバッグログ](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) を有効にすると、コンテキスト欠落例外が発生している場所のスタックトレースを確認できます。コードのこれらの部分をカスタムセグメントでラップできます。これにより、これらのエラーを解決できます。ダウンストリームリクエストをカスタムセグメントでラップする例については、[スタートアップコードの計測](scorekeep-startup.md)のサンプルコードを参照してください。
### 問題: 期待していたセグメントの一部が、X-Ray コンソールに表示されない
**アプリケーションでマルチスレッドを使用していますか？**
作成される予定のセグメントがコンソールに表示されない場合は、アプリケーションのバックグラウンドスレッドが原因である可能性があります。アプリケーションが AWS SDK を使用して Lambda 関数を 1 回だけ呼び出したり、一部の HTTP エンドポイントを定期的にポーリングしたりするなど、「発砲して忘れる」バックグラウンドスレッドを使用してタスクを実行する場合、エージェントがスレッド間でコンテキストを伝達している間にエージェントが混乱する可能性があります。この問題が発生しているかどうかを確認するには、X-Ray SDK のデバッグログを有効にして、次のようなメッセージがないかどうかを確認してください。*「進行中のサブセグメントの親となる、 という名前のセグメントを出力していません」* この問題を回避するには、サーバーが戻る前にバックグラウンドスレッドに参加して、そのスレッドで行われたすべての作業が記録されるようにします。または、エージェントの `contextPropagation` の設定を `false` にすると、バックグラウンドスレッドでのコンテキスト伝播を無効にすることができます。この場合、カスタムセグメントをもつスレッドを手動で計測するか、それらのスレッドが生成するコンテキスト欠落例外を無視する必要があります。
**サンプリングルールを設定しましたか？**
X-Ray コンソールに一見ランダムな、または予期しないセグメントが表示される場合、あるいはコンソールに表示されるはずのセグメントが表示されない場合は、サンプリングの問題が発生している可能性があります。X-Ray エージェントは、X-Ray コンソールのルールを使用して、作成したすべてのセグメントに集中サンプリングを適用します。デフォルトのルールは、1 秒あたり 1 セグメントが、それ以降はセグメントの 5% がサンプリングされます。つまり、エージェントで迅速に作成されたセグメントはサンプリングされない可能性があります。これを解決するには、目的のセグメントを適切にサンプリングするカスタムサンプリングルールを X-Ray コンソールで作成する必要があります。詳しくは、[サンプリング](xray-console-sampling.md)を参照してください。