[cloudwatch] Support alarm warm-up for single-series alarms
- 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
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