Skip navigation links

Package software.amazon.awscdk.services.cloudwatch

Amazon CloudWatch Construct Library

See: Description

Package software.amazon.awscdk.services.cloudwatch Description

Amazon CloudWatch Construct Library

---

cfn-resources: Stable

cdk-constructs: Stable

Metric objects

Metric objects represent a metric that is emitted by AWS services or your own application, such as CPUUsage, FailureCount or Bandwidth.

Metric objects can be constructed directly or are exposed by resources as attributes. Resources that expose metrics will have functions that look like metricXxx() which will return a Metric object, initialized with defaults that make sense.

For example, lambda.Function objects have the fn.metricErrors() method, which represents the amount of errors reported by that Lambda function: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object errors = fn.metricErrors();

You can also instantiate Metric objects to reference any published metric that's not exposed using a convenience method on the CDK construct. For example: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object hostedZone = HostedZone.Builder.create(this, "MyHostedZone").zoneName("example.org").build();
 Object metric = Metric.Builder.create()
         .namespace("AWS/Route53")
         .metricName("DNSQueries")
         .dimensions(Map.of(
                 "HostedZoneId", hostedZone.getHostedZoneId()))
         .build();

Instantiating a new Metric object

If you want to reference a metric that is not yet exposed by an existing construct, you can instantiate a Metric object to represent it. For example: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object metric = Metric.Builder.create()
         .namespace("MyNamespace")
         .metricName("MyMetric")
         .dimensions(Map.of(
                 "ProcessingStep", "Download"))
         .build();

Metric Math

Math expressions are supported by instantiating the MathExpression class. For example, a math expression that sums two other metrics looks like this: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object allProblems = MathExpression.Builder.create()
         .expression("errors + faults")
         .usingMetrics(Map.of(
                 "errors", myConstruct.metricErrors(),
                 "faults", myConstruct.metricFaults()))
         .build();

You can use MathExpression objects like any other metric, including using them in other math expressions: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object problemPercentage = MathExpression.Builder.create()
         .expression("(problems / invocations) * 100")
         .usingMetrics(Map.of(
                 "problems", allProblems,
                 "invocations", myConstruct.metricInvocations()))
         .build();

Aggregation

To graph or alarm on metrics you must aggregate them first, using a function like Average or a percentile function like P99. By default, most Metric objects returned by CDK libraries will be configured as Average over 300 seconds (5 minutes). The exception is if the metric represents a count of discrete events, such as failures. In that case, the Metric object will be configured as Sum over 300 seconds, i.e. it represents the number of times that event occurred over the time period.

If you want to change the default aggregation of the Metric object (for example, the function or the period), you can do so by passing additional parameters to the metric function call: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object minuteErrorRate = fn.metricErrors(Map.of(
         "statistic", "avg",
         "period", Duration.minutes(1),
         "label", "Lambda failure rate"));

This function also allows changing the metric label or color (which will be useful when embedding them in graphs, see below).

Rates versus Sums

The reason for using Sum to count discrete events is that some events are emitted as either 0 or 1 (for example Errors for a Lambda) and some are only emitted as 1 (for example NumberOfMessagesPublished for an SNS topic).

In case 0-metrics are emitted, it makes sense to take the Average of this metric: the result will be the fraction of errors over all executions.

If 0-metrics are not emitted, the Average will always be equal to 1, and not be very useful.

In order to simplify the mental model of Metric objects, we default to aggregating using Sum, which will be the same for both metrics types. If you happen to know the Metric you want to alarm on makes sense as a rate (Average) you can always choose to change the statistic.

Alarms

Alarms can be created on metrics in one of two ways. Either create an Alarm object, passing the Metric object to set the alarm on: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Alarm.Builder.create(this, "Alarm")
         .metric(fn.metricErrors())
         .threshold(100)
         .evaluationPeriods(2)
         .build();

Alternatively, you can call metric.createAlarm(): 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 fn.metricErrors().createAlarm(this, "Alarm", Map.of(
         "threshold", 100,
         "evaluationPeriods", 2));

The most important properties to set while creating an Alarms are:

Alarm Actions

To add actions to an alarm, use the integration classes from the @aws-cdk/aws-cloudwatch-actions package. For example, to post a message to an SNS topic when an alarm breaches, do the following: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.aws_cloudwatch_actions;
 
 
 // ...
 Topic topic = new Topic(stack, "Topic");
 Object alarm = Alarm.Builder.create(stack, "Alarm").build();
 
 alarm.addAlarmAction(new SnsAction(topic));

Composite Alarms

Composite Alarms can be created from existing Alarm resources. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object alarmRule = AlarmRule.anyOf(AlarmRule.allOf(AlarmRule.anyOf(alarm1, AlarmRule.fromAlarm(alarm2, AlarmState.getOK()), alarm3), AlarmRule.not(AlarmRule.fromAlarm(alarm4, AlarmState.getINSUFFICIENT_DATA()))), AlarmRule.fromBoolean(false));
 
 CompositeAlarm.Builder.create(this, "MyAwesomeCompositeAlarm")
         .alarmRule(alarmRule)
         .build();

