cdk-watchful gives a CDK app a central dashboard and default alarms without hand-written CloudWatch

One construct, and the resources it watches

Watchful is an AWS CDK construct library that makes it easy to monitor CDK apps, and it automatically synthesises alarms and dashboards for supported AWS resources. The tagline is watching your CDK back since 2019, which is also the package description.

The usage is the shortest in the README.

declare const myTable: dynamodb.Table;
declare const myFunction: lambda.Function;
declare const myRestApi: apigw.RestApi;

const wf = new Watchful(this, 'watchful');
wf.watchDynamoTable('My Cute Little Table', myTable);
wf.watchLambdaFunction('My Function', myFunction);
wf.watchApiGateway('My REST API', myRestApi);

Three calls after one constructor. The library creates the alarms and a dashboard as part of the same CloudFormation synthesis as the resources themselves, which is the whole point: there is no second place where monitoring is configured and no dashboard to click together by hand.

The supported resources are listed explicitly. Amazon DynamoDB through `watchful.watchDynamoTable`, AWS Lambda through `watchful.watchLambdaFunction`, and Amazon API Gateway through `watchful.watchApiGateway`. Under that list the README says Request yours, linking to the issues page, which tells you the set is small and grows on request rather than covering the AWS catalogue.

The names are strings, which is the one design choice that reads oddly at first. A human-readable name per resource is what ends up as the widget title on the dashboard, so the label you pass is the label your on-call engineer will read at 3am.

Where the alarms go

The Watchful construct takes an options object, and the README is clear that you can initialise it with an email address, an SQS ARN or both.

import * as sns from 'aws-cdk-lib/aws-sns';
import * as sqs from 'aws-cdk-lib/aws-sqs';

const alarmSqs = sqs.Queue.fromQueueArn(this, 'AlarmQueue', 'arn:aws:sqs:us-east-1:444455556666:alarm-queue')
const alarmSns = sns.Topic.fromTopicArn(this, 'AlarmTopic', 'arn:aws:sns:us-east-2:444455556666:MyTopic');

const wf = new Watchful(this, 'watchful', {
  alarmEmail: '[email protected]',
  alarmSqs,
  alarmSns,
  alarmActionArns: [ 'arn:aws:sqs:us-east-1:444455556666:alarm-queue' ]
});

Four ways to be told: an email address, an SNS topic, an SQS queue, and a list of arbitrary alarm action ARNs.

The use of `fromQueueArn` and `fromTopicArn` is what makes this composable with an existing stack. Those are the CDK import functions, which produce a reference to a resource that already exists elsewhere, so you are not forced to have Watchful own the queue or the topic. The `alarmActionArns` list is the escape hatch for anything else, and it takes plain strings, so a Slack webhook, a PagerDuty integration or an Opsgenie endpoint all go through the same door.

Putting a queue in the path is the more interesting choice for a real deployment, since it gives you a durable record of every alarm rather than an email that nobody reads.

Watching a whole scope instead of listing resources

The feature that separates this from a per-resource helper is scope watching.

Watchful can watch complete CDK construct scopes. It automatically discovers all watchable resources within that scope recursively, adds them to the dashboard and configures alarms for them.

declare const storageLayer: Stack;
declare const wf: Watchful;

wf.watchScope(storageLayer);

That one call covers a stack of resources, and it is recursive, so nested constructs are included. For a CDK codebase with many stacks and a convention of grouping resources into layers, this removes the maintenance burden that per-resource calls create, where every new table has to be remembered and wired in by hand.

The trade is that scope discovery only finds resources of the types Watchful knows how to watch. A new resource type in a scope you watch is silently not monitored, whereas an explicit `watchDynamoTable` call cannot be forgotten.

So the practical rule is that scope watching is right when your resources follow the supported set closely, and explicit calls are right at the edges where you want to be sure something is covered. The README's example directory has a more complete version of this at example/index.ts, and the repository also carries a rosetta/ directory and an API.md, which is the API reference generated as part of the build.

