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

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS X-Ray SDK for Java

X-Ray SDK for Java は、トレースデータを生成して X-Ray デーモンに送信するためのクラスとメソッドを提供する Java ウェブアプリケーション用のライブラリのセットです。トレースデータには、アプリケーションによって処理された受信HTTPリクエストに関する情報と、、 AWS SDKHTTPクライアント、または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 を使用して、SDKInstrumentor サブモジュールをビルド設定に含めることで AWS SDK for Java クライアントを計測します。計測されたクライアントを使用してダウンストリーム AWS のサービス またはリソースを呼び出すたびに、 はサブセグメントの呼び出しに関する情報SDKを記録します。 AWS のサービス また、サービス内でアクセスするリソースは、トレースマップにダウンストリームノードとして表示され、個々の接続でエラーやスロットリングの問題を識別しやすくなります。

へのすべてのダウンストリーム呼び出しを計測したくない場合は AWS のサービス、Instrumentor サブモジュールを省略して、計測するクライアントを選択できます。サービスクライアントに を追加してTracingHandler、個々のクライアントを AWS SDK計測します。

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

の使用を開始したらSDK、レコーダーとサーブレットフィルター を設定して、その動作をカスタマイズします。プラグインを追加して、アプリケーションを実行しているコンピューティングリソースに関するデータを記録し、サンプリングルールを定義してサンプリング動作をカスタマイズし、ログレベルを設定して、アプリケーションログSDKの からの情報を増減できます。

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

注釈とメタデータ

注釈とメタデータは、X-Ray でセグメントに追加する任意のテキストですSDK。注釈は、フィルタ式用にインデックス付けされます。メタデータはインデックス化されませんが、X-Ray コンソールまたは を使用して raw セグメントで表示できますAPI。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-v2、 はすべての 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 – で行われた PostgreSQL データベースへのアウトバウンド呼び出しを計測しますJDBC。

  • aws-xray-recorder-sdk-sql-mysql - で行われた MySQL データベースへのアウトバウンドコールを計測しますJDBC。

  • aws-xray-recorder-sdk-bom - すべてのサブモジュールで使用するバージョンを指定するための部品表を提供します。

  • aws-xray-recorder-sdk-metrics – 収集した X-Ray セグメントからサンプリングされていない Amazon CloudWatch メトリクスを公開します。

Maven または Gradle を使用してアプリケーションを構築する場合は、X-Ray SDK for Java をビルド設定 に追加します。

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

要件

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ファイルを含める場合は、 に独自のバージョンの Jackson ライブラリSDKJARが含まれているため、これらのJARファイルを削除する必要があります。

依存関係管理

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

  • グループ – com.amazonaws

  • Artifact – aws-xray-recorder-sdk-bom

  • バージョン – 2.11.0

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

例 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 ファイルに追加します。

例 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-Ray X-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 名前空間には、次のメトリクスが含まれます。

メトリクス 利用可能な統計情報 説明 単位

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 Submodules」を参照してください。

  2. グローバルレコーダービルドの一部として新しい MetricsSegmentListener() を有効にします。

    例 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());
  }
}

  3. CloudWatch エージェントをデプロイして、Amazon Elastic Compute Cloud (Amazon EC2）、Amazon Elastic Container Service (Amazon )、または Amazon Elastic Kubernetes Service (Amazon ECS) を使用してメトリクスを収集しますEKS。

  4. CloudWatch エージェントと通信SDKするように を設定します。デフォルトでは、 はアドレス で CloudWatch エージェントとSDK通信します127.0.0.1。環境変数または Java プロパティを address:port に設定することで、代替アドレスを設定できます。

    例 環境変数
    AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port
    例 Java のプロパティ
    com.amazonaws.xray.metrics.daemonAddress=address:port
設定を検証するには

  1. にサインイン AWS Management Console し、 で CloudWatch コンソールを開きますhttps://console.aws.amazon.com/cloudwatch/。

  2. [Metrics (メトリクス)] タブを開いて、メトリクスの到着を確認します。

  3. （オプション) CloudWatch コンソールのログタブで、ServiceMetricsSDKロググループを開きます。ホストメトリクスに一致するログストリームを探し、ログメッセージを確認します。