software.amazon.awssdk.metrics.publishers.cloudwatch

Class CloudWatchMetricPublisher.Builder

java.lang.Object

software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher.Builder

Enclosing class:

CloudWatchMetricPublisher

public static final class CloudWatchMetricPublisher.Builder
extends Object

Builder class to construct CloudWatchMetricPublisher instances. See the individual properties for which configuration settings are available.

Method Summary

Modifier and Type	Method and Description
CloudWatchMetricPublisher	build() Build a CloudWatchMetricPublisher using the configuration currently configured on this publisher.
CloudWatchMetricPublisher.Builder	cloudWatchClient(CloudWatchAsyncClient client) Configure the CloudWatchAsyncClient instance that should be used to communicate with CloudWatch.
CloudWatchMetricPublisher.Builder	detailedMetrics(Collection<SdkMetric<?>> detailedMetrics) Configure the set of metrics for which detailed values and counts are uploaded to CloudWatch, instead of summaries.
CloudWatchMetricPublisher.Builder	detailedMetrics(SdkMetric<?>... detailedMetrics)
CloudWatchMetricPublisher.Builder	dimensions(Collection<SdkMetric<String>> dimensions) Configure the SdkMetrics that are used to define the Dimensions metrics are aggregated under.
CloudWatchMetricPublisher.Builder	dimensions(SdkMetric<String>... dimensions)
CloudWatchMetricPublisher.Builder	maximumCallsPerUpload(Integer maximumCallsPerUpload) Configure the maximum number of CloudWatchAsyncClient.putMetricData(PutMetricDataRequest) calls that an individual "upload" event can make to CloudWatch.
CloudWatchMetricPublisher.Builder	metricCategories(Collection<MetricCategory> metricCategories) Configure the MetricCategorys that should be uploaded to CloudWatch.
CloudWatchMetricPublisher.Builder	metricCategories(MetricCategory... metricCategories)
CloudWatchMetricPublisher.Builder	metricLevel(MetricLevel metricLevel) Configure the MetricLevel that should be uploaded to CloudWatch.
CloudWatchMetricPublisher.Builder	namespace(String namespace) Configure the PutMetricDataRequest.namespace() used for all put-metric-data calls from this publisher.
CloudWatchMetricPublisher.Builder	uploadFrequency(Duration uploadFrequency) Configure the frequency at which aggregated metrics are uploaded to CloudWatch and released from memory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

namespace

public CloudWatchMetricPublisher.Builder namespace(String namespace)

Configure the PutMetricDataRequest.namespace() used for all put-metric-data calls from this publisher.

If this is not specified, AwsSdk/JavaSdk2 will be used.

cloudWatchClient

public CloudWatchMetricPublisher.Builder cloudWatchClient(CloudWatchAsyncClient client)

Configure the CloudWatchAsyncClient instance that should be used to communicate with CloudWatch.

If this is not specified, the CloudWatchAsyncClient will be created via CloudWatchAsyncClient.create() (and will be closed when CloudWatchMetricPublisher.close() is invoked).

If you specify a CloudWatchAsyncClient via this method, it will not be closed when this publisher is closed. You will need to need to manage the lifecycle of the client yourself.

uploadFrequency

public CloudWatchMetricPublisher.Builder uploadFrequency(Duration uploadFrequency)

Configure the frequency at which aggregated metrics are uploaded to CloudWatch and released from memory.

If this is not specified, metrics will be uploaded once per minute.

Smaller values will: (1) reduce the amount of memory used by the library (particularly when detailedMetrics(Collection) are enabled), (2) increase the number of CloudWatch calls (and therefore increase CloudWatch usage cost).

Larger values will: (1) increase the amount of memory used by the library (particularly when detailedMetrics are enabled), (2) increase the time it takes for metric data to appear in CloudWatch, (3) reduce the number of CloudWatch calls (and therefore decrease CloudWatch usage cost).

Warning: When detailedMetrics are enabled, all unique metric values are stored in memory until they can be published to CloudWatch. A high uploadFrequency with multiple detailedMetrics enabled can quickly consume heap memory while the values wait to be published to CloudWatch. In memory constrained environments, it is recommended to minimize the number of detailedMetrics configured on the publisher, or to upload metric data more frequently. As with all performance and resource concerns, profiling in a production-like environment is encouraged.

maximumCallsPerUpload

public CloudWatchMetricPublisher.Builder maximumCallsPerUpload(Integer maximumCallsPerUpload)

Configure the maximum number of CloudWatchAsyncClient.putMetricData(PutMetricDataRequest) calls that an individual "upload" event can make to CloudWatch. Any metrics that would exceed this limit are dropped during the upload, logging a warning on the software.amazon.awssdk.metrics.publishers.cloudwatch namespace.

The SDK will always attempt to maximize the number of metrics per put-metric-data call, but uploads will be split into multiple put-metric-data calls if they include a lot of different metrics or if there are a lot of high-value- distribution detailedMetrics(Collection) being monitored.