A projen project, and the yarn commands that build it

The repository is a projen project, and that is visible in the package.json, where every script is a thin wrapper around the projen CLI: build, compile, test, integ, release, bump, docgen, compat, clobber and the rest all run `npx projen` with a subcommand.

The practical consequence is that the build is not hand-written. The.projen/ directory and.projenrc.ts hold the project definition, and the generated files at the root, the eslint config, the tsconfig files and the GitHub workflows, come from that definition.

For a contributor, the README gives three steps. Clone the repo, run `yarn`, and then work in the development workflow, which runs the tests automatically as you change code.

yarn test:watch

The build, which is what CI runs, is the second command.

yarn build

And then you publish as a pull request.

The scripts list shows the breadth of what projen manages here. There are integration tests with the AWS CDK integ runner and the integ-tests-alpha package, and separate package targets for dotnet, go, java, js and python, which is the jsii cross-language packaging that CDK libraries use to expose the same construct to several languages. The scripts list also includes `rosetta:extract`, backed by the rosetta/ directory at the repository root.

The author field in package.json lists Amazon Web Services with the aws-cdk-dev address, and the licence is Apache 2.0 with the LICENSE file at the root.

The successor, and the gap between the tags and the commits

The first thing in the README is a pointer to a different project, and it is the most important thing to know before evaluating this library.

The README asks whether you have heard of cdk-monitoring-constructs, describes it as Watchful on steroids, and points at the repository. That is the maintainer's own recommendation to use the newer library.

The reason is not subtle. cdk-monitoring-constructs is the broader monitoring construct library for AWS CDK, while cdk-watchful handles a small set of resource types with defaults. The same README keeps a fuller task list for cdk-watchful with a request yours link, which reads as a maintenance note rather than a feature roadmap.

The version history shows the same story. The listed releases are v0.6.458 from 2023-11-16, v0.6.457 from 2023-07-05 and v0.6.456 from 2023-07-04. So the highest version number is in the hundreds, but the actual tags stopped in November 2023, while the last push to the repository was on 2026-10-19.

That means the repository is still receiving work even though the release tags are old. Projen projects typically publish on release rather than on every commit, so an actively touched repository with stale tags is normal here. The question for an adopter is whether the version you get from npm is the version in the tree, and for that the CHANGELOG and the release workflow are the places to look.

The links inside the README point at the eladb/cdk-watchful repository, while the project now sits under the cdklabs organisation.

Where cdk-watchful is the wrong choice

Four cases argue against it.

The first is a new project. The README describes cdk-monitoring-constructs as Watchful on steroids. Choosing cdk-watchful for new work means choosing the narrower library when the maintainers themselves point at the wider one.

The second is a monitoring requirement beyond defaults. cdk-watchful configures default alarming. If you need custom metric math, composite alarms, anomaly detection or thresholds tuned per workload, you are writing CloudWatch alarms yourself and using this only for the dashboard.

The third is resources outside the supported set. DynamoDB, Lambda and API Gateway are the listed types. An ECS service, an SQS queue or an RDS instance in your stack is not watched by default, and a scope watch will skip it.

The alternative in the same direction is cdk-monitoring-constructs, which the README calls Watchful on steroids. A third option is writing the alarms and a dashboard by hand in the same stack, which is more code but gives complete control over thresholds and actions, and which is worth doing when the alerting policy is the thing under review rather than the plumbing.

Editorial conclusion

cdk-watchful fits a CDK user who wants default alarming and a dashboard defined in the same stack as the resources, and who wants scope-wide discovery rather than per-resource wiring. It does not fit a new project, because the README points at cdk-monitoring-constructs as the more capable version of the same idea and the last tagged release here is v0.6.458 from 2023-11-16. If you start new work, use cdk-monitoring-constructs; if you maintain an existing cdk-watchful stack, keep the construct but plan around the projen-based build and the narrow set of supported resource types.

Frequently asked questions

Official sources

1. cdklabs/cdk-watchful on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases