翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 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 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`ロググループを開きます。ホストメトリクスに一致するログストリームを探し、ログメッセージを確認します。