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

> Implement robust CDK Lambda monitoring with alarms and dashboards using the Agent Toolkit. Get best-practice CloudWatch alarms for errors, duration, and health with a pre-built dashboard.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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:

```typescript
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

```typescript
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

```typescript
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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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.