からのSDKメトリクスを使用する AWS SDK for Java

AWS SDK for Java 2.x を使用すると、アプリケーション内のサービスクライアントに関するメトリクスを収集し、 で出力を分析し Amazon CloudWatch、それに対してアクションを実行できます。

デフォルトでは、 でメトリクス収集は無効になっていますSDK。このトピックは、それを有効にして設定するのに役立ちます。

前提条件

メトリクスを有効にして使用する前に、次の手順を完了する必要があります。

• 「AWS SDK for Java 2.x のセットアップ」のステップを完了します。

• AWS SDK for Javaのバージョン 2.14.0 以降を使用するように、プロジェクトの依存関係を (例: pom.xml または build.gradle ファイルで) 設定します。

  へのメトリクスの発行を有効にするには CloudWatch、プロジェクトの依存関係に artifactId cloudwatch-metric-publisherバージョン番号 2.14.0 以降の も含めます。

  例:

  <project>
    <dependencyManagement>
     <dependencies>
        <dependency>
          <groupId>software.amazon.awssdk</groupId>
          <artifactId>bom</artifactId>
          <version>2.14.0</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
     </dependencies>
    </dependencyManagement>
    <dependencies>
     <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>cloudwatch-metric-publisher</artifactId>
        <version>2.14.0</version>
     </dependency>
    </dependencies>
  </project>

• メトリクスパブリッシャーが使用する IAM ID のcloudwatch:PutMetricDataアクセス許可を有効にして、 SDK for Java がメトリクスを書き込めるようにします。

メトリクスの収集を有効にする方法

アプリケーションでサービスクライアントのメトリクスを有効にすることも、個々のリクエストでメトリクスを有効にすることもできます。

特定のリクエストのメトリクスを有効にする

次のクラスは、 へのリクエストに対して CloudWatch メトリクスパブリッシャーを有効にする方法を示しています Amazon DynamoDB。デフォルトのメトリクスパブリッシャー設定を使用します。

import software.amazon.awssdk.metrics.MetricPublisher;
import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.ListTablesRequest;

public class DefaultConfigForRequest {
    // Use one MetricPublisher for your application. It can be used with requests or service clients.
    static MetricPublisher metricsPub = CloudWatchMetricPublisher.create();

    public static void main(String[] args) {
        DynamoDbClient ddb = DynamoDbClient.create();
        // Publish metrics the for ListTables operation.
        ddb.listTables(ListTablesRequest.builder()
            .overrideConfiguration(c -> c.addMetricPublisher(metricsPub))
            .build());

        // Perform more work in your application.

        // A MetricsPublisher has its own lifecycle independent of any service client or request that uses it.
        // If you no longer need the publisher, close it to free up resources.
        metricsPub.close();  // All metrics stored in memory are flushed to CloudWatch.

        // Perform more work with the DynamoDbClient instance without publishing metrics.
        // Close the service client when you no longer need it.
        ddb.close();
    }
}

重要

サービスクライアントが使用されなくなったときに、アプリケーションがMetricPublisherインスタンスcloseで を呼び出すことを確認します。そうしないと、スレッドまたはファイル記述子のリークが発生する可能性があります。

特定のサービスクライアントの概要メトリクスを有効にする

次のコードスニペットは、サービスクライアントのデフォルト設定で CloudWatch メトリクスパブリッシャーを有効にする方法を示しています。

MetricPublisher metricsPub = CloudWatchMetricPublisher.create();

DynamoDbClient ddb = DynamoDbClient.builder()
          .overrideConfiguration(c -> c.addMetricPublisher(metricsPub))
          .build();

メトリクスパブリッシャーをカスタマイズする

次のクラスは、特定のサービスクライアントのメトリクスパブリッシャーのカスタム設定を設定する方法を示しています。カスタマイズには、特定のプロファイルのロード、メトリクスパブリッシャーがリクエストを送信する AWS リージョンの指定、パブリッシャーがメトリクスを に送信する頻度のカスタマイズが含まれます CloudWatch。

import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider;
import software.amazon.awssdk.core.metrics.CoreMetric;
import software.amazon.awssdk.metrics.MetricPublisher;
import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.cloudwatch.CloudWatchAsyncClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;

import java.time.Duration;

