Enabling SDK metrics - AWS SDK for Java
PrerequisitesHow to enable metrics collectionWhat information is collected?
AWS services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with AWS services in China.

At Amazon Web Services (AWS), we’re focused on finding ways to improve our products and provide a better customer experience. To do that, we need your feedback. Please take 5 minutes of your time to share insights regarding your experience with Java Spring and your need for Spring integration with AWS.

Click here to take a quick survey

This survey is hosted by an external company (Qualtrics), so the link above does not lead to our website. Please note that AWS will own the data gathered via this survey, and will not share the information/results collected with survey respondents. AWS handles your information as described in the AWS Privacy Notice.

Enabling SDK metrics

With the AWS 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.

Topics

Prerequisites

Before you can enable and use metrics, you must complete the following steps:

  • Sign up for AWS and create an IAM user

  • Set up AWS credentials and region for development

  • Configure your project dependencies (for example, in your pom.xml or build.gradle file) to use version 2.14.0 or later of the AWS SDK for Java.

    To enabling publishing of metrics to CloudWatch, also include the artifactId cloudwatch-metric-publisher with the version number 2.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.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>
Note

To enhance the security of your application, you can use dedicated set of credentials for publishing metrics to CloudWatch. Create a separate IAM user with cloudwatch:PutMetricData permissions and then use that user’s access key as credentials in the MetricPublisher configuration for your application.

For more information, see the Amazon CloudWatch Permissions Reference in the Amazon CloudWatch User Guide and Adding and Removing IAM Identity Permissions inthe AWS IAM User Guide.

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 code snippet shows how to enable the CloudWatch metrics publisher for a request to Amazon DynamoDB. It uses the default metrics publisher configuration. 

MetricPublisher metricsPub = CloudWatchMetricPublisher.create();
DynamoDbClient ddb = DynamoDbClient.create();
ddb.listTables(ListTablesRequest.builder()
    .overrideConfiguration(c -> c.addMetricPublisher(metricsPub))
    .build());

Enable metrics for a specific service client

The following code snippet shows how to enable the CloudWatch metrics publisher for a service client. 

MetricPublisher metricsPub = CloudWatchMetricPublisher.create();

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

The following snippet demonstrates how to use a custom configuration for the metrics publisher for a specific service client. The customizations include loading a separate credentials profile, specifying a different region than the service client, and customizing how often the publisher sends metrics to CloudWatch. 

MetricPublisher metricsPub = CloudWatchMetricPublisher.builder()
                    .credentialsProvider(EnvironmentVariableCredentialsProvider.create("cloudwatch"))
                    .region(Region.US_WEST_2)
                    .publishFrequency(5, TimeUnit.MINUTES)
                    .build();

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

What information is collected?

Metrics collection includes the following:

  • Number of API requests, including whether they succeed or fail

  • Information about the AWS 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 configuration-metrics-list.

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 and Using Amazon CloudWatch Alarms in the Amazon CloudWatch User Guide.