@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 either0
or1
(for exampleErrors
for a Lambda) and some are only emitted as1
(for exampleNumberOfMessagesPublished
for an SNS topic).In case
0
-metrics are emitted, it makes sense to take theAverage
of this metric: the result will be the fraction of errors over all executions.If
0
-metrics are not emitted, theAverage
will always be equal to1
, and not be very useful.In order to simplify the mental model of
Metric
objects, we default to aggregating usingSum
, 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 tometric >= 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)
- parent (
AlarmArn¶
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¶
AlarmWidgetProps (interface)¶
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)¶
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
) –
- parent (
DashboardProps (interface)¶
Dimension (interface)¶
GraphWidget¶
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)¶
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
- parent (
-
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¶
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)
-
SingleValueWidget¶
SingleValueWidgetProps (interface)¶
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)¶
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)¶
TreatMissingData (enum)¶
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
¶
-