public class CustomConfigForDDBClient {
    // Use one MetricPublisher for your application. It can be used with requests or service clients.
    static MetricPublisher metricsPub = CloudWatchMetricPublisher.builder()
        .cloudWatchClient(CloudWatchAsyncClient.builder()
            .region(Region.US_WEST_2)
            .credentialsProvider(ProfileCredentialsProvider.create("cloudwatch"))
            .build())
        .uploadFrequency(Duration.ofMinutes(5))
        .maximumCallsPerUpload(100)
        .namespace("ExampleSDKV2Metrics")
        .detailedMetrics(CoreMetric.API_CALL_DURATION)
        .build();

    public static void main(String[] args) {
        DynamoDbClient ddb = DynamoDbClient.builder()
            .overrideConfiguration(c -> c.addMetricPublisher(metricsPub))
            .build();
        // Publish metrics for DynamoDB operations.
        ddb.listTables();
        ddb.describeEndpoints();
        ddb.describeLimits();
        // Perform more work in your application.

        // A MetricsPublisher has its own lifecycle independent of any service client or request that uses it.
        // If you no longer need the publisher, close it to free up resources.
        metricsPub.close();  // All metrics stored in memory are flushed to CloudWatch.


        // Perform more work with the DynamoDbClient instance without publishing metrics.
        // Close the service client when you no longer need it.
        ddb.close();
    }
}

前のスニペットで示したカスタマイズには、次の効果があります。

• cloudWatchClient メソッドを使用すると、メトリクスの送信に使用する CloudWatch クライアントをカスタマイズできます。この例では、クライアントがメトリクスを送信するデフォルトの us-east-1 とは異なるリージョンを使用します。また、別の名前付きプロファイルである cloudwatch も使用します。このプロファイルの認証情報は、 へのリクエストの認証に使用されます CloudWatch。これらの認証情報には、 へのアクセス許可が必要ですcloudwatch:PutMetricData。

• uploadFrequency メソッドを使用すると、メトリクスパブリッシャーがメトリクスを にアップロードする頻度を指定できます CloudWatch。デフォルトは 1 分に 1 回です。

• maximumCallsPerUpload メソッドは、アップロードごとに行われる呼び出しの数を制限します。デフォルトは無制限です。

• デフォルトでは、 SDK for Java 2.x は名前空間 の下にメトリクスを発行しますAwsSdk/JavaSdk2。namespace メソッドを使用して、別の値を指定できます。

• デフォルトでは、 SDK はサマリーメトリクスを発行します。概要メトリクスは、平均、最小、最大、合計、サンプル数で構成されます。detailedMetrics メソッドで 1 つ以上のSDKメトリクスを指定することで、 SDK は各メトリクスの追加データを公開します。この追加データにより、 でクエリできる p90 や p99 などのパーセンタイル統計が有効になります CloudWatch。詳細なメトリクスはAPICallDuration、SDKクライアントリクエストのレイテンシーを測定する などの end-to-end レイテンシーメトリクスに特に役立ちます。CoreMetric クラスのフィールドを使用して、他の一般的なSDKメトリクスを指定できます。

メトリクスが利用可能になるまでの時間

メトリクスは、 SDK for Java がメトリクスを発行してから 5～10 分以内に一般公開されます。正確な と up-to-date メトリクスについては、Java アプリケーションからメトリクスを送信してから少なくとも 10 分後に Cloudwatch を確認してください。

収集される情報

メトリクスの収集には、次のものが含まれます。

• 成功か失敗かを含むAPIリクエストの数

• 返される例外など、APIリクエストで呼び出す AWS サービスに関する情報

• マーシャリング、署名、HTTPリクエストなどのさまざまなオペレーションの期間

• HTTP オープン接続の数、保留中のリクエストの数、使用されたHTTPクライアントの名前などのクライアントメトリクス

注記

使用可能なメトリクスはHTTPクライアントによって異なります。

詳細なリストについては、サービスクライアントのメトリクスを参照してください。

この情報の使用方法

がSDK収集するメトリクスを使用して、アプリケーション内のサービスクライアントをモニタリングできます。全体的な使用傾向の確認や、異常の特定ができるほか、返されたサービスクライアントの例外を確認したり、特定の問題を理解するために詳しく確認したりすることもできます。を使用して Amazon CloudWatch、アプリケーションが定義した条件に達したらすぐに通知するアラームを作成することもできます。

詳細については、「 Amazon CloudWatch ユーザーガイド」のAmazon CloudWatch 「メトリクスの使用」と Amazon CloudWatch 「アラームの使用」を参照してください。