Product
Introducing Ruby Support in Socket
Socket is launching Ruby support for all users. Enhance your Rails projects with AI-powered security scans for vulnerabilities and supply chain threats. Now in Beta!
@aws-cdk/aws-cloudwatch
Advanced tools
@aws-cdk/aws-cloudwatch is an AWS CDK library that allows you to define and manage Amazon CloudWatch resources using code. It provides a high-level, object-oriented abstraction to create and manage CloudWatch Alarms, Dashboards, Metrics, and more.
Creating CloudWatch Alarms
This code sample demonstrates how to create a CloudWatch Alarm that monitors the CPU utilization of an EC2 instance. The alarm triggers if the CPU utilization exceeds 80% for three consecutive evaluation periods.
const cloudwatch = require('@aws-cdk/aws-cloudwatch');
const cdk = require('@aws-cdk/core');
const app = new cdk.App();
const stack = new cdk.Stack(app, 'MyStack');
const alarm = new cloudwatch.Alarm(stack, 'MyAlarm', {
metric: new cloudwatch.Metric({
namespace: 'AWS/EC2',
metricName: 'CPUUtilization',
dimensions: { InstanceId: 'i-1234567890abcdef0' },
}),
threshold: 80,
evaluationPeriods: 3,
comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
});
app.synth();
Creating CloudWatch Dashboards
This code sample demonstrates how to create a CloudWatch Dashboard and add a graph widget to it. The graph widget displays the CPU utilization of an EC2 instance.
const cloudwatch = require('@aws-cdk/aws-cloudwatch');
const cdk = require('@aws-cdk/core');
const app = new cdk.App();
const stack = new cdk.Stack(app, 'MyStack');
const dashboard = new cloudwatch.Dashboard(stack, 'MyDashboard', {
dashboardName: 'MyDashboard',
});
dashboard.addWidgets(new cloudwatch.GraphWidget({
title: 'EC2 CPU Utilization',
left: [new cloudwatch.Metric({
namespace: 'AWS/EC2',
metricName: 'CPUUtilization',
dimensions: { InstanceId: 'i-1234567890abcdef0' },
})],
}));
app.synth();
Creating Custom Metrics
This code sample demonstrates how to create a custom CloudWatch metric and set up an alarm for it. The custom metric is defined with a specific namespace and dimensions.
const cloudwatch = require('@aws-cdk/aws-cloudwatch');
const cdk = require('@aws-cdk/core');
const app = new cdk.App();
const stack = new cdk.Stack(app, 'MyStack');
const customMetric = new cloudwatch.Metric({
namespace: 'MyNamespace',
metricName: 'MyCustomMetric',
dimensions: { MyDimension: 'MyValue' },
});
const alarm = new cloudwatch.Alarm(stack, 'MyCustomMetricAlarm', {
metric: customMetric,
threshold: 100,
evaluationPeriods: 1,
comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
});
app.synth();
The aws-sdk package is the official AWS SDK for JavaScript. It provides low-level access to AWS services, including CloudWatch. While it offers more granular control, it lacks the high-level abstractions provided by @aws-cdk/aws-cloudwatch, making it more complex to use for defining and managing CloudWatch resources.
The cloudwatch-metrics package is a lightweight library for publishing custom metrics to Amazon CloudWatch. It is simpler and more focused compared to @aws-cdk/aws-cloudwatch, but it does not provide the comprehensive resource management capabilities that the CDK library offers.
The serverless-plugin-cloudwatch package is a Serverless Framework plugin that allows you to define CloudWatch Alarms and Dashboards in your serverless.yml configuration file. It is tailored for use with the Serverless Framework and offers a more integrated experience for serverless applications, but it is less flexible and powerful compared to the @aws-cdk/aws-cloudwatch library.
This is a developer preview (public beta) module. Releases might lack important features and might have future breaking changes.
This API is still under active development and subject to non-backward compatible changes or removal in any future version. Use of the API is not recommended in production environments. Experimental APIs are not subject to the Semantic Versioning model.
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();
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 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 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 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.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"
})]
}));
An alarm widget shows the graph and the alarm line of a single alarm:
dashboard.add(new AlarmWidget({
title: "Errors",
alarm: errorAlarm,
}));
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],
}));
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'
}));
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 space0.35.0 (2019-06-19)
cdk context
(#2870) (b8a1c8e), closes #2854name
in StageProps
to stageName
. (#2882) (be574a1)hwType
to hardwareType
(#2916) (1aa0589), closes #2896aws-sns-subscribers
(#2804) (9ef899c)AssetProps.packaging
has been removed and is now automatically discovered based on the file type.ZipDirectoryAsset
has been removed, use aws-s3-assets.Asset
.FileAsset
has been removed, use aws-s3-assets.Asset
.Code.directory
and Code.file
have been removed. Use Code.asset
.hardwareType
from hwType
.TableOptions.pitrEnabled
renamed to pointInTimeRecovery
.TableOptions.sseEnabled
renamed to serverSideEncryption
.TableOptions.ttlAttributeName
renamed to timeToLiveAttribute
.TableOptions.streamSpecification
renamed stream
.ContainerImage.fromAsset()
now takes only build directory
directly (no need to pass scope
or id
anymore).ISecret.secretJsonValue
renamed to secretValueFromJson
.ParameterStoreString
has been removed. Use StringParameter.fromStringParameterAttributes
.ParameterStoreSecureString
has been removed. Use StringParameter.fromSecureStringParameterAttributes
.ParameterOptions.name
was renamed to parameterName
.newStream
renamed to addStream
and doesn't need a scopenewSubscriptionFilter
renamed to addSubscriptionFilter
and doesn't need a scopenewMetricFilter
renamed to addMetricFilter
and doesn't need a scopeNewSubscriptionFilterProps
renamed to SubscriptionProps
NewLogStreamProps
renamed to LogStreamOptions
NewMetricFilterProps
renamed to MetricFilterOptions
JSONPattern
renamed to JsonPattern
MethodOptions.authorizerId
is now called authorizer
and accepts an IAuthorizer
which is a placeholder interface for the authorizer resource.restapi.executeApiArn
renamed to arnForExecuteApi
.restapi.latestDeployment
and deploymentStage
are now read-only.EventPattern.detail
is now a map.scheduleExpression: string
is now schedule: Schedule
.cdk.RemovalPolicy
to configure the resource's removal policy.applyRemovalPolicy
is now CfnResource.applyRemovalPolicy
.RemovalPolicy.Orphan
has been renamed to Retain
.RemovalPolicy.Forbid
has been removed, use Retain
.RepositoryProps.retain
is now removalPolicy
, and defaults to Retain
instead of remove since ECR is a stateful resourceKeyProps.retain
is now removalPolicy
LogGroupProps.retainLogGroup
is now removalPolicy
LogStreamProps.retainLogStream
is now removalPolicy
DatabaseClusterProps.deleteReplacePolicy
is now removalPolicy
DatabaseInstanceNewProps.deleteReplacePolicy
is now removalPolicy
attr
instead of the resource type. For example, in S3 bucket.bucketArn
is now bucket.attrArn
.propertyOverrides
has been removed from all "Cfn" resources, instead
users can now read/write resource properties directly on the resource class. For example, instead of lambda.propertyOverrides.runtime
just use lambda.runtime
.stageName
instead of name
Function.addLayer
to addLayers
and made it variadicIFunction.handler
propertyIVersion.versionArn
property (the value is at functionArn
)SingletonLayerVersion
LogRetention
PolicyStatement
no longer has a fluid API, and accepts a
props object to be able to set the important fields.ImportedResourcePrincipal
to UnknownPrincipal
.managedPolicyArns
renamed to managedPolicies
, takes
return value from ManagedPolicy.fromAwsManagedPolicyName()
.PolicyDocument.postProcess()
is now removed.PolicyDocument.addStatement()
renamed to addStatements
.PolicyStatement
is no longer IResolvable
, call .toStatementJson()
to retrieve the IAM policy statement JSON.AwsPrincipal
has been removed, use ArnPrincipal
instead.s3.StorageClass
is now an enum-like class instead of a regular
enum. This means that you need to call .value
in order to obtain it's value.s3.Coordinates
renamed to s3.Location
Artifact.s3Coordinates
renamed to Artifact.s3Location
.BuildSpec
object.lambda.Runtime.NodeJS*
are now lambda.Runtime.Nodejs*
Stack
APIstack.name
renamed to stack.stackName
stack.stackName
will return the concrete stack name. Use Aws.stackName
to indicate { Ref: "AWS::StackName" }.stack.account
and stack.region
will return the concrete account/region only if they are explicitly specified when the stack is defined (under the env
prop). Otherwise, they will return a token that resolves to the AWS::AccountId and AWS::Region intrinsic references. Use Context.getDefaultAccount()
and Context.getDefaultRegion()
to obtain the defaults passed through the toolkit in case those are needed. Use Token.isUnresolved(v)
to check if you have a concrete or intrinsic.stack.logicalId
has been removed. Use stack.getLogicalId()
stack.env
has been removed, use stack.account
, stack.region
and stack.environment
insteadstack.accountId
renamed to stack.account
(to allow treating account more abstractly)AvailabilityZoneProvider
can now be accessed through Context.getAvailabilityZones()
SSMParameterProvider
can now be accessed through Context.getSsmParameter()
parseArn
is now Arn.parse
arnFromComponents
is now arn.format
node.lock
and node.unlock
are now privatestack.requireRegion
and requireAccountId
have been removed. Use Token.unresolved(stack.region)
insteadstack.parentApp
have been removed. Use App.isApp(stack.node.root)
instead.stack.missingContext
is now privatestack.renameLogical
have been renamed to stack.renameLogicalId
IAddressingScheme
, HashedAddressingScheme
and LogicalIDs
are now internal. Override Stack.allocateLogicalId
to customize how logical IDs are allocated to resources.--rename
, and the stack
names are now immutable on the stack artifact.@aws-cdk/aws-sns-subscribers
package.roleName
in RoleProps
is now of type PhysicalName
bucketName
in BucketProps
is now of type PhysicalName
roleName
in RoleProps
is now of type PhysicalName
FAQs
The CDK Construct Library for AWS::CloudWatch
The npm package @aws-cdk/aws-cloudwatch receives a total of 87,835 weekly downloads. As such, @aws-cdk/aws-cloudwatch popularity was classified as popular.
We found that @aws-cdk/aws-cloudwatch demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket is launching Ruby support for all users. Enhance your Rails projects with AI-powered security scans for vulnerabilities and supply chain threats. Now in Beta!
Product
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Product
We're launching a new set of license analysis and compliance features for analyzing, managing, and complying with licenses across a range of supported languages and ecosystems.