Add Automatic Monitoring to CDK Stacks with cdk-watchful (2026)

cdk-watchful turns your CDK deployment into a self-reporting system, alerting you when things go sideways after the deploy.

Here’s a simple Lambda function and API Gateway setup. We’ll add cdk-watchful to monitor it.

import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import { Construct } from 'constructs';
import { Watchful } from 'cdk-watchful'; // Import Watchful

export class MyCdkStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const api = new apigateway.RestApi(this, 'MyApi');

    const lambdaFn = new lambda.Function(this, 'MyLambda', {
      runtime: lambda.Runtime.NODEJS_18_X,
      handler: 'index.handler',
      code: lambda.Code.fromInline(`
        exports.handler = async (event) => {
          console.log('Received event:', JSON.stringify(event, null, 2));
          // Simulate a potential error
          if (Math.random() < 0.1) {
            throw new Error('Simulated random error!');
          }
          return {
            statusCode: 200,
            body: JSON.stringify({ message: 'Hello from Lambda!' }),
          };
        };
      `),
    });

    const integration = new apigateway.LambdaIntegration(lambdaFn);
    const resource = api.root.addResource('hello');
    resource.addMethod('GET', integration);

    // Instantiate Watchful and pass the stack
    new Watchful(this, 'Watchful', {
      stack: this,
    });
  }
}

const app = new cdk.App();
new MyCdkStack(app, 'MyCdkStack');

Deploy this with cdk deploy. After deployment, cdk-watchful automatically provisions CloudWatch Alarms and other resources tied to your stack’s components. It monitors things like Lambda function errors, API Gateway latency, and queue depths. When an alarm is breached, it sends a notification to a pre-configured SNS topic.

The core problem cdk-watchful solves is the "deploy and forget" anti-pattern. You build your infrastructure with CDK, but often, the critical part is knowing when it stops working in production. cdk-watchful bridges this gap by making your infrastructure observable and actionable right out of the box. It instruments your existing CDK constructs with monitoring without requiring you to manually create alarms, SNS topics, or subscriptions for every service.

Internally, cdk-watchful inspects the cdk.Stack you provide. It identifies common AWS resources like lambda.Function, apigateway.RestApi, sqs.Queue, etc. For each identified resource, it synthesizes the appropriate CloudWatch Alarms. For instance, a lambda.Function might get alarms for Errors and Duration. An apigateway.RestApi might get alarms for 5xxError and Latency. These alarms are then attached to an SNS topic, which you can configure to send notifications via email, Slack, or other integrations.

The Watchful construct itself is quite simple to use. You instantiate it within your stack and pass the stack object to its constructor. You can customize the alarms and notifications via props. For example, to change the SNS topic name or add specific metric thresholds:

new Watchful(this, 'Watchful', {
  stack: this,
  alarmSnsTopicName: 'my-custom-alerts-topic', // Specify a custom SNS topic name
  alarmFriendlyName: 'My Stack Alerts', // A friendly name for the alarms
  // You can also define custom alarm configurations for specific resources
  // For example, to set a custom threshold for Lambda duration:
  // lambdaFunctionAlarms: {
  //   MyLambda: {
  //     Duration: {
  //       threshold: 5000, // 5 seconds
  //       comparisonOperator: cdk.aws_cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
  //     },
  //   },
  // },
});

The cdk-watchful construct also provides a dashboard. After deployment, you can access a URL provided in the CloudFormation outputs that leads to a pre-built CloudWatch Dashboard summarizing the health of your stack’s resources, including the alarms it has created. This dashboard gives you a single pane of glass for your stack’s operational status.

A key aspect that often surprises people is how cdk-watchful handles existing resources. If you add cdk-watchful to a stack that’s already deployed, it will simply add the new monitoring resources (alarms, SNS topic, dashboard) to your stack. It doesn’t try to reconfigure or disrupt your running services. The alarms will start monitoring immediately, and you’ll begin receiving notifications if any predefined thresholds are breached. This makes it very easy to gradually add monitoring to existing infrastructure without a large-scale refactor.

The next logical step after setting up basic monitoring is to explore advanced alerting strategies and custom metrics.