@aws-cdk/aws-cloudwatch

Metrics

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',
    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: fn.metricErrors(),
    threshold: 100,
    evaluationPeriods: 2,
});

Alternatively, you can call metric.newAlarm():

fn.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.

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

Changelog

0.22.0 (2019-01-10)

This is a major release with multiple breaking changes in the core layers. Please consult the breaking changes section below for details.

We are focusing these days on finalizing the common patterns and APIs of the CDK framework and the AWS Construct Library, which is why you are seeing all these breaking changes. Expect a few more releases with changes of that nature as we stabilize these APIs, so you might want to hold off with upgrading. We will communicate when this foundational work is complete.

Bug Fixes

• core: automatic cross-stack refs for CFN resources (#1510) (ca5ee35)
• ecs: correct typo and other minor mistakes in ecs readme (#1448) (9c91b20)
• elbv2: unable to specify load balancer name (#1486) (5b24583), closes #973 #1481
• lambda: use IRole instead of Role to allow imports (#1509) (b909dcd)
• toolkit: fix typo in --rename option description (#1438) (1dd56d4)
• toolkit: support multiple toolkit stacks in the same environment (#1427) (095da14), closes #1416

Features

• apigateway: add tracingEnabled property to APIGW Stage (#1482) (fefa764)
• assets: enable local tooling scenarios such as lambda debugging (#1433) (0d2b633), closes #1432
• aws-cdk: better stack dependency handling (#1511) (b4bbaf0), closes #1508 #1505
• aws-codepipeline: jenkins build and test actions (#1216) (471e8eb)
• aws-codepipeline: support notifications on the ManualApprovalAction (#1368) (068fa46), closes #1222
• aws-ecs: add support Amazon Linux 2 (#1484) (82ec0ff), closes #1483
• aws-kms: allow tagging kms keys (#1485) (f43b4d4)
• aws-lambda: add input and output artifacts to the CodePipeline action (#1390) (fbd7728), closes #1384
• cdk: transparently use constructs from another stack (d7371f0), closes #1324
• cli: allow specifying options using env vars (#1447) (7cd84a0)
• aws resource api linting (breaking changes) (#1434) (8c17ca7), closes #742 #1428
• core: cloudformation condition chaining (#1494) (2169015), closes #1457
• diff: better diff of arbitrary json objects (#1488) (607f997)
• route53: support cname records (#1487) (17eddd1), closes #1420
• step-functions: support parameters option (#1492) (935054a), closes #1480
• core: construct base class changes (breaking) (#1444) (fb22a32), closes #1431 #1441 #189 #1441 #1431
• core: idiomize cloudformation intrinsics functions (#1428) (04217a5), closes #202
• cloudformation: no more generated attribute types in CFN layer (L1) (#1489) (4d6d5ca), closes #1455 #1406
• cloudformation: stop generating legacy cloudformation resources (#1493) (81b4174)

BREAKING CHANGES TO EXPERIMENTAL FEATURES

• Cross-stack references: if you are using export() and import() to share constructs between stacks, you can stop doing that, instead of FooImportProps accept an IFoo directly on the consuming stack, and use that object as usual.
• ArnUtils.fromComponents() and ArnUtils.parse() have been moved onto Stack.
• All CloudFormation pseudo-parameter (such as AWS::AccountId etc) are now also accessible via Stack, as stack.accountId etc.
• All CloudFormation intrinsic functions are now represented as static methods under the Fn class (e.g. Fn.join(...) instead of new FnJoin(...).toString())
• resolve() has been moved to this.node.resolve().
• CloudFormationJSON.stringify() has been moved to this.node.stringifyJson(). validate() now should be protected.
• The deprecated cloudformation.XxxResource classes have been removed. Use the CfnXxx classes instead.
• Any CfnXxx resource attributes that represented a list of strings are now typed as string[]s (via #1144). Attributes that represent strings, are still typed as string (#712) and all other attribute types are represented as cdk.Token.
• route53: The route53.TXTRecord class was renamed to route53.TxtRecord.
• route53: record classes now require a zone when created (not assuming zone is the parent construct).
• lambda: the static "metric" methods moved from lambda.FunctionRef to lambda.Function.
• Many AWS resource classes have been changed to conform to API guidelines:
  • XxxRef abstract classes are now IXxx interfaces
  • XxxRefProps are now XxxImportProps
  • XxxRef.import(...) are now Xxx.import(...) accept XxxImportProps and return IXxx
  • export(): XxxImportProps is now defined in IXxx and implemented by imported resources