Use SDK metrics from the Amazon SDK for Java
With the Amazon SDK for Java 2.x, you can collect metrics about the service clients in your application, analyze the output in Amazon CloudWatch, and then act on it.
By default, metrics collection is disabled in the SDK. This topic helps you to enable and configure it.
Prerequisites
Before you can enable and use metrics, you must complete the following steps:
-
Complete the steps in Set up the Amazon SDK for Java 2.x.
-
Configure your project dependencies (for example, in your
pom.xml
orbuild.gradle
file) to use version2.14.0
or later of the Amazon SDK for Java.To enabling publishing of metrics to CloudWatch, also include the artifactId
cloudwatch-metric-publisher
with the version number2.14.0
or later in your project’s dependencies.For example:
<project> <dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>bom</artifactId> <version>2.27.21</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>cloudwatch-metric-publisher</artifactId> </dependency> </dependencies> </project>
-
Enable
cloudwatch:PutMetricData
permissions for the IAM identity used by the metrics publisher to allow the SDK for Java to write metrics.
How to enable metrics collection
You can enable metrics in your application for a service client or on individual requests.
Enable metrics for a specific request
The following class shows how to enable the CloudWatch metrics publisher for a request to Amazon DynamoDB. It uses the default metrics publisher configuration.
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(); } }
Important
Make sure your application calls close
on the MetricPublisher
instance when the service client is no longer
in use. Failure to do so results in possible thread or file descriptor leaks.
Enable summary metrics for a specific service client
The following code snippet shows how to enable a CloudWatch metrics publisher with default settings for a service client.
MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build();
Customize metrics publisher
The following class demonstrates how to set up a custom configuration for the metrics publisher for a specific service client. The customizations include loading a specific profile, specifying a Amazon Region where the metrics publisher sends requests, and customizing how often the publisher sends metrics to 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(); } }
The customizations shown in the previous snippet have the following effects.
-
The
cloudWatchClient
method lets you customize the CloudWatch client used to send metrics. In this example, we use a different region from the default of us-east-1 where the client sends metrics. We also use a different named profile, cloudwatch, whose credentials will be used to authenticate requests to CloudWatch. Those credentials must have permissions tocloudwatch:PutMetricData
. -
The
uploadFrequency
method allows you to specify how frequently the metrics publisher uploads metrics to CloudWatch. The default is once a minute. -
The
maximumCallsPerUpload
method limits the number of calls made per upload. The default is unlimited. -
By default, the SDK for Java 2.x publishes metrics under the namespace
AwsSdk/JavaSdk2
. You can use thenamespace
method to specify a different value. -
By default, the SDK publishes summary metrics. Summary metrics consist of average, minimum, maximum, sum, and sample count. By specifying one or more SDK metrics in the
detailedMetrics
method, the SDK publishes additional data for each metric. This additional data enables percentile statistics like p90 and p99 that you can query in CloudWatch. The detailed metrics are especially useful for latency metrics likeAPICallDuration
, which measures the end-to-end latency for SDK client requests. You can use fields of theCoreMetric
class to specify other common SDK metrics.
When are metrics available?
Metrics are generally available within 5-10 minutes after the SDK for Java emits them. For accurate and up-to-date metrics, check Cloudwatch at least 10 minutes after emitting the metrics from your Java applications.
What information is collected?
Metrics collection includes the following:
-
Number of API requests, including whether they succeed or fail
-
Information about the Amazon services you call in your API requests, including exceptions returned
-
The duration for various operations such as Marshalling, Signing, and HTTP requests
-
HTTP client metrics, such as the number of open connections, the number of pending requests, and the name of the HTTP client used
Note
The metrics available vary by HTTP client.
For a complete list, see Service client metrics.
How can I use this information?
You can use the metrics the SDK collects to monitor the service clients in your application. You can look at overall usage trends, identify anomalies, review service client exceptions returned, or to dig in to understand a particular issue. Using Amazon CloudWatch, you can also create alarms to notify you as soon as your application reaches a condition that you define.
For more information, see
Using Amazon CloudWatch Metrics