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

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

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

サブモジュール

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

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、AWSSDK、および Jackson が必要です。

SDK は、コンパイル時および実行時に次のライブラリに依存します。

これらの依存関係は SDK の pom.xml ファイルで宣言され、Maven や Gradle を使用して構築すると自動的に含まれます。

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

依存関係管理

X-Ray SDK for Javaは、Maven から入手できます。

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

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-xray-recorder-sdk-bom</artifactId>
      <version>2.11.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 ファイルに追加します。

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

AWS X-RayX-Ray SDK for Javaのメトリック

このトピックでは、AWS X-Ray の名前空間、メトリクス、ディメンションについて説明します。X-Ray SDK for Java を使用して、収集した X-Ray セグメントから、サンプリングされていない Amazon CloudWatch メトリクスを公開できます。これらのメトリクスは、セグメントの開始時間と終了時間、さらにエラー、障害、スロットリングのステータスフラグから取得されます。これらの追跡メトリクスを使用して、サブセグメント内の再試行と依存関係の問題を公開します。

CloudWatch はメトリクスリポジトリです。メトリクスは CloudWatch の基本的概念で、時系列に並んだデータポイントのセットを表しています。ユーザー (または AWS のサービス) がメトリクスのデータポイントを CloudWatch で公開し、このデータポイントに関する統計を、時系列順に並べられた時系列データのセットとして取得できます。

メトリクスは名前、名前空間、1 つ以上のディメンションで一意に定義されます。各データポイントには、タイムスタンプと、オプションとして測定単位があります。統計を要求した場合、返されるデータストリームは、名前空間、メトリクス名、ディメンションによって識別されます。

CloudWatch の詳細については、Amazon CloudWatch ユーザーガイドを参照してください。

X-Ray CloudWatch メトリクス

ServiceMetrics/SDK 名前空間には、次のメトリクスが含まれます。

X-Ray CloudWatch ディメンション

以下の表のディメンションを使用して、X-Ray によって計測された Java アプリケーションに対して返されるメトリクスを絞り込みます。

X-Ray CloudWatch メトリクスを有効にする

以下の手順を使用して、計測された Java アプリケーションでトレースメトリクスを有効にします。