Package software.amazon.awssdk.metrics.publishers.cloudwatch

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