CDK Lambda Monitoring Patterns with Alarms and Dashboards: A Complete Implementation Guide

The Agent Toolkit for AWS provides a production-ready CDK helper that implements best-practice CloudWatch monitoring for Lambda functions, including error-rate math expressions, p99 duration alarms, and composite health alarms with a pre-built dashboard.

The aws/agent-toolkit-for-aws repository delivers a robust observability solution that eliminates common monitoring anti-patterns. The createLambdaMonitoring function in alarm-template.ts constructs a comprehensive monitoring stack using AWS CDK constructs, implementing intelligent alarm configurations that reduce false positives while ensuring genuine service degradation is captured immediately.

The Complete Monitoring Architecture

The monitoring implementation in plugins/aws-core/skills/aws-observability/assets/alarm-template.ts creates five distinct observability components that work together to provide comprehensive Lambda function visibility.

Error-Rate Alarm with MathExpression

Instead of monitoring raw error counts, the helper creates a CloudWatch MathExpression that calculates the actual error percentage: errors * 100 / invocations. This approach prevents false positives during low-traffic periods when a single error might represent 100% of invocations.

The alarm configuration uses:

• 1-minute period for rapid detection
• 3 evaluation periods with 2 datapoints-to-alarm
• NOT_BREACHING treatment for missing data
• Default threshold of 5% (configurable via errorRateThreshold)

Duration Alarm for p99 Latency

Rather than averaging latency across all invocations, the stack monitors the p99 duration metric. This ensures you catch slow responses affecting your worst-performing percentiles, not just statistical averages that might mask performance issues.

The duration alarm shares the same evaluation settings as the error-rate alarm, with a default threshold of 3000 milliseconds (configurable via durationThresholdMs).

Throttle Detection

The throttle alarm triggers when throttles exceed 1 within a one-minute period. This catches Lambda concurrency limit issues immediately, as throttled requests represent immediate customer impact.

Composite Alarm for Service Health

All individual alarms feed into a CompositeAlarm named ServiceHealthAlarm. This pattern aggregates multiple failure signals into a single operational health indicator, ensuring downstream incident-response pipelines and paging systems only react when genuine service degradation occurs, not transient individual metric spikes.

Pre-Configured CloudWatch Dashboard

The implementation generates a CloudWatch Dashboard containing:

• Text widgets with service context
• AlarmWidget instances displaying current alarm states
• Graphs plotting invocations versus errors over time
• PeriodOverride.INHERIT and an 8-hour default time range

This dashboard provides operators with immediate visibility into service health following deployments.

Implementation Reference

The core function signature demonstrates the configurable interface:

export function createLambdaMonitoring(
  scope: Construct,
  fn: IFunction,
  snsTopic: ITopic,
  options?: {
    errorRateThreshold?: number;   // default 5%
    durationThresholdMs?: number; // default 3000ms
  },
)

All alarms automatically wire to the provided SNS topic for notifications. The implementation deliberately avoids common CDK defaults—such as single evaluation periods or MISSING data treatment—to minimize alarm fatigue while maintaining sensitivity to real issues.

Practical Usage Examples

Adding Monitoring to a Lambda Function

import * as cdk from 'aws-cdk-lib';
import { Function, Runtime, Code } from 'aws-cdk-lib/aws-lambda';
import { Topic } from 'aws-cdk-lib/aws-sns';
import { createLambdaMonitoring } from 'aws-observability/assets/alarm-template';

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

    const fn = new Function(this, 'MyFunction', {
      runtime: Runtime.NODEJS_18_X,
      handler: 'index.handler',
      code: Code.fromAsset('lambda'),
    });

    const topic = new Topic(this, 'AlarmTopic');

    const monitors = createLambdaMonitoring(this, fn, topic, {
      errorRateThreshold: 4,
      durationThresholdMs: 2500,
    });

    new cdk.CfnOutput(this, 'ErrorRateAlarmArn', {
      value: monitors.errorRateAlarm.alarmArn,
    });
  }
}

Accessing the Generated Dashboard

import { Dashboard } from 'aws-cdk-lib/aws-cloudwatch';

const dashboard = monitors.dashboard;

new cdk.CfnOutput(this, 'DashboardUrl', {
  value: dashboard.dashboardArn,
});

Summary

• MathExpression-based error rates prevent false positives during low-traffic periods by calculating percentages rather than monitoring raw counts.
• CompositeAlarm aggregation ensures paging systems only trigger during genuine service degradation, not individual metric anomalies.
• p99 duration monitoring captures worst-case latency rather than hiding issues in averages.
• NOT_BREACHING configuration for missing data eliminates noise from idle functions.
• Pre-built dashboard provides immediate operational visibility with an 8-hour time window and alarm status widgets.

Frequently Asked Questions

Why does the error-rate alarm use a MathExpression instead of the Errors metric directly?

Using a MathExpression that calculates errors * 100 / invocations provides a percentage-based threshold that scales with traffic volume. According to the implementation in alarm-template.ts, this prevents scenarios where a single error during low-traffic periods would trigger a 100% error rate alarm, while ensuring high-traffic functions maintain appropriate sensitivity to actual degradation.

What is the purpose of the CompositeAlarm in this monitoring pattern?

The CompositeAlarm named ServiceHealthAlarm aggregates the error-rate, duration, and throttle alarms into a single operational health indicator. This pattern ensures that incident response workflows and on-call paging only trigger when multiple failure signals confirm genuine service issues, reducing alert fatigue from transient individual metric spikes.

How does the monitoring handle missing data points?

The implementation configures all alarms with treatMissingData: NOT_BREACHING. This setting prevents alarms from triggering when Lambda functions experience no traffic or gaps in metric data, which is common for sporadically invoked functions. This approach follows the production guidance embedded in the aws-core plugin observability assets.

Where can I examine the source implementation of these CDK patterns?

The complete implementation resides in plugins/aws-core/skills/aws-observability/assets/alarm-template.ts within the aws/agent-toolkit-for-aws repository. A duplicate reference exists in skills/core-skills/aws-observability/assets/alarm-template.ts for the core-skills package, both implementing identical logic for the createLambdaMonitoring function and its associated CloudWatch constructs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}