Class CloudWatchMetricPublisher
- All Implemented Interfaces:
AutoCloseable
,MetricPublisher
,SdkAutoCloseable
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. CloudWatchMetricPublisher
s 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.
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic final class
Builder class to constructCloudWatchMetricPublisher
instances. -
Method Summary
Modifier and TypeMethodDescriptionbuilder()
Create a newCloudWatchMetricPublisher.Builder
that can be used to createCloudWatchMetricPublisher
s.void
close()
static CloudWatchMetricPublisher
create()
Create aCloudWatchMetricPublisher
using all default values.void
publish
(MetricCollection metricCollection) Notify the publisher of new metric data.
-
Method Details
-
publish
Description copied from interface:MetricPublisher
Notify the publisher of new metric data. After this call returns, the caller can safely discard the givenmetricCollection
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 interfaceMetricPublisher
- 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 interfaceAutoCloseable
- Specified by:
close
in interfaceMetricPublisher
- Specified by:
close
in interfaceSdkAutoCloseable
-
builder
Create a newCloudWatchMetricPublisher.Builder
that can be used to createCloudWatchMetricPublisher
s. -
create
Create aCloudWatchMetricPublisher
using all default values.
-