A note on units

In CloudWatch, Metrics datums are emitted with units, such as seconds or bytes. When Metric objects are given a unit attribute, it will be used to filter the stream of metric datums for datums emitted using the same unit attribute.

In particular, the unit field is not used to rescale datums or alarm threshold values (for example, it cannot be used to specify an alarm threshold in Megabytes if the metric stream is being emitted as bytes).

You almost certainly don't want to specify the unit property when creating Metric objects (which will retrieve all datums regardless of their unit), unless you have very specific requirements. Note that in any case, CloudWatch only supports filtering by unit for Alarms, not in Dashboard graphs.

Please see the following GitHub issue for a discussion on real unit calculations in CDK: https://github.com/aws/aws-cdk/issues/5595

Dashboards

Dashboards are set of Widgets stored server-side which can be accessed quickly from the AWS console. Available widgets are graphs of a metric over time, the current value of a metric, or a static piece of Markdown which explains what the graphs mean.

The following widgets are available:

Graph widget

A graph widget can display any number of metrics on either the left or right vertical axis: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 dashboard.addWidgets(GraphWidget.Builder.create()
         .title("Executions vs error rate")
 
         .left(asList(executionCountMetric))
 
         .right(asList(errorCountMetric.with(Map.of(
                 "statistic", "average",
                 "label", "Error rate",
                 "color", Color.getGREEN()))))
         .build());

Using the methods addLeftMetric() and addRightMetric() you can add metrics to a graph widget later on.

Graph widgets can also display annotations attached to the left or the right y-axis. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 dashboard.addWidgets(GraphWidget.Builder.create()
         // ...
         // ...
 
         .leftAnnotations(asList(Map.of("value", 1800, "label", Duration.minutes(30).toHumanString(), "color", Color.getRED()), Map.of("value", 3600, "label", "1 hour", "color", "#2ca02c")))
         .build());

The graph legend can be adjusted from the default position at bottom of the widget. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 dashboard.addWidgets(GraphWidget.Builder.create()
         // ...
         // ...
 
         .legendPosition(LegendPosition.getRIGHT())
         .build());

The graph can publish live data within the last minute that has not been fully aggregated. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 dashboard.addWidgets(GraphWidget.Builder.create()
         // ...
         // ...
 
         .liveData(true)
         .build());

The graph view can be changed from default 'timeSeries' to 'bar' or 'pie'. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 dashboard.addWidgets(GraphWidget.Builder.create()
         // ...
         // ...
 
         .view(GraphWidgetView.getBAR())
         .build());

Alarm widget

An alarm widget shows the graph and the alarm line of a single alarm: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 dashboard.addWidgets(AlarmWidget.Builder.create()
         .title("Errors")
         .alarm(errorAlarm)
         .build());

Single value widget

A single-value widget shows the latest value of a set of metrics (as opposed to a graph of the value over time): 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 dashboard.addWidgets(SingleValueWidget.Builder.create()
         .metrics(asList(visitorCount, purchaseCount))
         .build());

Show as many digits as can fit, before rounding. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 dashboard.addWidgets(SingleValueWidget.Builder.create()
         // ..
         // ..
 
         .fullPrecision(true)
         .build());

Text widget

A text widget shows an arbitrary piece of MarkDown. Use this to add explanations to your dashboard: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 dashboard.addWidgets(TextWidget.Builder.create()
         .markdown("# Key Performance Indicators")
         .build());

Alarm Status widget

An alarm status widget displays instantly the status of any type of alarms and gives the ability to aggregate one or more alarms together in a small surface. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 dashboard.addWidgets(
 AlarmStatusWidget.Builder.create()
         .alarms(asList(errorAlarm))
         .build());

Query results widget

A LogQueryWidget shows the results of a query from Logs Insights: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 dashboard.addWidgets(LogQueryWidget.Builder.create()
         .logGroupNames(asList("my-log-group"))
         .view(LogQueryVisualizationType.getTABLE())
         // The lines will be automatically combined using '\n|'.
         .queryLines(asList("fields @message", "filter @message like /Error/"))
         .build());

Dashboard Layout

The widgets on a dashboard are visually laid out in a grid that is 24 columns wide. Normally you specify X and Y coordinates for the widgets on a Dashboard, but because this is inconvenient to do manually, the library contains a simple layout system to help you lay out your dashboards the way you want them to.

Widgets have a width and height property, and they will be automatically laid out either horizontally or vertically stacked to fill out the available space.

Widgets are added to a Dashboard by calling add(widget1, widget2, ...). Widgets given in the same call will be laid out horizontally. Widgets given in different calls will be laid out vertically. To make more complex layouts, you can use the following widgets to pack widgets together in different ways:

Skip navigation links

Copyright © 2021. All rights reserved.