CDK Constructs for AWS CloudWatch
Project description
Amazon CloudWatch Construct Library
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:
const errors = fn.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 = fn.metricErrors({
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 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: fn.metricErrors(),
threshold: 100,
evaluationPeriods: 2,
});
Alternatively, you can call metric.createAlarm()
:
fn.metricErrors().createAlarm(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.
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.
Graph widget
A graph widget can display any number of metrics on either the left
or
right
vertical axis:
dashboard.addWidgets(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.addWidgets(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.addWidgets(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.addWidgets(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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for aws-cdk.aws-cloudwatch-1.10.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | ae6f330d2389625c79838dc9fac11de994c9905f4e773933d89e9fd596db0896 |
|
MD5 | 9f554331e1f50ce698e68f16f4570807 |
|
BLAKE2b-256 | f4171cc6c7ed4858213ab92930031a2a49ec94012d6004684988f41f8d84a07f |
Hashes for aws_cdk.aws_cloudwatch-1.10.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bbe5f9ccbdde831696395bda105a3dda6775d5e320eaa9d6effe7011de75d6e6 |
|
MD5 | 410cee6c4117f18f7d5044e0c6d9aca1 |
|
BLAKE2b-256 | 9864335c756f857de8e5c1d044391d91ece5058c047a05340725abadbedf4116 |