AWS X-Ray SDK for Java

The X-Ray SDK for Java ウェブアプリケーション用のライブラリのセットです。トレースデータを作成し X-Ray デーモンに送信するためのクラスおよびメソッドを提供します。トレースデータには、アプリケーションによって処理された受信 HTTP リクエスト、およびアプリケーションから AWS SDK を使用したダウンストリームサービス、HTTP クライアント、または SQL データベースコネクターに対して行われる呼び出しに関する情報が含まれています。セグメントを手動で作成し、注釈およびメタデータにデバッグ情報を追加することもできます。

注記

The X-Ray SDK for Java は、オープンソースプロジェクトです。プロジェクトに従って、GitHub github.com/aws/aws-xray-sdk-java で問題とプルリクエストを送信できます。

受信リクエストのトレースは、AWSXRayServletFilter をサーブレットフィルタとして追加することから開始します。サーブレットフィルタにより、セグメントが作成されます。セグメントが開いている間、SDK クライアントのメソッドを使用してセグメントに情報を追加し、サブセグメントを作成してダウンストリーム呼び出しをトレースできます。また、SDK では、セグメントが開いている間にアプリケーションがスローする例外を自動的に記録します。

リリース 1.3 以降では、Spring のアスペクト指向プログラミング (AOP) を使用してアプリケーションを計測できます。これにより、アプリケーションのランタイムにコードを追加することなく、AWS で実行中にアプリケーションを計測することができます。

次に、Java 用 X-Ray SDK を使用して、AWS SDK for Java クライアントをSDK Instrumentor サブモジュールを含むをビルド設定で使用します。計測済みクライアントを使用して、ダウンストリーム AWS サービスやリソースに対して呼び出しを行うたびに、SDK は、サブセグメントの呼び出しに関する情報を記録します。サービス内でアクセスする AWS サービスおよびリソースは、サービスマップにダウンストリームノードとして表示され、個々の接続でエラーとスロットリングの問題を識別するのに役立ちます。

AWS のサービスに対するダウンストリーム呼び出しのすべてを計測するわけではない場合は、Instrumentor サブモジュールを除外して、計測するクライアントを選択します。AWS SDK サービスクライアントに TracingHandler を追加して、個別のクライアントを計測します。

その他の X-Ray SDK for Java サブモジュールでは、HTTP ウェブ API および SQL データベースに対するダウンストリーム呼び出しを計測できます。以下の操作を実行できます。The X-Ray SDK for Java バージョンのHTTPClientおよびHTTPClientBuilderApache HTTP サブモジュールで Apache HTTP クライアントを計測します。SQL クエリの計測には、データソースに SDK のインターセプターを追加します。

SDK を活用したら、レコーダーとサーブレットフィルタを設定してその動作をカスタマイズします。プラグインを追加して、アプリケーションを実行しているコンピューティングリソースに関するデータを記録したり、サンプリングルールを定義することでサンプリングの動作のカスタマイズしたり、アプリケーションログに SDK からの情報をより多くあるいは少なく表示するようにログレベルを設定できます。

アプリケーションが注釈やメタデータで行うリクエストや作業に関する追加情報を記録します。注釈は、フィルタ式で使用するためにインデックス化されたシンプルなキーと値のペアで、特定のデータが含まれているトレースを検索できます。メタデータのエントリは制約が緩やかで、JSON にシリアル化できるオブジェクトと配列全体を記録できます。

注釈とメタデータ

注釈とメタデータは、X-Ray SDK を使用してセグメントに追加する任意のテキストです。注釈は、フィルタ式用にインデックス付けされます。メタデータはインデックス化されませんが、X-Ray コンソールまたは API を使用して raw セグメントで表示できます。X-Ray への読み取りアクセスを許可したユーザーは、このデータを表示できます。

コードに多数の計測されたクライアントがある場合、単一のリクエストセグメントには計測されたクライアントで行われた呼び出しごとに 1 個の多数のサブセグメントを含めることができます。カスタムサブセグメントで、クライアント呼び出しをラップすることで、サブセグメントを整理してグループできます。関数全体またはコードの任意のセクションのサブセグメントを作成し、親セグメントにすべてのレコードを記述する代わりにサブセグメントにメタデータと注釈を記録できます。

