Class CloudWatchMetricPublisher

java.lang.Object
software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher
All Implemented Interfaces:
AutoCloseable, MetricPublisher, SdkAutoCloseable
@ThreadSafe @Immutable public final class CloudWatchMetricPublisher extends Object implements MetricPublisher
An implementation of MetricPublisher that aggregates and uploads metrics to Amazon CloudWatch on a periodic basis.

This simplifies the process of uploading custom metrics to CloudWatch, and can also be configured on the AWS SDK clients directly to upload AWS SDK-specific metrics (e.g. request latencies, failure rates) to CloudWatch.

Overview

This publisher aggregates metric data in memory, and periodically uploads it to CloudWatch in a background thread. This minimizes the work necessary to upload metrics, allowing the caller to focus on collecting the data.

The default settings of the metrics publisher are meant to minimize memory usage and CloudWatch cost, while still providing a useful amount of insight into the metric data. Care should be taken when overriding the default values on the publisher, because they can result in an associated increased in memory usage and CloudWatch cost.

By default, all metrics are uploaded using summary statistics. This means that only count, maximum, minimum, sum and average data is available in CloudWatch. Metric details (e.g. p90, p99) can be enabled on a per-metric basis using CloudWatchMetricPublisher.Builder.detailedMetrics(Collection).

See CloudWatchMetricPublisher.Builder for the configuration values that are available for the publisher, and how they can be used to increase the functionality or decrease the cost the publisher.

Logging The CloudWatchMetricPublisher logs all aggregation and upload-related logs to the software.amazon.awssdk.metrics.publishers.cloudwatch namespace. To determine how many metrics are being uploaded successfully without checking the CloudWatch console, you can check for a "success" message at the DEBUG level. At the TRACE level, you can see exactly which metrics are being uploaded.

Configuring AWS SDK clients to upload client metrics

Create a CloudWatchMetricPublisher, and configure it via ClientOverrideConfiguration.Builder.addMetricPublisher(MetricPublisher) 

     CloudWatchMetricPublisher cloudWatchMetricPublisher = CloudWatchMetricPublisher.create();
     S3Client s3 = S3Client.builder()
                           .overrideConfiguration(o -> o.addMetricPublisher(cloudWatchMetricPublisher))
                           .build();

Uploading your own custom metrics Step 1: Define which metrics you wish to collect

Metrics are described using the SdkMetric.create(java.lang.String, java.lang.Class<T>, software.amazon.awssdk.metrics.MetricLevel, software.amazon.awssdk.metrics.MetricCategory, software.amazon.awssdk.metrics.MetricCategory...) method. When you describe your metric, you specify the name that will appear in CloudWatch and the Java data-type of the metric. The metric should be described once for your entire application.

Supported types: (1) Number types (e.g. Integer, Double, etc.), (2) Duration. 

     // In this and the following examples, we want to collect metrics about calls to a method we have defined: "myMethod"
     public static final class MyMethodMetrics {
         // The number of times "myMethod" has been called.
         private static final SdkMetric<Integer> MY_METHOD_CALL_COUNT =
                 SdkMetric.create("MyMethodCallCount", Integer.class, MetricLevel.INFO, MetricCategory.CUSTOM);

         // The amount of time that "myMethod" took to execute.
         private static final SdkMetric<Duration> MY_METHOD_LATENCY =
                 SdkMetric.create("MyMethodLatency", Duration.class, MetricLevel.INFO, MetricCategory.CUSTOM);
     }

Step 2: Create a CloudWatchMetricPublisher

A CloudWatchMetricPublisher should be created once for your entire application, and be reused wherever it is needed. CloudWatchMetricPublishers are thread-safe, so there should be no need to create multiple instances. Most people create and manage the publisher in their inversion-of-control (IoC) container (e.g. Spring/Dagger/Guice).

Note: When your application is finished with the CloudWatchMetricPublisher, make sure to close() it. Your inversion-of-control container may handle this for you on JVM shutdown.

See CloudWatchMetricPublisher.Builder for all available configuration options. 

     // Create a CloudWatchMetricPublisher using a custom namespace.
     MetricPublisher metricPublisher = CloudWatchMetricPublisher.builder()
                                                                .namespace("MyApplication")
                                                                .build();

Step 3: Collect and Publish Metrics

Create and use a MetricCollector to collect data about your configured metrics. 

     // Call "myMethod" and collect metrics about the call.
     Instant methodCallStartTime = Instant.now();
     myMethod();
     Duration methodCallDuration = Duration.between(methodCallStartTime, Instant.now());

     // Write the metrics to the CloudWatchMetricPublisher.
     MetricCollector metricCollector = MetricCollector.create("MyMethodCall");
     metricCollector.reportMetric(MyCustomMetrics.MY_METHOD_CALL_COUNT, 1);
     metricCollector.reportMetric(MyCustomMetrics.MY_METHOD_LATENCY, methodCallDuration);
     MetricCollection metricCollection = metricCollector.collect();

     metricPublisher.publish(metricCollection);

Warning: Make sure the close() this publisher when it is done being used to release all resources it consumes. Failure to do so will result in possible thread or file descriptor leaks.

  • Method Details

    • publish

      public void publish(MetricCollection metricCollection)
      Description copied from interface: MetricPublisher
      Notify the publisher of new metric data. After this call returns, the caller can safely discard the given metricCollection instance if it no longer needs it. Implementations are strongly encouraged to complete any further aggregation and publishing of metrics in an asynchronous manner to avoid blocking the calling thread.

      With the exception of a null metricCollection, all invocations of this method must return normally. This is to ensure that callers of the publisher can safely assume that even in situations where an error happens during publishing that it will not interrupt the calling thread.

      Specified by:
      publish in interface MetricPublisher
      Parameters:
      metricCollection - The collection of metrics.

    • close

      public void close()
      Description copied from interface: MetricPublisher

      Important: Implementations must block the calling thread until all pending metrics are published and any resources acquired have been freed.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface MetricPublisher
      Specified by:
      close in interface SdkAutoCloseable

    • builder

      public static CloudWatchMetricPublisher.Builder builder()
      Create a new CloudWatchMetricPublisher.Builder that can be used to create CloudWatchMetricPublishers.

    • create

      public static CloudWatchMetricPublisher create()
      Create a CloudWatchMetricPublisher using all default values.