Changes in SDK metric publishing from version 1 to version 2

This topic details the changes in client-side SDK metric publishing from version 1.x (v1) to version 2.x (v2) of the AWS SDK for Java.

High-level changes

Architecture changes

In v1, metrics collection is a global, JVM-wide setting that you enable with a system property. The SDK automatically publishes all collected metrics to CloudWatch. There is only one metrics destination.

In v2, metrics collection uses a pluggable MetricPublisher interface that you attach to individual service clients or requests. The SDK provides three implementations:

Scope changes

In v1, enabling metrics publishes data for all AWS service clients in the JVM. In v2, you control metrics at the service client level or at the individual request level.

Metric type changes

v1 collects three categories of metrics: AWS Request Metrics, AWS Service Metrics, and Machine Metrics (heap memory, thread count, open file descriptors).

v2 focuses on SDK request and response metrics, such as API call duration, marshalling duration, signing duration, and retry count. v2 does not collect machine metrics such as heap memory, thread count, and open file descriptors. To continue collecting JVM metrics in CloudWatch, you can use the CloudWatch Agent with JMX metric collection.

Changes in dependencies

The following table shows the Maven dependency and package name changes between v1 and v2.

<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>

¹ Latest version. ² Latest version.

The v2 artifact depends on the use case, as shown in the following table.

API changes

Enabling metrics

The following table compares how to enable metrics in v1 and v2 for different use cases.

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

Configuring the CloudWatch destination

The following table shows how to configure the CloudWatch destination in v1 compared to v2.

-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

Metrics for Lambda functions

v1 does not have a Lambda-specific metrics solution. In v2, use EmfMetricLoggingPublisher which writes metrics as structured log entries in 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();

Metrics for development and debugging

v1 does not have a console-based metrics output. In v2, use LoggingMetricPublisher:

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

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

Lifecycle management

In v1, metrics collection runs for the lifetime of the JVM once the system property is set. In v2, you must manage the lifecycle of the 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();

Required permissions

The following table lists the IAM permissions required for each metrics publisher.

Limitations

The AWS CRT-based S3 client does not currently support SDK metrics collection in v2.

Additional resources