翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # AWS X-Ray SDK for Java **注記** X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKs/Daemon はメンテナンスモードに移行します。 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)」を参照してください。 X-Ray SDK for Java は、Java ウェブアプリケーション用のライブラリのセットです。トレースデータを作成し X-Ray デーモンに送信するためのクラスおよびメソッドを提供します。トレースデータには、アプリケーションによって提供される受信 HTTP リクエストに関する情報、およびアプリケーションが AWS SDK、HTTP クライアント、または SQL データベースコネクタを使用してダウンストリームサービスに対して行う呼び出しが含まれます。セグメントを手動で作成し、注釈およびメタデータにデバッグ情報を追加することもできます。 X-Ray SDK for Java は、オープンソースプロジェクトです。プロジェクトに従って、GitHub [github.com/aws/aws-xray-sdk-java](https://github.com/aws/aws-xray-sdk-java) で問題とプルリクエストを送信できます。 受信リクエストのトレースは、[`AWSXRayServletFilter` をサーブレットフィルタとして追加する](xray-sdk-java-filters.md)ことから開始します。サーブレットフィルタにより、[セグメント](xray-concepts.md#xray-concepts-segments)が作成されます。セグメントが開いている間、SDK クライアントのメソッドを使用してセグメントに情報を追加し、サブセグメントを作成してダウンストリーム呼び出しをトレースできます。また、SDK では、セグメントが開いている間にアプリケーションがスローする例外を自動的に記録します。 リリース 1.3 以降では、[Spring のアスペクト指向プログラミング (AOP)](xray-sdk-java-aop-spring.md) を使用してアプリケーションを計測できます。つまり、アプリケーションのランタイムにコードを追加することなく AWS、実行中にアプリケーションを計測できます。 次に、X-Ray SDK for Java を使用して[、SDK Instrumentor サブモジュール](#xray-sdk-java-dependencies)をビルド設定に含めることで AWS SDK for Java クライアントを計測します。計測されたクライアントを使用してダウンストリーム AWS のサービス またはリソースを呼び出すたびに、SDK は呼び出しに関する情報をサブセグメントに記録します。 AWS のサービス サービス内でアクセスするリソースは、トレースマップにダウンストリームノードとして表示され、個々の接続でエラーやスロットリングの問題を特定するのに役立ちます。 へのすべてのダウンストリーム呼び出しを計測しない場合は AWS のサービス、Instrumentor サブモジュールを省略し、計測するクライアントを選択できます。 AWS SDK サービスクライアントに [を追加して`TracingHandler`](xray-sdk-java-awssdkclients.md)、個々のクライアントを計測します。 その他の X-Ray SDK for Java サブモジュールでは、HTTP ウェブ API および SQL データベースに対するダウンストリーム呼び出しを計測できます。Apache HTTP サブモジュールで [X-Ray SDK for Java のバージョン `HTTPClient` と `HTTPClientBuilder` を使用する](xray-sdk-java-httpclients.md) と、Apache HTTP クライアントを計測することができます。SQL クエリの計測には、[データソースに SDK のインターセプターを追加します](xray-sdk-java-sqlclients.md)。 SDK を使用し始めたら、[レコーダーやサーブレットフィルターを設定](xray-sdk-java-configuration.md)して、SDK の動作をカスタマイズしてみましょう。プラグインを追加して、アプリケーションを実行しているコンピューティングリソースに関するデータを記録したり、サンプリングルールを定義することでサンプリングの動作をカスタマイズしたり、アプリケーションログに SDK からの情報をより多くあるいは少なく表示するようにログレベルを設定できます。 アプリケーションが[注釈やメタデータ](xray-sdk-java-segment.md)で行うリクエストや作業に関する追加情報を記録します。注釈は、[フィルタ式](xray-console-filters.md)で使用するためにインデックス化されたシンプルなキーと値のペアで、特定のデータが含まれているトレースを検索できます。メタデータのエントリは制約が緩やかで、JSON にシリアル化できるオブジェクトと配列全体を記録できます。 **注釈とメタデータ** 注釈およびメタデータとは、X-Ray SDK を使用してセグメントに追加する任意のテキストです。注釈は、フィルタ式用にインデックス付けされます。メタデータはインデックス化されませんが、X-Ray コンソールまたは API を使用して raw セグメントで表示できます。X-Ray への読み取りアクセスを許可した人は誰でも、このデータを表示できます。 コードに多数の計測されたクライアントがある場合、単一のリクエストセグメントには計測されたクライアントで行われた呼び出しごとに 1 個の多数のサブセグメントを含めることができます。[カスタムサブセグメント](xray-sdk-java-subsegments.md)で、クライアント呼び出しをラップすることで、サブセグメントを整理してグループできます。関数全体またはコードの任意のセクションのサブセグメントを作成し、親セグメントにすべてのレコードを記述する代わりにサブセグメントにメタデータと注釈を記録できます。 ## サブモジュール X-Ray SDK for Java は、Maven からダウンロードできます。X-Ray SDK for Java は、ユースケースごとにサブモジュールに分割され、部品表のバージョン管理に使用されます。 + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/) (必須) セグメントを作成して送信するための基本的な機能です。受信リクエストを計測する `AWSXRayServletFilter` が含まれています。 + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/) – トレース AWS SDK for Java クライアントをリクエストハンドラーとして追加することで、クライアントで AWS のサービス 行われた への呼び出しを計測します。 + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/) – トレースクライアントをリクエストインターセプターとして追加することで、 AWS SDK for Java 2.2 以降のクライアントで AWS のサービス 行われた の呼び出しを計測します。 + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/) – では`aws-xray-recorder-sdk-aws-sdk`、 はすべての AWS SDK for Java クライアントを自動的に計測します。 + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/) – では`aws-xray-recorder-sdk-aws-sdk-v2`、 はすべての AWS SDK for Java 2.2 以降のクライアントを自動的に計測します。 + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/) - Apache HTTP クライアントを使用して行われるアウトバウンド HTTP 呼び出しを計測します。 + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/) – Spring AOP Framework アプリケーション用のインターセプターを提供します。 + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/) - JDBC を使用して PostgreSQL データベースに対して行われるアウトバウンド呼び出しを計測します。 + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/) - JDBC を使用して MySQL データベースに対して行われるアウトバウンド呼び出しを計測します。 + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/) - すべてのサブモジュールで使用するバージョンを指定するための部品表を提供します。 + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/) – 収集した X-Ray セグメントからサンプリングされていない Amazon CloudWatch メトリクスを発行します。 Maven または Gradle を使用してアプリケーションを構築する場合は、[X-Ray SDK for Java をビルド設定に追加します](#xray-sdk-java-dependencies)。 SDK のクラスとメソッドに関するリファレンスドキュメントについては、「[AWS X-Ray SDK for Java API リファレンス](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc)」を参照してください。 ## 要件 X-Ray SDK for Java には、Java 8 以降、Servlet API 3、 AWS SDK、Jackson が必要です。 SDK は、コンパイル時および実行時に次のライブラリに依存します。 + AWS SDK for Java バージョン 1.11.398 以降 + Servlet API 3.1.0 これらの依存関係は SDK の `pom.xml` ファイルで宣言され、Maven や Gradle を使用して構築すると自動的に含まれます。 X-Ray SDK for Java に含まれているライブラリを使用する場合、同梱されているバージョンを使用する必要があります。たとえば、すでに実行時に Jackson に依存し、その依存関係のためにデプロイメントに JAR ファイルを含めている場合、SDK JAR には Jackson ライブラリの独自のバージョンが含まれているため、その JAR ファイルを削除する必要があります。 ## 依存関係管理 X-Ray SDK for Javaは、Maven から入手できます。 + **グループ** – `com.amazonaws` + **Artifact** – `aws-xray-recorder-sdk-bom` + **バージョン** – `2.11.0` Maven を使用してアプリケーションを構築する場合は、SDK を依存関係として `pom.xml` ファイルに追加します。 **Example pom.xml - 依存関係** ``` com.amazonaws aws-xray-recorder-sdk-bom 2.11.0 pom import com.amazonaws aws-xray-recorder-sdk-core com.amazonaws aws-xray-recorder-sdk-apache-http com.amazonaws aws-xray-recorder-sdk-aws-sdk com.amazonaws aws-xray-recorder-sdk-aws-sdk-instrumentor com.amazonaws aws-xray-recorder-sdk-sql-postgres com.amazonaws aws-xray-recorder-sdk-sql-mysql ``` Gradle の場合は、SDK をコンパイル時の依存関係として `build.gradle` ファイルに追加します。 **Example 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") compile("com.amazonaws:aws-xray-recorder-sdk-apache-http") compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres") compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql") testCompile("junit:junit:4.11") } dependencyManagement { imports { mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39') mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0') } } ``` Elastic Beanstalk を使用してアプリケーションをデプロイする場合、すべての依存関係を含んだ大きなアーカイブを構築してアップロードする代わりに、Maven または Gradle を使用してデプロイするたびにオンインスタンスで構築できます。Gradle の使用例については、[サンプルアプリケーション](xray-scorekeep.md)を参照してください。 # 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\$1XRAY\$1TRACING\$1NAME | com.amazonaws.xray.strategy.tracingName | XRayInstrumentedService | | contextMissingStrategy | String | LOG\$1ERROR、IGNORE\$1ERROR | エージェントが X-Ray セグメントコンテキストを使用しようとするが、存在しないときに実行するアクション。 | AWS\$1XRAY\$1CONTEXT\$1MISSING | com.amazonaws.xray.strategy.contextMissingStrategy | LOG\$1ERROR | | DaemonAddress | String | フォーマットされた IP アドレスとポート、または TCP および UDP アドレスのリスト | X-Ray デーモンとの通信にエージェントが使用するアドレス。 | AWS\$1XRAY\$1DAEMON\$1ADDRESS | com.amazonaws.xray.emitter.daemonAddress | 127.0.0.1:2000 | | tracingEnabled | ブール値 | True、False | X-Ray エージェントによる計測を有効にします。 | AWS\$1XRAY\$1TRACING\$1ENABLED | 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)を参照してください。 # X-Ray SDK for 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)」を参照してください。 X-Ray SDK for Java には、グローバルレコーダーを提供する `AWSXRay` というクラスが含まれます。これは、コードの計測に使用できる `TracingHandler` です。グローバルレコーダーを設定して、受信 HTTP 呼び出しのセグメントを作成する `AWSXRayServletFilter` をカスタマイズできます。 **Topics** + [サービスプラグイン](#xray-sdk-java-configuration-plugins) + [サンプリングルール](#xray-sdk-java-configuration-sampling) + [ログ記録](#xray-sdk-java-configuration-logging) + [セグメントリスナー](#xray-sdk-java-configuration-listeners) + [環境変数](#xray-sdk-java-configuration-envvars) + [システムプロパティ](#xray-sdk-java-configuration-sysprops) ## サービスプラグイン `plugins`を使用して、アプリケーションをホストしているサービスに関する情報を記録します。 **プラグイン** + Amazon EC2 —`EC2Plugin`は、インスタンス ID、アベイラビリティーゾーン、および CloudWatch Logs グループを追加します。 + ElasticBeanstalk– `ElasticBeanstalkPlugin`は、環境名、バージョンラベル、およびデプロイ ID を追加します。 + Amazon ECS — `ECSPlugin`は、コンテナ ID を追加します。 + Amazon EKS – `EKSPlugin` は、コンテナ ID、クラスター名、ポッド ID、および CloudWatch Logs グループを追加します。 ![\[Amazon EC2 および Elastic Beanstalk プラグインでリソースデータをセグメント化します。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources.png) プラグインを使用するには、`AWSXRayRecorderBuilder` で `withPlugin` を呼び出します。 **Example src/main/java/scorekeep/WebConfig.java - レコーダー** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.plugins.ElasticBeanstalkPlugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/ElasticBeanstalkPlugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); @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()); } } ``` また、SDK はプラグインの設定を利用して、セグメントの `origin` フィールドを設定します。これは、アプリケーションを実行する AWS リソースのタイプを示します。複数のプラグインを使用する場合、SDK は次の解決順序を使用して起点を決定します。ElasticBeanStalk > EKS > ECS > EC2。 ## サンプリングルール SDK は X-Ray コンソールで定義したサンプリングルールを使用し、記録するリクエストを決定します。デフォルトルールでは、最初のリクエストを毎秒トレースし、X-Ray にトレースを送信するすべてのサービスで追加のリクエストの 5% をトレースします。[X-Ray コンソールに追加のルールを作成する](xray-console-sampling.md)をクリックして、各アプリケーションで記録されるデータ量をカスタマイズします。 SDK は、定義された順序でカスタムルールを適用します。リクエストが複数のカスタムルールと一致する場合、SDK は最初のルールのみを適用します。 **注記** SDK が X-Ray に到達してサンプリングルールを取得できない場合、1 秒ごとに最初のリクエストのデフォルトのローカルルールに戻り、ホストあたりの追加リクエストの 5% に戻ります。これは、ホストがサンプリング API を呼び出す権限を持っていない場合や、SDK によって行われる API 呼び出しの TCP プロキシとして機能する X-Ray デーモンに接続できない場合に発生します。 JSON ドキュメントからサンプリングルールをロードするように SDK を設定することもできます。SDK は、X-Ray サンプリングが利用できない場合のバックアップとしてローカルルールを使用することも、ローカルルールを排他的に使用することもできます。 **Example sampling-rules.json** ``` { "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } } ``` この例では、1 つのカスタムルールとデフォルトルールを定義します。カスタムルールでは、5 パーセントのサンプリングレートが適用され、`/api/move/`以下のパスに対してトレースするリクエストの最小数はありません。デフォルトのルールでは、1秒ごとの最初のリクエストおよび追加リクエストの 10 パーセントをトレースします。 ルールをローカルで定義することの欠点は、固定ターゲットが X-Ray サービスによって管理されるのではなく、レコーダーの各インスタンスによって個別に適用されることです。より多くのホストをデプロイすると、固定レートが乗算され、記録されるデータ量の制御が難しくなります。 では AWS Lambda、サンプリングレートを変更することはできません。関数がインストルメント化されたサービスによって呼び出された場合、そのサービスによってサンプリングされたリクエストを生成した呼び出しは Lambda によって記録されます。アクティブなトレースが有効で、トレースヘッダーが存在しない場合、Lambda はサンプリングを決定します。 Spring でバックアップルールを提供するには、設定クラスの `CentralizedSamplingStrategy` にグローバルレコーダーを設定します。 **Example src/main/java/myapp/WebConfig.java – レコーダーの設定** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); @Configuration public class WebConfig { static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } ``` Tomcat の場合、`ServletContextListener` を拡張するリスナーを追加し、デプロイ記述子にリスナーを登録します。 **Example src/com/myapp/web/Startup.java** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); import java.net.URL; import javax.servlet.ServletContextEvent; import javax.servlet.ServletContextListener; public class Startup implements ServletContextListener { @Override public void contextInitialized(ServletContextEvent event) { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()); URL ruleFile = Startup.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } @Override public void contextDestroyed(ServletContextEvent event) { } } ``` **Example WEB-INF/web.xml** ``` ... com.myapp.web.Startup ``` ローカルルールのみを使用するには、`CentralizedSamplingStrategy` を `LocalizedSamplingStrategy` に置き換えます。 ``` builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); ``` ## ログ記録 デフォルトでは、SDK はアプリケーションログに `ERROR`-レベルのメッセージを出力します。SDK でデバッグレベルのログを有効にすると、より詳細なログをアプリケーションログファイルに出力できます。有効なログレベルは、`DEBUG`、`INFO`、`WARN`、`ERROR`、`FATAL` です。`FATAL` ログレベルは、SDK が致命的なレベルでログを記録しないため、すべてのログメッセージを消去します。 **Example application.properties** `logging.level.com.amazonaws.xray` プロパティを使用してログレベルを設定します。 ``` logging.level.com.amazonaws.xray = DEBUG ``` デバッグログを使用して問題を識別します。たとえば、「[サブセグメントを手動で生成する](xray-sdk-java-subsegments.md)」場合にサブセグメントが閉じない問題などです。 ### ログへのトレース ID の挿入 ログステートメントに現在の完全修飾トレース ID を公開するには、マップされた診断コンテキスト (MDC) に ID を挿入できます。`SegmentListener` インターフェイスを使用して、セグメントライフサイクルイベント中に X-Ray レコーダーからメソッドが呼び出されます。セグメントまたはサブセグメントが開始されると、修飾トレース ID がキー `AWS-XRAY-TRACE-ID` と共に MDC に挿入されます。そのセグメントが終了すると、キーは MDC から削除されます。これにより、トレース ID が使用中のログ記録ライブラリに公開されます。サブセグメントが終了すると、その親 ID が MDC に挿入されます。 **Example 完全修飾トレース ID** 完全修飾 ID は `TraceID@EntityID` として表されます ``` 1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3 ``` この機能は、 AWS X-Ray SDK for Java で計測された Java アプリケーションで動作し、次のログ記録設定をサポートします。 + Logback バックエンドを使用する SLF4J フロントエンド API + Log4J2 バックエンドを使用する SLF4J フロントエンド API + Log4J2 バックエンドを使用する Log4J2 フロントエンド API 各フロントエンドと各バックエンドのニーズについては、以下のタブを参照してください。 ------ #### [ SLF4J Frontend ] 1. 以下の Maven 依存関係をプロジェクトに追加します。 ``` com.amazonaws aws-xray-recorder-sdk-slf4j 2.11.0 ``` 1. `AWSXRayRecorder` を構築するときに `withSegmentListener` メソッドを含めます。これにより、`SegmentListener` クラスが追加されて、SLF4J MDC に新しいトレース ID が自動的に挿入されるようになります。 `SegmentListener` は、ログステートメントのプレフィクスを設定するためのパラメータとしてオプションの文字列を取ります。プレフィクスは、次の方法で設定できます。 + **なし** – デフォルトの `AWS-XRAY-TRACE-ID` プレフィックスを使用します。 + **空** – 空の文字列を使用します (例:`""`)。 + **カスタム** – 文字列で定義されているカスタムプレフィックスを使用します。 **Example `AWSXRayRecorderBuilder` ステートメント** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX")); ``` ------ #### [ Log4J2 front end ] 1. 以下の Maven 依存関係をプロジェクトに追加します。 ``` com.amazonaws aws-xray-recorder-sdk-log4j 2.11.0 ``` 1. `AWSXRayRecorder` を構築するときに `withSegmentListener` メソッドを含めます。これにより、`SegmentListener` クラスが追加されて、SLF4J MDC に新しい完全修飾トレース ID が自動的に挿入されるようになります。 `SegmentListener` は、ログステートメントのプレフィクスを設定するためのパラメータとしてオプションの文字列を取ります。プレフィクスは、次の方法で設定できます。 + **なし** – デフォルトの `AWS-XRAY-TRACE-ID` プレフィックスを使用します。 + **空** – 空の文字列 (例: `""`) を使用して、プレフィックスを削除します。 + **カスタム** – 文字列で定義されているカスタムプレフィックスを使用します。 **Example `AWSXRayRecorderBuilder` ステートメント** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX")); ``` ------ #### [ Logback backend ] トレース ID をログイベントに挿入するには、各ログ記録ステートメントを書式設定するロガーの `PatternLayout` を変更する必要があります。 1. `patternLayout` が設定されている場所を見つけます。これは、プログラムで行うことも、XML 設定ファイルを使用して行うこともできます。詳細については、「[Logback の設定](http://logback.qos.ch/manual/configuration.html)」を参照してください。 1. 以降のログ記録ステートメントにトレース ID を挿入するには、`patternLayout` の任意の場所に `%X{AWS-XRAY-TRACE-ID}` を挿入します。`%X{}` は、MDC から提供されたキーを使用して値を取得することを示します。Logback の PatternLayouts の詳細については、「[PatternLayout](https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout)」を参照してください。 ------ #### [ Log4J2 backend ] 1. `patternLayout` が設定されている場所を見つけます。これは、プログラムで行うことも、XML、JSON、YAML、またはプロパティ形式で記述された設定ファイルを使用して行うこともできます。 設定ファイルを使用した Log4J2 の設定の詳細については、「[設定](https://logging.apache.org/log4j/2.x/manual/configuration.html)」を参照してください。 プログラムによる Log4J2 の設定の詳細については、「[プログラムによる設定](https://logging.apache.org/log4j/2.x/manual/customconfig.html)」を参照してください。 1. 以降のログ記録ステートメントにトレース ID を挿入するには、`PatternLayout` の任意の場所に `%X{AWS-XRAY-TRACE-ID}` を挿入します。`%X{}` は、MDC から提供されたキーを使用して値を取得することを示します。Log4J2 の PatternLayouts の詳細については、「[パターンレイアウト](https://logging.apache.org/log4j/2.x/manual/layouts.html#Pattern_Layout)」を参照してください。 ------ **トレース ID の挿入の例** 以下に示しているのは、トレース ID を含むように変更された `PatternLayout` 文字列です。トレース ID は、スレッド名 (`%t`) の後、ログレベル (`%-5p`) の前に出力されます。 **Example ID を挿入した `PatternLayout`** ``` %d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n ``` AWS X-Ray は、簡単に解析できるように、ログステートメントにキーとトレース ID を自動的に出力します。以下に示しているのは、変更した `PatternLayout` を使用したログステートメントです。 **Example ID を挿入したログステートメント** ``` 2019-09-10 18:58:30.844 [nio-5000-exec-4] AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here ``` ログメッセージ自体はパターン `%m` に格納され、ロガーを呼び出すときに設定されます。 ## セグメントリスナー セグメントリスナーは、`AWSXRayRecorder` によって生成されたセグメントの開始と終了などのライフサイクルイベントをインターセプトするためのインターフェイスです。セグメントリスナーイベント関数の実装では、[https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-) で作成された場合にすべてのサブセグメントに同じ注釈を追加したり、[https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-) を使用して各セグメントがデーモンに送信された後にメッセージをログに記録したりします。または、[https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-) を使用して SQL インターセプターによって送信されたクエリを記録し、サブセグメントが SQL クエリを表しているかどうかを確認して、そうであればメタデータを追加します。 `SegmentListener` 関数の完全なリストについては、[AWS X-Ray Recorder SDK for Java API](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html) のドキュメントを参照してください。 次の例は、[https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-) での作成時にすべてのサブセグメントに一貫性のある注釈を追加し、[https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-) を使用して各セグメントの最後にログメッセージを出力する方法を示しています。 **Example MySegmentListener.java** ``` import com.amazonaws.xray.entities.Segment; import com.amazonaws.xray.entities.Subsegment; import com.amazonaws.xray.listeners.SegmentListener; public class MySegmentListener implements SegmentListener { ..... @Override public void onBeginSubsegment(Subsegment subsegment) { subsegment.putAnnotation("annotationKey", "annotationValue"); } @Override public void afterEndSegment(Segment segment) { // Be mindful not to mutate the segment logger.info("Segment with ID " + segment.getId()); } } ``` このカスタムセグメントリスナーは、`AWSXRayRecorder` を構築するときに参照されます。 **Example AWSXRayRecorderBuilder statement** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new MySegmentListener()); ``` ## 環境変数 環境変数を使用して、X-Ray SDK for Java を設定できます。SDK は次の変数をサポートしています。 + `AWS_XRAY_CONTEXT_MISSING` – 計測されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外をスローするには、`RUNTIME_ERROR` に設定します。 **有効な値** + `RUNTIME_ERROR`— ランタイム例外をスローします。 + `LOG_ERROR` – エラーをログ記録して続行します (デフォルト)。 + `IGNORE_ERROR` – エラーを無視して続行します。 オープン状態のリクエストがない場合、または新しいスレッドを発生させるコードで、スタートアップコードに実装されたクライアントを使用しようとした場合に発生する可能性がある、セグメントまたはサブセグメントの欠落に関連するエラー。 + `AWS_XRAY_DAEMON_ADDRESS` – X-Ray デーモンリスナーのホストとポートを設定します。デフォルトでは、SDK はトレースデータ (UDP) とサンプリング (TCP) の両方に`127.0.0.1:2000`を使用します。この変数は、デーモンを次のように構成している場合に使用します。[別のポートでリッスンする](xray-daemon-configuration.md)または、別のホストで実行されている場合。 **形式** + **同じポート** – `address:port` + **異なるポート** – `tcp:address:port udp:address:port` + `AWS_LOG_GROUP` - ロググループの名前を、ご使用のアプリケーションに関連付けられたロググループに設定します。ロググループがアプリケーションと同じ AWS アカウントとリージョンを使用している場合、X-Ray はこの指定されたロググループを使用してアプリケーションのセグメントデータを自動的に検索します。ロググループの詳細については、「[ロググループとストリームの操作](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)」を参照してください。 + `AWS_XRAY_TRACING_NAME` – SDK がセグメントに使用するサービス名を設定します。サーブレットフィルタの[セグメント命名ルール](xray-sdk-java-filters.md#xray-sdk-java-filters-naming)で設定したサービス名を上書きします。 環境変数は、同等の「[システムプロパティ](#xray-sdk-java-configuration-sysprops)」と、コードで設定される値を上書きします。 ## システムプロパティ システムプロパティは、「[環境変数](#xray-sdk-java-configuration-envvars)」に代わる JVM 固有の代替的な方法として使用できます。SDK では、以下のプロパティをサポートしています。 + `com.amazonaws.xray.strategy.tracingName` – `AWS_XRAY_TRACING_NAME` と同等です。 + `com.amazonaws.xray.emitters.daemonAddress` – `AWS_XRAY_DAEMON_ADDRESS` と同等です。 + `com.amazonaws.xray.strategy.contextMissingStrategy` – `AWS_XRAY_CONTEXT_MISSING` と同等です。 環境変数と同等の環境変数のいずれも設定されている場合は、環境変数の値が使用されます。どちらのメソッドでも、コードで設定される値は上書きされます。 # X-Ray SDK for 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)」を参照してください。 X-Ray SDK を使用して、アプリケーションが Amazon EC2 の EC2 インスタンス AWS Elastic Beanstalk、または Amazon ECS で処理する受信 HTTP リクエストをトレースできます。 Amazon EC2 `Filter` を使用して受信 HTTP リクエストを計測します。X-Ray サーブレットフィルターをアプリケーションに追加すると、X-Ray SDK for Java によってサンプリングされた各リクエストのセグメントが作成されます。このセグメントには、時間、メソッド、HTTP リクエストの処理などが含まれます。追加の計測により、このセグメントでサブセグメントが作成されます。 **注記** AWS Lambda 関数の場合、Lambda はサンプリングされたリクエストごとにセグメントを作成します。詳細については「[AWS Lambda および AWS X-Ray](xray-services-lambda.md)」を参照してください。 各セグメントには、サービスマップ内のアプリケーションを識別する名前があります。セグメントの名前は静的に指定することも、受信リクエストのホストヘッダーに基づいて動的に名前を付けるように SDK を設定することもできます。動的ネーミングでは、リクエスト内のドメイン名に基づいてトレースをグループ化でき、名前が予想されるパターンと一致しない場合（たとえば、ホストヘッダーが偽造されている場合）、デフォルト名を適用できます。 **転送されたリクエスト** ロードバランサーまたは他の仲介者がアプリケーションにリクエストを転送する場合、X-Ray は、クライアントの IP をIP パケットの送信元 IP からではなく、リクエストの`X-Forwarded-For`ヘッダーから取得します。転送されたリクエストについて記録されたクライアント IP は偽造される可能性があるため、信頼されるべきではありません。 リクエストが転送されると、それを示す追加フィールドが SDK によってセグメントに設定されます。セグメントのフィールド `x_forwarded_for` が `true` に設定されている場合、クライアント IP が HTTP リクエストの `X-Forwarded-For` ヘッダーから取得されます。 メッセージハンドラーは、次の情報が含まれる `http` ブロックを使用して、各受信リクエスト用にセグメントを作成します。 + **HTTP メソッド** – GET、POST、PUT、DELETE、その他。 + **クライアントアドレス** – リクエストを送信するクライアントの IP アドレス。 + **レスポンスコード** – 完了したリクエストの HTTP レスポンスコード。 + **タイミング** – 開始時間 (リクエストが受信された時間) および終了時間 (レスポンスが送信された時間)。 + **ユーザーエージェント** — リクエストからの`user-agent` + **コンテンツの長さ** — レスポンスからの`content-length` **Topics** + [トレースフィルタをアプリケーション (Tomcat) に追加する](#xray-sdk-java-filters-tomcat) + [トレースフィルタをアプリケーション (Spring) に追加する](#xray-sdk-java-filters-spring) + [セグメント命名ルールの設定](#xray-sdk-java-filters-naming) ## トレースフィルタをアプリケーション (Tomcat) に追加する Tomcat の場合は、プロジェクトの `` ファイルに `web.xml` を追加します。`fixedName` パラメーターを使用して、[サービス名](#xray-sdk-java-filters-naming)を指定し、着信リクエスト用に作成されたセグメントに適用します。 **Example WEB-INF/web.xml - Tomcat** ``` AWSXRayServletFilter com.amazonaws.xray.javax.servlet.AWSXRayServletFilter fixedName MyApp AWSXRayServletFilter * ``` ## トレースフィルタをアプリケーション (Spring) に追加する Spring の場合は、`WebConfig` クラスに `Filter` を追加します。セグメント名を文字列として [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) コンストラクタに渡します。 **Example src/main/java/myapp/WebConfig.java - Spring** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } } ``` ## セグメント命名ルールの設定 AWS X-Ray は*サービス名*を使用してアプリケーションを識別し、アプリケーションが使用する他のアプリケーション、データベース、外部 APIs、 AWS リソースと区別します。X-Ray SDK が受信リクエストのセグメントを生成すると、アプリケーションのサービス名がセグメントの[名前フィールド](xray-api-segmentdocuments.md#api-segmentdocuments-fields)に記録されます。 X-Ray SDK では、HTTP リクエストヘッダーのホスト名の後にセグメントの名前を指定できます。ただし、このヘッダーは偽造され、サービスマップに予期しないノードが発生する可能性があります。偽造されたホストヘッダーを持つリクエストによって SDK がセグメントの名前を間違えないようにするには、受信リクエストのデフォルト名を指定する必要があります。 アプリケーションが複数のドメインのリクエストを処理する場合、動的ネーミングストラテジーを使用してセグメント名にこれを反映するように SDK を設定できます。動的ネーミングストラテジーにより、SDK は予想されるパターンに一致するリクエストにホスト名を使用し、そうでないリクエストにデフォルト名を適用できます。 たとえば、3 つのサブドメイン（`www.example.com`,`api.example.com`,および`static.example.com`）に対してリクエストを処理する単一のアプリケーションがあるとします。動的ネーミングストラテジーをパターン `*.example.com` で使用して、異なる名前を持つ各サブドメインのセグメントを識別することができます。結果的にはサービスマップ上に 3 つのサービスノードを作成することになります。アプリケーションがパターンと一致しないホスト名のリクエストを受信すると、指定したフォールバック名を持つ 4 番目のノードがサービスマップに表示されます。 すべてのリクエストセグメントに対して同じ名前を使用するには、[前のセクション](#xray-sdk-java-filters-tomcat)で示すとおり、サーブレットフィルタを初期化するときに、アプリケーションの名前を指定します。これは、`SegmentNamingStrategy.fixed()` を呼び出して固定 [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html) を作成し、それを [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) コンストラクタに渡すのと同じ効果があります。 **注記** コードで定義したデフォルトのサービス名は、`AWS_XRAY_TRACING_NAME` [環境変数](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars)で上書きできます。 動的な命名戦略は、ホスト名と一致するようパターンを定義し、HTTP リクエストのホスト名がパターンと一致しない場合はデフォルトの名前を使用します。Tomcat で動的にセグメントに命名するには、`dynamicNamingRecognizedHosts` および `dynamicNamingFallbackName` を使用して、パターンとデフォルト名をそれぞれ定義します。 **Example WEB-INF/web.xml - 動的名前付けのサーブレットフィルタ** ``` AWSXRayServletFilter com.amazonaws.xray.javax.servlet.AWSXRayServletFilter dynamicNamingRecognizedHosts *.example.com dynamicNamingFallbackName MyApp AWSXRayServletFilter * ``` Spring の場合、`SegmentNamingStrategy.dynamic()`を呼び出して [動的SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html) を作成し、`AWSXRayServletFilter` コンストラクタに渡します。 **Example src/main/java/myapp/WebConfig.java - servlet filter with dynamic naming** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); import [com.amazonaws.xray.strategy.SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("MyApp", "*.example.com")); } } ``` # X-Ray AWS SDK for Java を使用した SDK 呼び出しのトレース **注記** X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKs/Daemon はメンテナンスモードに移行します。 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)」を参照してください。 アプリケーションが AWS のサービス を呼び出してデータの保存、キューへの書き込み、または通知の送信を行うと、X-Ray SDK for Java は[サブセグメントのダウンストリームの呼び出しを追跡します](xray-sdk-java-subsegments.md)。これらのサービス (例えば、Amazon S3 バケットまたは Amazon SQS キュー) 内でアクセスするトレースされた AWS のサービス およびリソースは、X-Ray コンソールのトレースマップではダウンストリームノードとして表示されます。 `aws-sdk` および `aws-sdk-instrumentor` [サブモジュール](xray-sdk-java.md#xray-sdk-java-submodules)をビルドに含めると、X-Ray SDK for Java では自動的にすべての AWS SDK クライアントを計測します。Instrumentor サブモジュールを含めない場合は、一部のクライアントを計測して他を除外できます。 個々のクライアントを計測するには、ビルドから`aws-sdk-instrumentor`サブモジュールを削除し、サービスのクライアントビルダーを使用して AWS SDK クライアント`TracingHandler`に `XRayClient` として を追加します。 たとえば、`AmazonDynamoDB` を計測するには、トレースハンドラーを `AmazonDynamoDBClientBuilder` に渡します。 **Example MyModel.java - DynamoDB クライアント** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.handlers.TracingHandler](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/handlers/TracingHandler.html); ... public class MyModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Regions.fromName(System.getenv("AWS_REGION"))) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build(); ... ``` すべてのサービスで、X-Ray コンソールで呼び出された API の名前を確認できます。サービスのサブセットの場合、X-Ray SDK はセグメントに情報を追加して、サービスマップでより細かく指定します。 たとえば、実装された DynamoDB クライアントでコールすると、SDK はテーブルをターゲットとするコールのセグメントにテーブル名を追加します。コンソールで、各テーブルはサービスマップ内に個別のノードとして表示され、テーブルをターゲットにしないコール用の汎用の DynamoDB ノードが表示されます。 **Example 項目を保存するための DynamoDB に対するコールのサブセグメント** ``` { "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", } } ``` 名前付きリソースにアクセスしたとき、次のサービスをコールすると、サービスマップに追加のノードが作成されます。特定のリソースをターゲットとしないコールでは、サービスの汎用ノードが作成されます。 + **Amazon DynamoDB** – テーブル名 + **Amazon Simple Storage Service** – バケットとキー名 + **Amazon Simple Queue Service** – キュー名 AWS SDK for Java 2.2 以降 AWS のサービス で へのダウンストリーム呼び出しを計測するには、ビルド設定から`aws-xray-recorder-sdk-aws-sdk-v2-instrumentor`モジュールを省略できます。その代わりに、`aws-xray-recorder-sdk-aws-sdk-v2 module` を含め、`TracingInterceptor` で設定して個々のクライアントを実装します。 **Example AWS SDK for Java 2.2 以降 - インターセプターのトレース** ``` import com.amazonaws.xray.interceptors.TracingInterceptor; import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration import software.amazon.awssdk.services.dynamodb.DynamoDbClient; //... public class MyModel { private DynamoDbClient client = DynamoDbClient.builder() .region(Region.US_WEST_2) .overrideConfiguration(ClientOverrideConfiguration.builder() .addExecutionInterceptor(new TracingInterceptor()) .build() ) .build(); //... ``` # X-Ray SDK for Java を使用してダウンストリーム HTTP ウェブサービスの呼び出しをトレースする **注記** 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)」を参照してください。 アプリケーションがマイクロサービスまたはパブリック HTTP API に呼び出しを実行する場合に、X-Ray SDK for Java の `HttpClient` バージョンを使用してこれらの呼び出しを計測し、API をダウンストリームサービスとしてサービスグラフに追加できます。 X-Ray SDK for Java には、送信 HTTP 呼び出しの計測と同等の Apache HttpComponents の代わりに使用できる `DefaultHttpClient` および `HttpClientBuilder` クラスが含まれています。 + `com.amazonaws.xray.proxies.apache.http.DefaultHttpClient` - `org.apache.http.impl.client.DefaultHttpClient` + `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder` - `org.apache.http.impl.client.HttpClientBuilder` これらのライブラリは、[`aws-xray-recorder-sdk-apache-http`](xray-sdk-java.md)サブモジュールにあります。 既存のインポートステートメントを X-Ray の該当部分に置き換えてすべてのクライアントを計測するか、クライアントを初期化する際に完全修飾名を使用して特定のクライアントを計測できます。 **Example HttpClientBuilder** ``` import com.fasterxml.jackson.databind.ObjectMapper; import org.apache.http.HttpEntity; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.util.EntityUtils; import [com.amazonaws.xray.proxies.apache.http.HttpClientBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/proxies/apache/http/HttpClientBuilder.html); ... public String randomName() throws IOException { CloseableHttpClient httpclient = HttpClientBuilder.create().build(); HttpGet httpGet = new HttpGet("http://names.example.com/api/"); CloseableHttpResponse response = httpclient.execute(httpGet); try { HttpEntity entity = response.getEntity(); InputStream inputStream = entity.getContent(); ObjectMapper mapper = new ObjectMapper(); Map jsonMap = mapper.readValue(inputStream, Map.class); String name = jsonMap.get("name"); EntityUtils.consume(entity); return name; } finally { response.close(); } } ``` ダウンストリームウェブ API に対する呼び出しを計測すると、X-Ray SDK for Java は HTTP リクエストおよびレスポンスに関する情報を含むセグメントを記録します。X-Ray はサブセグメントを使用してリモート API の推測セグメントを生成します。 **Example ダウンストリーム HTTP 呼び出しのサブセグメント** ``` { "id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com", "namespace": "remote", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } } } ``` **Example ダウンストリーム HTTP 呼び出しの推定セグメント** ``` { "id": "168416dc2ea97781", "name": "names.example.com", "trace_id": "1-62be1272-1b71c4274f39f122afa64eab", "start_time": 1484786387.131, "end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }, "inferred": true } ``` # X-Ray SDK for Java での SQL クエリのトレース **注記** 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)」を参照してください。 ## SQL インターセプター X-Ray SDK for Java JDBC インターセプターをデータソース設定に追加して、SQL データベースのクエリを計測します。 + **PostgreSQL** – `com.amazonaws.xray.sql.postgres.TracingInterceptor` + **MySQL** – `com.amazonaws.xray.sql.mysql.TracingInterceptor` これらのインターセプタは、それぞれ[`aws-xray-recorder-sql-postgres` と `aws-xray-recorder-sql-mysql` サブモジュール](xray-sdk-java.md)にあります｡ これらは、Tomcat の接続プールと互換性がある `org.apache.tomcat.jdbc.pool.JdbcInterceptor` を実装します｡ **注記** SQL インターセプタは、セキュリティ上の目的で SQL クエリ自体をサブセグメント内に記録しません。 Spring の場合は、プロパティファイルのインターセプターを追加し、スプリングブートの `DataSourceBuilder` を使用して、データソースを構築します。 **Example `src/main/java/resources/application.properties` - PostgreSQL JDBC Interceptor** ``` spring.datasource.continue-on-error=true spring.jpa.show-sql=false spring.jpa.hibernate.ddl-auto=create-drop spring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptor spring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect ``` **Example `src/main/java/myapp/WebConfig.java` - データソース** ``` import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.data.jpa.repository.config.EnableJpaRepositories; import javax.servlet.Filter; import javax.sql.DataSource; import java.net.URL; @Configuration @EnableAutoConfiguration @EnableJpaRepositories("myapp") public class RdsWebConfig { @Bean @ConfigurationProperties(prefix = "spring.datasource") public DataSource dataSource() { logger.info("Initializing PostgreSQL datasource"); return DataSourceBuilder.create() .driverClassName("org.postgresql.Driver") .url("jdbc:postgresql://" + System.getenv("RDS_HOSTNAME") + ":" + System.getenv("RDS_PORT") + "/ebdb") .username(System.getenv("RDS_USERNAME")) .password(System.getenv("RDS_PASSWORD")) .build(); } ... } ``` Tomcat の場合、X-Ray SDK for Java クラスを参照する JDBC データソースの `setJdbcInterceptors` を呼び出します。 **Example `src/main/myapp/model.java` - データソース** ``` import org.apache.tomcat.jdbc.pool.DataSource; ... DataSource source = new DataSource(); source.setUrl(url); source.setUsername(user); source.setPassword(password); source.setDriverClassName("com.mysql.jdbc.Driver"); source.setJdbcInterceptors("com.amazonaws.xray.sql.mysql.TracingInterceptor;"); ``` Tomcat JDBC データソースライブラリは、X-Ray SDK for Java に含まれていますが、使用するドキュメントへの指定された依存関係として宣言できます。 **Example `pom.xml` - JDBC Data Source** ``` org.apache.tomcat tomcat-jdbc 8.0.36 provided ``` ## ネイティブ SQL トレースデコレータ + [https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql](https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql) を依存関係に追加します。 + データベースのデータソース、接続、またはステートメントを修飾します。 ``` dataSource = TracingDataSource.decorate(dataSource) connection = TracingConnection.decorate(connection) statement = TracingStatement.decorateStatement(statement) preparedStatement = TracingStatement.decoratePreparedStatement(preparedStatement, sql) callableStatement = TracingStatement.decorateCallableStatement(callableStatement, sql) ``` # X-Ray SDK for 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)」を参照してください。 サブセグメントはリクエストを処理するために行われた作業の詳細を含んだトレースの[セグメント](xray-concepts.md#xray-concepts-segments)を拡張します。計測済みクライアント内で呼び出しを行うたびに、X-Ray SDK によってサブセグメントに生成された情報が記録されます。追加のサブセグメントを作成して、他のサブセグメントをグループ化したり、コードセクションのパフォーマンスを測定したり、注釈とメタデータを記録したりできます。 サブセグメントを管理するには、`beginSubsegment` および `endSubsegment` メソッドを使用します。 **Example GameModel.java - カスタムサブセグメント** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("Save Game"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` この例では、サブセグメント内のコードは、セッションモデルの メソッドを使用して DynamoDB からゲームのセッションをロードし、 AWS SDK for Javaの DynamoDB マッパーを使用してゲームを保存します。このコードをサブセグメントにラップすることで、呼び出しが `Save Game` サブセグメントの DynamoDB の子としてコンソールのトレースビューに表示されます。 ![\[Timeline showing Scorekeep and DynamoDB operations with durations and status checks.\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-PUTrules-timeline-subsegments.png) サブセグメントのコードがチェック例外をスローした場合は、`try` ブロックにコードをラップして、`finally` ブロックで `AWSXRay.endSubsegment()` を呼び出し、常にサブセグメントが閉じられるようにします。サブセグメントが閉じていない場合は、親セグメントが完了できず、X-Ray に送信されません。 チェック例外をスローしないコードの場合は、コードを Lambda 関数として `AWSXRay.CreateSubsegment` に渡すことができます。 **Example Lambda 関数のサブセグメント** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); AWSXRay.createSubsegment("getMovies", (subsegment) -> { // function code }); ``` セグメントまたは別のサブセグメント内にサブセグメントを作成する場合、X-Ray SDK for Java によってその ID が生成され、開始時刻と終了時刻が記録されます。 **Example サブセグメントとメタデータ** ``` "subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } }, ``` 非同期やマルチスレッドのプログラミングでは、非同期実行中に X-Ray コンテキストが変更されることがあるため、サブセグメントを `endSubsegment()` メソッドに手動で渡して正しく閉じるようにする必要があります。親セグメントが閉じられた後に非同期サブセグメントが閉じられた場合、このメソッドはセグメント全体を X-Ray デーモンに自動的にストリームします。 **Example 非同期サブセグメント** ``` @GetMapping("/api") public ResponseEntity api() { CompletableFuture.runAsync(() -> { Subsegment subsegment = AWSXRay.beginSubsegment("Async Work"); try { Thread.sleep(3000); } catch (InterruptedException e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(subsegment); } }); return ResponseEntity.ok().build(); } ``` # X-Ray SDK for 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)」を参照してください。 リクエスト、環境、または注釈やメタデータを使用するアプリケーションに関する追加情報を記録できます。X-Ray SDK が作成するセグメントまたは作成するカスタムサブセグメントに、注釈およびメタデータを追加できます。 **注釈**は文字列、数値、またはブール値を使用したキーと値のペアです。注釈は、[フィルタ式](xray-console-filters.md)用にインデックス付けされます。注釈を使用して、コンソールでトレースをグループ化するため、または[https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API を呼び出すときに使用するデータを記録します。 **メタデータ**は、オブジェクトとリストを含む、任意のタイプの値を持つことができるキーバリューのペアですが、フィルタ式に使用するためにインデックスは作成されません。メタデータを使用してトレースに保存する追加のデータを記録しますが、検索で使用する必要はありません。 注釈とメタデータに加えて、セグメントに[ユーザー ID 文字列を記録](#xray-sdk-java-segment-userid)することもできます。ユーザー ID はセグメントの個別のフィールドに記録され、検索用にインデックスが作成されます。 **Topics** + [X-Ray SDK for Java での注釈の記録](#xray-sdk-java-segment-annotations) + [X-Ray SDK for Java を使用したメタデータの記録](#xray-sdk-java-segment-metadata) + [X-Ray SDK for Javaを使用したユーザー ID の記録](#xray-sdk-java-segment-userid) ## X-Ray SDK for Java での注釈の記録 注釈を使用して、検索用にインデックスを作成するセグメントまたはサブセグメントに情報を記録します。 **注釈の要件** + **キー** – X-Ray 注釈のキーには最大 500 文字の英数字を使用できます。スペースまたはドットやピリオド (.) 以外の記号は使用できません。 + **値** – X-Ray 注釈の値には最大 1,000 の Unicode 文字を使用できます。 + **注釈**の数 – トレースごとに最大 50 の注釈を使用できます。 **注釈を記録するには** 1. `AWSXRay` から現在のセグメントまたはサブセグメントの参照を取得します。 ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` または ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Subsegment document = AWSXRay.getCurrentSubsegment(); ``` 1. 文字列キー、および、ブール値、数値、文字列値を使用して `putAnnotation` を呼び出します。 ``` document.putAnnotation("mykey", "my value"); ``` 次の例は、ドット、ブール値、数値、または文字列値を含む文字列キーを使用して `putAnnotation` を呼び出す方法を示しています。 ``` document.putAnnotation("testkey.test", "my value"); ``` SDK は、セグメントドキュメントの `annotations` オブジェクトにキーと値のペアとして、注釈を記録します。同じキーで `putAnnotation` を 2 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。 特定の値を持つ注釈のあるトレースを見つけるには、`annotation[key]`フィルタ式[の ](xray-console-filters.md) キーワードを使用します。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java) – 注釈とメタデータ** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` ## X-Ray SDK for Java を使用したメタデータの記録 メタデータを使用して、検索用にインデックスを作成する必要のないセグメントまたはサブセグメントに情報を記録します。メタデータ値は、文字列、数値、ブール値、または JSON オブジェクトや JSON 配列にシリアル化できる任意のオブジェクトになります。 **メタデータを記録するには** 1. `AWSXRay` から現在のセグメントまたはサブセグメントの参照を取得します。 ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` または ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Subsegment document = AWSXRay.getCurrentSubsegment(); ``` 1. 文字列名前空間、文字列キー、ブール値、数値、文字列値、オブジェクト値を使用して `putMetadata` を呼び出します。 ``` document.putMetadata("my namespace", "my key", "my value"); ``` または キーと値だけを使用して `putMetadata` を呼び出します。 ``` document.putMetadata("my key", "my value"); ``` 名前空間を指定しない場合、SDK は `default` を使用します。同じキーで `putMetadata` を 2 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java) – 注釈とメタデータ** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` ## X-Ray SDK for Javaを使用したユーザー ID の記録 リクエストセグメントにユーザー ID を記録して、リクエストを送信したユーザーを識別します。 **ユーザー ID を記録するには** 1. `AWSXRay` から現在のセグメントへの参照を取得します。 ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` 1. リクエストを送信したユーザーの文字列 ID を使用して `setUser` を呼び出します。 ``` document.setUser("U12345"); ``` コントローラーで `setUser` を呼び出し、アプリケーションがリクエストの処理を開始するとすぐに、ユーザー ID を記録できます。ユーザー ID を設定するためだけにセグメントを使用する場合、呼び出しを 1 行で連鎖させることができます。 **Example [src/main/java/scorekeep/MoveController.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java) – ユーザー ID** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... @RequestMapping(value="/{userId}", method=RequestMethod.POST) public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException { AWSXRay.getCurrentSegment().setUser(userId); return moveFactory.newMove(sessionId, gameId, userId, move); } ``` ユーザー ID のトレースを見つけるには、`user`フィルタ式[で、](xray-console-filters.md) キーワードを使用します。 ## AWS X-Ray X-Ray SDK for Java の メトリクス **注記** X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKs/Daemon はメンテナンスモードに移行します。 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)」を参照してください。 このトピックでは、 AWS X-Ray 名前空間、メトリクス、ディメンションについて説明します。X-Ray SDK for Java を使用して、収集した X-Ray セグメントから、サンプリングされていない Amazon CloudWatch メトリクスを公開できます。これらのメトリクスは、セグメントの開始時間と終了時間、さらにエラー、障害、スロットリングのステータスフラグから取得されます。これらの追跡メトリクスを使用して、サブセグメント内の再試行と依存関係の問題を公開します。 CloudWatch はメトリクスリポジトリです。メトリクスは CloudWatch の基本的概念で、時系列に並んだデータポイントのセットを表しています。(または AWS のサービス) メトリクスデータポイントを CloudWatch に発行し、それらのデータポイントに関する統計を時系列データの順序付けられたセットとして取得します。 メトリクスは名前、名前空間、1 つ以上のディメンションで一意に定義されます。各データポイントには、タイムスタンプと、オプションとして測定単位があります。統計を要求した場合、返されるデータストリームは、名前空間、メトリクス名、ディメンションによって識別されます。 CloudWatch の詳細については、「[https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/)」を参照してください。 ### X-Ray CloudWatch メトリクス `ServiceMetrics/SDK` 名前空間には、次のメトリクスが含まれます。 | メトリクス | 利用可能な統計情報 | 説明 | 単位 | | --- | --- | --- | --- | | `Latency` | Average、Minimum、Maximum、Count | 開始時間と終了時間の差。Average、Minimum、Maximum はすべて、オペレーション関連のレイテンシーを表します。Count は、呼び出し数を表します。 | ミリ秒 | | `ErrorRate` | Average、Sum | `4xx Client Error` ステータスコードで失敗し、エラーになったリクエストの割合。 | 割合 (%) | | `FaultRate` | Average、Sum | `5xx Server Error` ステータスコードで失敗し、障害になったトレースの割合。 | 割合 (%) | | `ThrottleRate` | Average、Sum | `429` ステータスコードを返すスロットリングトレースの割合。これは `ErrorRate` メトリクスのサブセットです。 | 割合 (%) | | `OkRate` | Average、Sum | トレースされた後、`OK` ステータスコードになったリクエストの割合。 | 割合 (%) | ### X-Ray CloudWatch ディメンション 以下の表のディメンションを使用して、X-Ray によって計測された Java アプリケーションに対して返されるメトリクスを絞り込みます。 | ディメンション | 説明 | | --- | --- | | `ServiceType` | 不明な場合、サービスのタイプ (`AWS::EC2::Instance`、`NONE` など)。 | | `ServiceName` | サービスの正規名。 | ### X-Ray CloudWatch メトリクスを有効にする 以下の手順を使用して、計測された Java アプリケーションでトレースメトリクスを有効にします。 **トレースメトリクスを設定するには** 1. `aws-xray-recorder-sdk-metrics` パッケージを Apache Maven 依存関係として追加します。詳細は、X-Ray SDK for Java [サブモジュール](#xray-sdk-java-submodules)を参照してください。 1. グローバルレコーダービルドの一部として新しい `MetricsSegmentListener()` を有効にします。 **Example src/com/myapp/web/Startup.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()) .withSegmentListener(new MetricsSegmentListener()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } } ``` 1. CloudWatch エージェントをデプロイして、Amazon Elastic Compute Cloud (Amazon EC2)、Amazon Elastic Container Service (Amazon ECS)、または Amazon Elastic Kubernetes Service (Amazon EKS) を使用してメトリクスを収集します。 + Amazon EC2 を設定するには、「[CloudWatch エージェントのインストール](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance.html)」を参照してください。 + Amazon ECS を設定するには、「[Container Insights を使用して Amazon ECS コンテナをモニタリングする](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cloudwatch-container-insights.html)」を参照してください。 + Amazon ESK を設定するには、「[Amazon CloudWatch Observability EKS アドオンを使用して CloudWatch エージェントをインストールする](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html)」を参照してください。 1. CloudWatch エージェントと通信するように SDK を設定します。デフォルトでは、SDK はアドレス `127.0.0.1` の CloudWatch エージェントと通信します。環境変数または Java プロパティを `address:port` に設定することで、代替アドレスを設定できます。 **Example 環境変数** ``` AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port ``` **Example Java のプロパティ** ``` com.amazonaws.xray.metrics.daemonAddress=address:port ``` **設定を検証するには** 1. にサインイン AWS マネジメントコンソール し、[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) で CloudWatch コンソールを開きます。 1. [**Metrics (メトリクス)**] タブを開いて、メトリクスの到着を確認します。 1. (オプション) CloudWatch コンソールのLogs **(ログ) タブ**で、`ServiceMetricsSDK`ロググループを開きます。ホストメトリクスに一致するログストリームを探し、ログメッセージを確認します。 # マルチスレッドアプリケーションでのスレッド間のセグメントコンテキストの受け渡し **注記** 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)」を参照してください。 アプリケーションで新しいスレッドを作成すると、`AWSXRayRecorder` は現在のセグメントまたはサブセグメント [Entity](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html) への参照を保持しません。実装されたクライアントを新しいスレッドで使用すると、SDK は存在しないセグメントに書き込みを試み、[SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html) が発生します。 開発中に例外をスローしないようにするには、代わりにエラーを記録するよう指示する [ContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/ContextMissingStrategy.html) でレコーダーを設定します。[SetContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#setContextMissingStrategy(com.amazonaws.xray.strategy.ContextMissingStrategy)) を使用してコード内に戦略を設定するか､[環境変数](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars) または [システムプロパティ](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sysprops)を使用して同等のオプションを設定することができます｡ エラーに対処する 1 つの方法として、スレッドを開始するときに [beginSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#beginSegment(java.lang.String)) を呼び出して新しいセグメントを使用する方法と､スレッドを終了するときに [endSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#endSegment--) を使用する方法があります｡ これは、アプリケーションの起動時に実行されるコードのように、HTTP リクエストに応答して実行されないコードを実装する場合に機能します。 複数のスレッドを使用して着信リクエストを処理する場合は、現在のセグメントまたはサブセグメントを新しいスレッドに渡してグローバルレコーダーに渡すことができます。これにより、新しいスレッド内に記録された情報が、そのリクエストに関して記録された残りの情報と同じセグメントに関連付けられることが保証されます。新しいスレッドでセグメントが使用可能になると、そのセグメントのコンテキストにアクセスできる任意の実行可能なファイルを `segment.run(() -> { ... })` メソッドで実行できるようになります。 例については、「[実装されたクライアントをワーカースレッドで使用する](scorekeep-workerthreads.md)」を参照してください。 ## 非同期プログラミングでの X-Ray の使用 X-Ray SDK for Java は、[SegmentContextExecutors](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/contexts/SegmentContextExecutors.html) を使用した非同期 Java プログラムで使用できます。SegmentContextExecutor は Executor インターフェイスを実装しており、[CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) のすべての非同期操作に渡せます。これにより、非同期オペレーションがそのコンテキスト内で正しいセグメントで実行されることが保証されます。 **Example App.java 例: SegmentContextExecutor を CompletableFuture に渡す** ``` DynamoDbAsyncClient client = DynamoDbAsyncClient.create(); AWSXRay.beginSegment(); // ... client.getItem(request).thenComposeAsync(response -> { // If we did not provide the segment context executor, this request would not be traced correctly. return client.getItem(request2); }, SegmentContextExecutors.newSegmentContextExecutor()); ``` # Spring による AOP と X-Ray SDK for 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)」を参照してください。 このトピックでは、X-Ray SDK および Spring Framework を使用して、コアロジックを変更せずにアプリケーションを計測する方法について説明します。つまり、リモートで実行されているアプリケーションをインストルメントする非侵襲的な方法が追加されました AWS。 **Spring で AOP を有効にするには** 1. [Spring を設定します](#xray-sdk-java-aop-spring-configuration) 1. [トレースフィルターをアプリケーションに追加する](#xray-sdk-java-aop-filters-spring) 1. [コードに注釈を付けるか、インターフェイスを実装します](#xray-sdk-java-aop-annotate-or-implement) 1. [アプリケーションで X-Ray を有効化します](#xray-sdk-java-aop-activate-xray) ## Spring の設定 Maven または Gradle を使用して、AOP でアプリケーションを計測するように Spring を設定できます。 Maven を使用してアプリケーションを構築する場合は、次の依存関係を `pom.xml` ファイルに追加します。 ``` com.amazonaws aws-xray-recorder-sdk-spring 2.11.0 ``` Gradle の場合は、次の依存関係を `build.gradle` ファイルに追加します。 ``` compile 'com.amazonaws:aws-xray-recorder-sdk-spring:2.11.0' ``` ## Spring Boot の設定 前のセクションで説明した Spring の依存関係に加えて、Spring Boot を使用している場合で、それがまだクラスパス上にない場合は、次の依存関係を追加します。 Maven: ``` org.springframework.boot spring-boot-starter-aop 2.5.2 ``` Gradle: ``` compile 'org.springframework.boot:spring-boot-starter-aop:2.5.2' ``` ## トレースフィルターをアプリケーションに追加する `WebConfig` のクラスに `Filter` を追加します。セグメント名を文字列として [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) コンストラクタに渡します。フィルターのトレースおよび受信リクエストの計測の詳細については、「[X-Ray SDK for Java を使用して受信リクエストをトレースします。](xray-sdk-java-filters.md)」を参照してください。 **Example src/main/java/myapp/WebConfig.java - Spring** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } } ``` ## Jakarta のサポート Spring 6 の Enterprise Edition では、Javax ではなく [Jakarta](https://spring.io/blog/2022/11/16/spring-framework-6-0-goes-ga) を使用しています。この新しい名前空間をサポートするために、X-Ray では独自の Jakarta 名前空間に存在するクラスの並列セットを作成しました。 フィルタークラスの場合は、`javax` を `jakarta` に置き換えてください。セグメント命名ルールを設定するときは、次の例のように、命名ルールクラス名の前に `jakarta` を追加してください。 ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import jakarta.servlet.Filter; import com.amazonaws.xray.jakarta.servlet.AWSXRayServletFilter; import com.amazonaws.xray.strategy.jakarta.SegmentNamingStrategy; @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("Scorekeep")); } } ``` ## コードに注釈を付ける、またはインターフェイスを実装する クラスには `@XRayEnabled` の注釈を付けるか、`XRayTraced` インターフェイスを実装する必要があります。これにより、X-Ray の計測のため、影響を受けた関数をラップするように AOP システムに伝えます。 ## アプリケーションでの X-Ray のアクティベーション アプリケーションで X-Ray トレースを有効化するには、コードで次のメソッドをオーバーライドして、抽象クラス `BaseAbstractXRayInterceptor` を拡張する必要があります。 + `generateMetadata`—この関数では、現在の関数のトレースにアタッチされたメタデータをカスタマイズできます。デフォルトでは、実行中の関数のクラス名がメタデータに記録されます。追加情報が必要な場合は、さらにデータを追加できます。 + `xrayEnabledClasses`—この関数は空であり、空のままにしておく必要があります。これは、ラップするメソッドをインターセプターに指示するポイントカットのホストとして機能します。`@XRayEnabled` の注釈が付けられたどのクラスをトレースするか指定して、ポイントカットを定義します。次のステートメントは、`@XRayEnabled` という注釈が付けられたすべてのコントローラービーンをラップするようにインターセプターに伝えます。 ``` @Pointcut(“@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)”) ``` プロジェクトで Spring Data JPA を使用している場合は、`BaseAbstractXRayInterceptor` ではなく `AbstractXRayInterceptor` から拡張することを検討してください。 ## 例 次のコードは、抽象クラス `BaseAbstractXRayInterceptor`を示しています。 ``` @Aspect @Component public class XRayInspector extends BaseAbstractXRayInterceptor { @Override protected Map> generateMetadata(ProceedingJoinPoint proceedingJoinPoint, Subsegment subsegment) throws Exception { return super.generateMetadata(proceedingJoinPoint, subsegment); } @Override @Pointcut("@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)") public void xrayEnabledClasses() {} } ``` 次のコードは、X-Ray によって計測されるクラスです。 ``` @Service @XRayEnabled public class MyServiceImpl implements MyService { private final MyEntityRepository myEntityRepository; @Autowired public MyServiceImpl(MyEntityRepository myEntityRepository) { this.myEntityRepository = myEntityRepository; } @Transactional(readOnly = true) public List getMyEntities(){ try(Stream entityStream = this.myEntityRepository.streamAll()){ return entityStream.sorted().collect(Collectors.toList()); } } } ``` アプリケーションを正しく設定した場合は、コンソールの次のスクリーンショットに示すように、コントローラーからサービス呼び出しまで、アプリケーションの完全なコールスタックが表示されます。 ![\[Timeline showing API call duration and breakdown of server operations for metering service.\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/aop-spring-console.png)