AWS X-Ray SDK for Java - AWS X-Ray
サブモジュール要件依存関係管理

AWS X-Ray SDK for Java

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 で問題とプルリクエストを送信できます。

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

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

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

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

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

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

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

注釈とメタデータ

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

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

サブモジュール

X-Ray SDK for Java は、Maven からダウンロードできます。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 を使用してアプリケーションを構築する場合は、X-Ray SDK for Java をビルド設定に追加します。

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

要件

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

  • アーティファクト – 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 の使用例については、サンプルアプリケーションを参照してください。