This value combined with the uploadFrequency(Duration) effectively provide a "hard cap" on the number of put-metric-data calls, to prevent unbounded cost in the event that too many metrics are enabled by the user.

If this is not specified, put-metric-data calls will be capped at 10 per upload.

dimensions

public CloudWatchMetricPublisher.Builder dimensions(Collection<SdkMetric<String>> dimensions)

Configure the SdkMetrics that are used to define the Dimensions metrics are aggregated under.

If this is not specified, CoreMetric.SERVICE_ID and CoreMetric.OPERATION_NAME are used, allowing you to compare metrics for different services and operations.

Warning: Configuring the dimensions incorrectly can result in a large increase in the number of unique metrics and put-metric-data calls to cloudwatch, which have an associated monetary cost. Be sure you're choosing your metric dimensions wisely, and that you always evaluate the cost of modifying these values on your monthly usage costs.

Example useful settings:

• CoreMetric.SERVICE_ID and CoreMetric.OPERATION_NAME (default): Separate metrics by service and operation, so that you can compare latencies between AWS services and operations.
• CoreMetric.SERVICE_ID, CoreMetric.OPERATION_NAME and CoreMetric.HOST_NAME: Separate metrics by service, operation and host so that you can compare latencies across hosts in your fleet. Note: This should only be used when your fleet is relatively small. Large fleets result in a large number of unique metrics being generated.
• CoreMetric.SERVICE_ID, CoreMetric.OPERATION_NAME and HttpMetric.HTTP_CLIENT_NAME: Separate metrics by service, operation and HTTP client type so that you can compare latencies between different HTTP client implementations.

dimensions

@SafeVarargs
public final CloudWatchMetricPublisher.Builder dimensions(SdkMetric<String>... dimensions)

See Also:

dimensions(SdkMetric[])

metricCategories

public CloudWatchMetricPublisher.Builder metricCategories(Collection<MetricCategory> metricCategories)

Configure the MetricCategorys that should be uploaded to CloudWatch.

If this is not specified, MetricCategory.ALL is used.

All SdkMetrics are associated with at least one MetricCategory. This setting determines which category of metrics uploaded to CloudWatch. Any metrics CloudWatchMetricPublisher.publish(MetricCollection)ed that do not fall under these configured categories are ignored.

Note: If there are dimensions(Collection) configured that do not fall under these MetricCategory values, the dimensions will NOT be ignored. In other words, the metric category configuration only affects which metrics are uploaded to CloudWatch, not which values can be used for dimensions.

metricCategories

public CloudWatchMetricPublisher.Builder metricCategories(MetricCategory... metricCategories)

See Also:

metricCategories(Collection)

metricLevel

public CloudWatchMetricPublisher.Builder metricLevel(MetricLevel metricLevel)

Configure the MetricLevel that should be uploaded to CloudWatch.

If this is not specified, MetricLevel.INFO is used.

All SdkMetrics are associated with one MetricLevel. This setting determines which level of metrics uploaded to CloudWatch. Any metrics CloudWatchMetricPublisher.publish(MetricCollection)ed that do not fall under these configured categories are ignored.

Note: If there are dimensions(Collection) configured that do not fall under this MetricLevel values, the dimensions will NOT be ignored. In other words, the metric category configuration only affects which metrics are uploaded to CloudWatch, not which values can be used for dimensions.

detailedMetrics

public CloudWatchMetricPublisher.Builder detailedMetrics(Collection<SdkMetric<?>> detailedMetrics)

Configure the set of metrics for which detailed values and counts are uploaded to CloudWatch, instead of summaries.

By default, all metrics published to this publisher are summarized using StatisticSets. This saves memory, because it allows the publisher to store a fixed amount of information in memory, no matter how many different metric values are published. The drawback is that metrics other than count, sum, average, maximum and minimum are not made available in CloudWatch. The detailedMetrics setting instructs the publisher to store and publish itemized MetricDatum.values() and MetricDatum.counts(), which enables other metrics like p90 and p99 to be queried in CloudWatch.

Warning: When detailedMetrics are enabled, all unique metric values are stored in memory until they can be published to CloudWatch. A high uploadFrequency with multiple detailedMetrics enabled can quickly consume heap memory while the values wait to be published to CloudWatch. In memory constrained environments, it is recommended to minimize the number of detailedMetrics configured on the publisher, or to upload metric data more frequently. As with all performance and resource concerns, profiling in a production-like environment is encouraged.

In addition to additional heap memory usage, detailed metrics can result in more requests being sent to CloudWatch, which can also introduce additional usage cost. The maximumCallsPerUpload(Integer) acts as a safeguard against too many calls being made, but if you configure multiple detailedMetrics, you may need to increase the maximumCallsPerUpload limit.

detailedMetrics

public CloudWatchMetricPublisher.Builder detailedMetrics(SdkMetric<?>... detailedMetrics)

See Also:

detailedMetrics(Collection)

build

public CloudWatchMetricPublisher build()

Build a CloudWatchMetricPublisher using the configuration currently configured on this publisher.