@aws-cdk/cloudwatch

Add alarms and graphs to CDK applications

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 objects have the lambda.metricErrors() method, which represents the amount of errors reported by that Lambda function:

const errors = lambda.metricErrors();

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:

const minuteErrorRate = lambda.metricErrors({
    statistic: 'avg',
    periodSec: 60,
    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:

new Alarm(this, 'Alarm', {
    metric: lambda.metricErrors(),
    threshold: 100,
    evaluationPeriods: 2,
});

Alternatively, you can call metric.newAlarm():

lambda.metricErrors().newAlarm(this, 'Alarm', {
    threshold: 100,
    evaluationPeriods: 2,
});

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

  • threshold: the value to compare the metric against.
  • comparisonOperator: the comparison operation to use, defaults to metric >= threshold.
  • evaluationPeriods: how many consecutive periods the metric has to be breaching the the threshold for the alarm to trigger.

Making 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:

  • GraphWidget – shows any number of metrics on both the left and right vertical axes.
  • AlarmWidget – shows the graph and alarm line for a single alarm.
  • SingleValueWidget – shows the current value of a set of metrics.
  • TextWidget – shows some static Markdown.

Warning! Due to a bug in CloudFormation, you cannot update a Dashboard after initially creating it if you let its name automatically be generated. You must set dashboardName if you intend to update the dashboard after creation.

(This note will be removed once the bug is fixed).

Graph widget

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

dashboard.add(new GraphWidget({
    title: "Executions vs error rate",

    left: [executionCountMetric],

    right: [errorCountMetric.with({
        statistic: "average",
        label: "Error rate",
        color: "00FF00"
    })]
}));

Alarm widget

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

dashboard.add(new AlarmWidget({
    title: "Errors",
    alarm: errorAlarm,
}));

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):

dashboard.add(new SingleValueWidget({
    metrics: [visitorCount, purchaseCount],
}));

Text widget

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

dashboard.add(new TextWidget({
    markdown: '# Key Performance Indicators'
}));

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:

  • Column: stack two or more widgets vertically.
  • Row: lay out two or more widgets horizontally.
  • Spacer: take up empty space

Reference

Alarm

class _aws-cdk_cloudwatch.Alarm(parent, name, props)

An alarm on a CloudWatch metric

Extends:

Construct

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (AlarmProps) –
onAlarm(*actions)

Trigger this action if the alarm fires Typically the ARN of an SNS topic or ARN of an AutoScaling policy.

Parameters:*actions (IAlarmAction) –
onInsufficientData(*actions)

Trigger this action if there is insufficient data to evaluate the alarm Typically the ARN of an SNS topic or ARN of an AutoScaling policy.

Parameters:*actions (IAlarmAction) –
onOk(*actions)

Trigger this action if the alarm returns from breaching state into ok state Typically the ARN of an SNS topic or ARN of an AutoScaling policy.

Parameters:*actions (IAlarmAction) –
toAnnotation() → @aws-cdk/cloudwatch.HorizontalAnnotation

Turn this alarm into a horizontal annotation This is useful if you want to represent an Alarm in a non-AlarmWidget. An AlarmWidget can directly show an alarm, but it can only show a single alarm and no other metrics. Instead, you can convert the alarm to a HorizontalAnnotation and add it as an annotation to another graph. This might be useful if: - You want to show multiple alarms inside a single graph, for example if you have both a “small margin/long period” alarm as well as a “large margin/short period” alarm. - You want to show an Alarm line in a graph with multiple metrics in it.

Return type:HorizontalAnnotation
alarmArn

ARN of this alarm

Type:AlarmArn (readonly)
metric

The metric object this alarm was based on

Type:Metric (readonly)

AlarmArn

class _aws-cdk_cloudwatch.AlarmArn([valueOrFunction])

The ARN of an Alarm

Extends:Arn
Parameters:valueOrFunction (any or None) –

AlarmMetricJson (interface)

class _aws-cdk_cloudwatch.AlarmMetricJson

Properties used to construct the Metric identifying part of an Alarm

dimensions

The dimensions to apply to the alarm

Type:Dimension or None
namespace

Namespace of the metric

Type:string
metricName

Name of the metric

Type:string
period

How many seconds to aggregate over

Type:number
statistic

Simple aggregation function to use

Type:string or None
extendedStatistic

Percentile aggregation function to use

Type:string or None
unit

The unit of the alarm

Type:string or None

AlarmProps (interface)

class _aws-cdk_cloudwatch.AlarmProps

Properties for Alarms

metric

The metric to add the alarm on Metric objects can be obtained from most resources, or you can construct custom Metric objects by instantiating one.

Type:Metric
alarmName

Name of the alarm

Type:string or None
alarmDescription

Description for the alarm

Type:string or None
comparisonOperator

Comparison to use to check if metric is breaching

Type:string or None
threshold

The value against which the specified statistic is compared.

Type:number
evaluationPeriods

The number of periods over which data is compared to the specified threshold.

Type:number
evaluateLowSampleCountPercentile

Specifies whether to evaluate the data and potentially change the alarm state if there are too few data points to be statistically significant. Used only for alarms that are based on percentiles.

Type:string or None
treatMissingData

Sets how this alarm is to handle missing data points.

Type:string or None
actionsEnabled

Whether the actions for this alarm are enabled

Type:boolean or None

AlarmWidget

class _aws-cdk_cloudwatch.AlarmWidget(props)

Display the metric associated with an alarm, including the alarm line

Extends:ConcreteWidget
Parameters:props (AlarmWidgetProps) –
toJson() → any[]

Return the widget JSON for use in the dashboard

Return type:any

AlarmWidgetProps (interface)

class _aws-cdk_cloudwatch.AlarmWidgetProps

Properties for an AlarmWidget

Extends:MetricWidgetProps
alarm

The alarm to show

Type:Alarm
leftAxisRange

Range of left Y axis

Type:YAxisRange or None

Column

class _aws-cdk_cloudwatch.Column(*widgets)

A widget that contains other widgets in a vertical column Widgets will be laid out next to each other

Implements:IWidget
Parameters:*widgets (IWidget) –
position(x, y)

Place the widget at a given position

Parameters:
  • x (number) –
  • y (number) –
toJson() → any[]

Return the widget JSON for use in the dashboard

Return type:any
width

The amount of horizontal grid units the widget will take up

Type:number (readonly)
height

The amount of vertical grid units the widget will take up

Type:number (readonly)

ComparisonOperator (enum)

class _aws-cdk_cloudwatch.ComparisonOperator
GreaterThanOrEqualToThreshold
GreaterThanThreshold
LessThanThreshold
LessThanOrEqualToThreshold

ConcreteWidget

class _aws-cdk_cloudwatch.ConcreteWidget(width, height)

A real CloudWatch widget that has its own fixed size and remembers its position This is in contrast to other widgets which exist for layout purposes.

Implements:

IWidget

Abstract:

Yes

Parameters:
  • width (number) –
  • height (number) –
position(x, y)

Place the widget at a given position

Parameters:
  • x (number) –
  • y (number) –
toJson() → any[]

Return the widget JSON for use in the dashboard

Return type:any
Abstract:Yes
width

The amount of horizontal grid units the widget will take up

Type:number (readonly)
height

The amount of vertical grid units the widget will take up

Type:number (readonly)
x
Type:number or None
y
Type:number or None

Dashboard

class _aws-cdk_cloudwatch.Dashboard(parent, name[, props])

A CloudWatch dashboard

Extends:

Construct

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (DashboardProps or None) –
add(*widgets)

Add a widget to the dashboard. Widgets given in multiple calls to add() will be laid out stacked on top of each other. Multiple widgets added in the same call to add() will be laid out next to each other.

Parameters:*widgets (IWidget) –

DashboardProps (interface)

class _aws-cdk_cloudwatch.DashboardProps
dashboardName

Name of the dashboard

Type:string or None

Dimension (interface)

class _aws-cdk_cloudwatch.Dimension

Metric dimension

name

Name of the dimension

Type:string
value

Value of the dimension

Type:any

GraphWidget

class _aws-cdk_cloudwatch.GraphWidget(props)

A dashboard widget that displays MarkDown

Extends:ConcreteWidget
Parameters:props (GraphWidgetProps) –
toJson() → any[]

Return the widget JSON for use in the dashboard

Return type:any

GraphWidgetProps (interface)

class _aws-cdk_cloudwatch.GraphWidgetProps

Properties for a GraphWidget

Extends:MetricWidgetProps
left

Metrics to display on left Y axis

Type:Metric or None
right

Metrics to display on right Y axis

Type:Metric or None
leftAnnotations

Annotations for the left Y axis

Type:HorizontalAnnotation or None
rightAnnotations

Annotations for the right Y axis

Type:HorizontalAnnotation or None
stacked

Whether the graph should be shown as stacked lines

Type:boolean or None
leftAxisRange

Range of left Y axis

Type:YAxisRange or None
rightAxisRange

Range of right Y axis

Type:YAxisRange or None

HorizontalAnnotation (interface)

class _aws-cdk_cloudwatch.HorizontalAnnotation

Horizontal annotation to be added to a graph

value

The value of the annotation

Type:number
label

Label for the annotation

Type:string or None
color

Hex color code to be used for the annotation

Type:string or None
fill

Add shading above or below the annotation

Type:string or None
visible

Whether the annotation is visible

Type:boolean or None

IAlarmAction (interface)

class _aws-cdk_cloudwatch.IAlarmAction

Interface for objects that can be the targets of CloudWatch alarm actions

alarmActionArn

Return the ARN that should be used for a CloudWatch Alarm action

Type:Arn (readonly)

IWidget (interface)

class _aws-cdk_cloudwatch.IWidget

A single dashboard widget

width

The amount of horizontal grid units the widget will take up

Type:number (readonly)
height

The amount of vertical grid units the widget will take up

Type:number (readonly)
position(x, y)

Place the widget at a given position

Parameters:
  • x (number) –
  • y (number) –
toJson() → any[]

Return the widget JSON for use in the dashboard

Return type:any

Metric

class _aws-cdk_cloudwatch.Metric(props)

A metric emitted by a service The metric is a combination of a metric identifier (namespace, name and dimensions) and an aggregation function (statistic, period and unit). It also contains metadata which is used only in graphs, such as color and label. It makes sense to embed this in here, so that compound constructs can attach that metadata to metrics they expose. This class does not represent a resource, so hence is not a construct. Instead, Metric is an abstraction that makes it easy to specify metrics for use in both alarms and graphs.

Parameters:props (MetricProps) –
with(props) → @aws-cdk/cloudwatch.Metric

Return a copy of Metric with properties changed. All properties except namespace and metricName can be changed.

Parameters:props (MetricCustomization) – The set of properties to change.
Return type:Metric
newAlarm(parent, name, props) → @aws-cdk/cloudwatch.Alarm

Make a new Alarm for this metric Combines both properties that may adjust the metric (aggregation) as well as alarm properties.

Parameters:
  • parent (Construct) –
  • name (string) –
  • props (NewAlarmProps) –
Return type:

Alarm

dimensionsAsList() → @aws-cdk/cloudwatch.Dimension[]

Return the dimensions of this Metric as a list of Dimension.

Return type:Dimension
dimensions
Type:any or None (readonly)
namespace
Type:string (readonly)
metricName
Type:string (readonly)
periodSec
Type:number (readonly)
statistic
Type:string (readonly)
unit
Type:string or None (readonly)
label
Type:string or None (readonly)
color
Type:string or None (readonly)

MetricCustomization (interface)

class _aws-cdk_cloudwatch.MetricCustomization

Properties of a metric that can be changed

dimensions

Dimensions of the metric

Type:any or None
periodSec

The period over which the specified statistic is applied. Specify time in seconds, in multiples of 60.

Type:number or None
statistic

What function to use for aggregating. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.NN”

Type:string or None
unit

Unit for the metric that is associated with the alarm

Type:string or None
label

Label for this metric when added to a Graph in a Dashboard

Type:string or None
color

Color for this metric when added to a Graph in a Dashboard

Type:string or None

MetricProps (interface)

class _aws-cdk_cloudwatch.MetricProps

Properties for a metric

dimensions

Dimensions of the metric

Type:any or None
namespace

Namespace of the metric.

Type:string
metricName

Name of the metric.

Type:string
periodSec

The period over which the specified statistic is applied. Specify time in seconds, in multiples of 60.

Type:number or None
statistic

What function to use for aggregating. Can be one of the following (case insensitive) - “minimum” | “min” - “maximum” | “max” - “average” | “avg” - “sum” - “samplecount | “n” - “pNN.NN”

Type:string or None
unit

Unit for the metric that is associated with the alarm

Type:string or None
label

Label for this metric when added to a Graph in a Dashboard

Type:string or None
color

Color for this metric when added to a Graph in a Dashboard

Type:string or None

MetricWidgetProps (interface)

class _aws-cdk_cloudwatch.MetricWidgetProps

Basic properties for widgets that display metrics

title

Title for the graph

Type:string or None
region

The region the metrics of this graph should be taken from

Type:Region or None
width

Width of the widget, in a grid of 24 units wide

Type:number or None
height

Height of the widget

Type:number or None

NewAlarmProps (interface)

class _aws-cdk_cloudwatch.NewAlarmProps

Properties to make an alarm from a metric

periodSec

The period over which the specified statistic is applied. Specify time in seconds, in multiples of 60.

Type:number or None
statistic

What function to use for aggregating. Can be one of the following: - “Minimum” | “min” - “Maximum” | “max” - “Average” | “avg” - “Sum” | “sum” - “SampleCount | “n” - “pNN.NN”

Type:string or None
alarmName

Name of the alarm

Type:string or None
alarmDescription

Description for the alarm

Type:string or None
comparisonOperator

Comparison to use to check if metric is breaching

Type:string or None
threshold

The value against which the specified statistic is compared.

Type:number
evaluationPeriods

The number of periods over which data is compared to the specified threshold.

Type:number
evaluateLowSampleCountPercentile

Specifies whether to evaluate the data and potentially change the alarm state if there are too few data points to be statistically significant. Used only for alarms that are based on percentiles.

Type:string or None
treatMissingData

Sets how this alarm is to handle missing data points.

Type:string or None
actionsEnabled

Whether the actions for this alarm are enabled

Type:boolean or None

Region

class _aws-cdk_cloudwatch.Region([valueOrFunction])

An AWS region

Extends:Token
Parameters:valueOrFunction (any or None) –

Row

class _aws-cdk_cloudwatch.Row(*widgets)

A widget that contains other widgets in a horizontal row Widgets will be laid out next to each other

Implements:IWidget
Parameters:*widgets (IWidget) –
position(x, y)

Place the widget at a given position

Parameters:
  • x (number) –
  • y (number) –
toJson() → any[]

Return the widget JSON for use in the dashboard

Return type:any
width

The amount of horizontal grid units the widget will take up

Type:number (readonly)
height

The amount of vertical grid units the widget will take up

Type:number (readonly)

Shading (enum)

class _aws-cdk_cloudwatch.Shading
None
Above
Below

SingleValueWidget

class _aws-cdk_cloudwatch.SingleValueWidget(props)

A dashboard widget that displays the most recent value for every metric

Extends:ConcreteWidget
Parameters:props (SingleValueWidgetProps) –
toJson() → any[]

Return the widget JSON for use in the dashboard

Return type:any

SingleValueWidgetProps (interface)

class _aws-cdk_cloudwatch.SingleValueWidgetProps

Properties for a SingleValueWidget

Extends:MetricWidgetProps
metrics

Metrics to display

Type:Metric

Spacer

class _aws-cdk_cloudwatch.Spacer(props)

A widget that doesn’t display anything but takes up space

Implements:IWidget
Parameters:props (SpacerProps) –
position(_x, _y)

Place the widget at a given position

Parameters:
  • _x (number) –
  • _y (number) –
toJson() → any[]

Return the widget JSON for use in the dashboard

Return type:any
width

The amount of horizontal grid units the widget will take up

Type:number (readonly)
height

The amount of vertical grid units the widget will take up

Type:number (readonly)

SpacerProps (interface)

class _aws-cdk_cloudwatch.SpacerProps

Props of the spacer

width

Width of the spacer

Type:number or None
height

Height of the spacer

Type:number or None

Statistic (enum)

class _aws-cdk_cloudwatch.Statistic
SampleCount
Average
Sum
Minimum
Maximum

TextWidget

class _aws-cdk_cloudwatch.TextWidget(props)

A dashboard widget that displays MarkDown

Extends:ConcreteWidget
Parameters:props (TextWidgetProps) –
position(x, y)

Place the widget at a given position

Parameters:
  • x (number) –
  • y (number) –
toJson() → any[]

Return the widget JSON for use in the dashboard

Return type:any

TextWidgetProps (interface)

class _aws-cdk_cloudwatch.TextWidgetProps

Properties for a Text widget

markdown

The text to display, in MarkDown format

Type:string
width

Width of the widget, in a grid of 24 units wide

Type:number or None
height

Height of the widget

Type:number or None

TreatMissingData (enum)

class _aws-cdk_cloudwatch.TreatMissingData
Breaching
NotBreaching
Ignore
Missing

Unit (enum)

class _aws-cdk_cloudwatch.Unit
Seconds
Microseconds
Milliseconds
Bytes_
Kilobytes
Megabytes
Gigabytes
Terabytes
Bits
Kilobits
Megabits
Gigabits
Terabits
Percent
Count
BytesPerSecond
KilobytesPerSecond
MegabytesPerSecond
GigabytesPerSecond
TerabytesPerSecond
BitsPerSecond
KilobitsPerSecond
MegabitsPerSecond
GigabitsPerSecond
TerabitsPerSecond
CountPerSecond
None

YAxisRange (interface)

class _aws-cdk_cloudwatch.YAxisRange

A minimum and maximum value for either the left or right Y axis

min

The minimum value

Type:number or None
max

The maximum value

Type:number or None