Submodules

Maven から Java 用 X-Ray SDK をダウンロードできます。X-Ray SDK for Java は、ユースケースごとにサブモジュールに分割され、部品表のバージョン管理に使用されます。

aws-xray-recorder-sdk-core(必須) — セグメントの作成とセグメントの送信の基本的な機能です。受信リクエストを計測する AWSXRayServletFilter が含まれています。
aws-xray-recorder-sdk-aws-sdk— トレースクライアントをリクエストハンドラーとして追加して、AWS SDK for Java クライアントを使用して行われる AWS のサービスに対する呼び出しを計測します。
aws-xray-recorder-sdk-aws-sdk-v2— トレースクライアントをリクエストインターセプターとして追加して、AWS SDK for Java 2.2 以降のクライアントを使用して行われる AWS のサービスに対する呼び出しを計測します。
aws-xray-recorder-sdk-aws-sdk-instrumentor— とともにaws-xray-recorder-sdk-aws-sdkは、すべての AWS SDK for Java クライアントを自動的に計測します。
aws-xray-recorder-sdk-aws-sdk-v2-instrumentor— とともにaws-xray-recorder-sdk-aws-sdkでは、AWS SDK for Java 2.2 以降のクライアントをすべて自動的に計測できます。
aws-xray-recorder-sdk-apache-http— Apache HTTP クライアントを使用して行われるアウトバウンド HTTP 呼び出しを計測します。
aws-xray-recorder-sdk-spring— Spring AOP Framework アプリケーション用のインターセプターを提供します。
aws-xray-recorder-sdk-sql-postgres— JDBC を使用して PostgreSQL データベースに対して行われるアウトバウンド呼び出しを計測します。
aws-xray-recorder-sdk-sql-mysql— JDBC を使用して MySQL データベースに対して行われるアウトバウンド呼び出しを計測します。
aws-xray-recorder-sdk-bom— すべてのサブモジュールで使用するバージョンを指定するための部品表を提供します。
aws-xray-recorder-sdk-metrics— 収集した X-Ray セグメントから、サンプリングされていない Amazon CloudWatch メトリックスを公開します。

Maven や Gradle を使用してアプリケーションを構築する場合、Java for X-Ray SDK for Java。

SDK のクラスとメソッドに関するリファレンスドキュメントについては、「AWS X-Ray SDK for Java API リファレンス」を参照してください。

Requirements

Java 用 X-Ray SDK には、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 を使用して構築すると自動的に含まれます。

Java 用 X-Ray SDK に含まれているライブラリを使用する場合、同梱されているバージョンを使用する必要があります。たとえば、すでに実行時に Jackson に依存し、その依存関係のためにデプロイメントに JAR ファイルを含めている場合、SDK JAR には Jackson ライブラリの独自のバージョンが含まれているため、その JAR ファイルを削除する必要があります。

依存関係管理

Java の X-Ray SDK for Java

グループ–com.amazonaws
アーティファクト–aws-xray-recorder-sdk-bom
バージョン–2.4.0

Maven を使用してアプリケーションを構築する場合は、SDK を依存関係として pom.xml ファイルに追加します。

例 pom.xml - 依存関係


<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-xray-recorder-sdk-bom</artifactId>
      <version>2.4.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-core</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-apache-http</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-aws-sdk</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-aws-sdk-instrumentor</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-sql-postgres</artifactId>
  </dependency>
  <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-xray-recorder-sdk-sql-mysql</artifactId>
  </dependency>
</dependencies>

Gradle の場合は、SDK をコンパイル時の依存関係として build.gradle ファイルに追加します。

例 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.4.0')
    }
}

Elastic Beanstalk を使用してアプリケーションをデプロイする場合、すべての依存関係を含んだ大きなアーカイブを構築してアップロードする代わりに、Maven や Gradle を使用してデプロイするたびにオンインスタンスで構築できます。Gradle の使用例については、サンプルアプリケーションを参照してください。

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

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

ドキュメントの表記規則

注釈とメタデータ

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