aws / aws/aws-cdk

[cloudwatch] Support alarm warm-up for single-series alarms

Open
#38,743 2 comments 0 reactions 0 assignees View on GitHub
@aws-cdk/aws-cloudwatch effort/medium feature-request p2
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
2d 3h
Merged PRs (30d)
83

Description

### Describe the feature

Expose the CloudFormation `AWS::CloudWatch::Alarm` `WarmUpConfiguration` property through CloudWatch alarm L2 APIs that evaluate one time series.

The API should allow callers to configure a warm-up duration and optionally require the complete warm-up period to elapse before evaluation starts.

Supported alarm inputs include plain metrics, ordinary single-output metric math, Metrics Insights queries that produce or are collapsed to one time series, and anomaly detection. PromQL and direct multi-time-series Metrics Insights contributor alarms are intentionally excluded.

### Use Case

New or updated resources can take time to begin publishing enough metric data for meaningful alarm evaluation. Without warm-up configuration, alarms can create noise during startup or deployment. CDK users currently need to reach through to the L1 construct to configure this CloudFormation capability.

Providing an L2 option keeps supported alarm configuration strongly typed while preventing unsupported contributor-alarm combinations.

### Proposed Solution

Add a shared `AlarmWarmupConfiguration` struct with:

- `warmupPeriod: Duration`
- `onlyStartEvaluatingAfterWarmupPeriodEnds?: boolean`

Expose it through `Alarm`, `AnomalyDetectionAlarm`, `Metric.createAlarm`, and `MathExpression.createAlarm`. Map it to the generated L1 property and validate CloudFormation's supported range of 1–2880 whole minutes while allowing unresolved duration tokens.

Reject a direct top-level Metrics Insights query containing `SELECT ... GROUP BY`. Allow grouped queries wrapped by outer metric math that collapses them to one time series. Do not expose the option on `PromQLAlarmProps`.

### Other Information

CloudFormation reference: https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-cloudwatch-alarm-warmupconfiguration.html

The change is backward compatible because omitting the option preserves the current synthesized template.

### Acknowledgements

- [x] I may be able to implement this feature request
- [ ] This feature might incur a breaking change

### AWS CDK Library version (aws-cdk-lib)

`main` development checkout (`0.0.0`)

### AWS CDK CLI version

Repository development dependency (`2.1131.0`)

### Environment details

Linux; validated with Node.js 20.20.2 in the repository development environment.

Contributor guide

Open the contributing guide

Research direction

Start with the Alarm, AnomalyDetectionAlarm, Metric.createAlarm, and MathExpression.createAlarm entry points named in the proposal, then trace how they map configuration to the generated L1 property. Check the CloudFormation WarmUpConfiguration constraints and the supported Metrics Insights cases before implementing validation. Done means supported single-series alarms synthesize the property correctly while PromQL and direct contributor alarms reject it, with omitted configuration preserving existing output.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, typescript
Domain
cloud, observability-sre
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.