SDK メトリクスの公開をバージョン 1 からバージョン 2 に変更

このトピックでは、 のバージョン 1.x (v1) からバージョン 2.x (v2) へのクライアント側の SDK メトリクス発行の変更について詳しく説明します AWS SDK for Java。

高レベル変更

アーキテクチャの変更

v1 では、メトリクスコレクションは、システムプロパティで有効にする JVM 全体のグローバル設定です。SDK は、収集されたすべてのメトリクスを CloudWatch に自動的に発行します。メトリクスの送信先は 1 つだけです。

v2 では、メトリクスコレクションは、個々のサービスクライアントまたはリクエストにアタッチするプラガブル MetricPublisher インターフェイスを使用します。SDK には 3 つの実装があります。

スコープの変更

v1 では、メトリクスを有効にすると、JVM 内のすべての AWS サービスクライアントのデータが公開されます。v2 では、サービスクライアントレベルまたは個々のリクエストレベルでメトリクスを制御します。

メトリクスタイプの変更

v1 は、 AWS リクエストメトリクス、 AWS サービスメトリクス、マシンメトリクス (ヒープメモリ、スレッド数、オープンファイル記述子) の 3 つのカテゴリのメトリクスを収集します。

v2 は、API コール期間、マーシャリング期間、署名期間、再試行回数などの SDK リクエストおよびレスポンスメトリクスに焦点を当てています。v2 は、ヒープメモリ、スレッド数、オープンファイル記述子などのマシンメトリクスを収集しません。CloudWatch で JVM メトリクスを引き続き収集するには、JMX メトリクスコレクションで CloudWatch エージェントを使用できます。

依存関係の変更

次の表は、v1 と v2 の間の Maven の依存関係とパッケージ名の変更を示しています。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-java-sdk-bom</artifactId>
            <version>1.12.x1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-java-sdk-cloudwatchmetrics</artifactId>
    </dependency>
</dependencies>

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

¹ 最新バージョン。 ² 最新バージョン。

次の表に示すように、v2 アーティファクトはユースケースによって異なります。

API の変更

メトリクスを有効にする

次の表は、さまざまなユースケースで v1 と v2 でメトリクスを有効にする方法を比較したものです。

-Dcom.amazonaws.sdk.enableDefaultMetrics=credentialFile=/path/aws.properties

-Dcom.amazonaws.sdk.enableDefaultMetrics

MetricPublisher metricsPub =
    CloudWatchMetricPublisher.create();

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

// ... use the client ...

metricsPub.close();
ddb.close();

ddb.listTables(ListTablesRequest.builder()
    .overrideConfiguration(c -> c
        .addMetricPublisher(metricsPub))
    .build());

CloudWatch 送信先の設定

次の表は、v2 と比較して v1 で CloudWatch 送信先を設定する方法を示しています。

-Dcom.amazonaws.sdk.enableDefaultMetrics=cloudwatchRegion=us-west-2

CloudWatchMetricPublisher.builder()
    .cloudWatchClient(
        CloudWatchAsyncClient.builder()
            .region(Region.US_WEST_2)
            .build())
    .build();

CloudWatchMetricPublisher.builder()
    .uploadFrequency(Duration.ofMinutes(5))
    .build();

CloudWatchMetricPublisher.builder()
    .namespace("MyApp/SDK")
    .build();

-Dcom.amazonaws.sdk.enableDefaultMetrics=excludeMachineMetrics

Lambda 関数のメトリクス

v1 には Lambda 固有のメトリクスソリューションはありません。v2 EmfMetricLoggingPublisherでは、 を使用して CloudWatch Embedded Metric Format (EMF) の構造化ログエントリとしてメトリクスを書き込みます。

// v2 - Lambda-optimized metrics publishing
EmfMetricLoggingPublisher emfPublisher = EmfMetricLoggingPublisher.builder()
        .namespace("MyApp")
        .dimensions(CoreMetric.SERVICE_ID, CoreMetric.OPERATION_NAME)
        .build();

DynamoDbClient dynamoDb = DynamoDbClient.builder()
        .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher))
        .build();

開発とデバッグのメトリクス

v1 にはコンソールベースのメトリクス出力はありません。v2 では、 を使用しますLoggingMetricPublisher。

// v2 - Console output for debugging
MetricPublisher loggingPublisher = LoggingMetricPublisher.create();

S3Client s3 = S3Client.builder()
        .overrideConfiguration(c -> c.addMetricPublisher(loggingPublisher))
        .build();

ライフサイクル管理

v1 では、システムプロパティが設定されると、メトリクス収集は JVM の存続期間中実行されます。v2 では、 のライフサイクルを管理する必要がありますMetricPublisher。

// v2 - Close the publisher when no longer needed
MetricPublisher metricsPub = CloudWatchMetricPublisher.create();
DynamoDbClient ddb = DynamoDbClient.builder()
        .overrideConfiguration(c -> c.addMetricPublisher(metricsPub))
        .build();

// ... use the client ...

metricsPub.close(); // Flushes remaining metrics to CloudWatch
ddb.close();

必要なアクセス許可

次の表に、各メトリクスパブリッシャーに必要な IAM アクセス許可を示します。

制限事項

AWS CRT ベースの S3 クライアントは現在、v2 での SDK メトリクス収集をサポートしていません。

その他のリソース