Repository navigation
[cloudwatch] Support alarm warm-up for single-series alarms #38743
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: DurationonlyStartEvaluatingAfterWarmupPeriodEnds?: 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
- 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.
Activity
topra-aws commentedon Sep 2, 2026
^Note the entire attached PR is written via AI as I'm not very familiar with typescript. It looked correct as it is just a property on metric and log alarms (no support for composite). I will also update it to remove the promQL support as for promQL we expect to use the pending period to keep it in line with normal prometheus alerts. Also once log alarms construct is written, support should be extended to it as well
[-][cloudwatch] Support alarm warm-up configuration in L2 alarms[/-][+][cloudwatch] Support alarm warm-up configuration for single metrics[/+][-][cloudwatch] Support alarm warm-up configuration for single metrics[/-][+][cloudwatch] Support alarm warm-up for single-series alarms[/+]pahud commentedon Sep 4, 2026
Thanks for the well-scoped request — and for already opening #38744. This is a valid feature request; I confirmed
CfnAlarm.warmUpConfiguration(withWarmUpConfigurationProperty) is present in the shippedaws-cdk-lib2.268.0 generated L1, so the L2 gap is real.Until the PR lands, you (and anyone else finding this issue) can set the property today without raw escape hatches using the CfnAlarmPropsMixin from
@aws-cdk/cfn-property-mixins:On the proposal itself: in my opinion the scoping is sound — single-series alarms only, 1–2880 whole-minute validation with unresolved-token passthrough, rejecting top-level
GROUP BYMetrics Insights queries, and your follow-up decision to exclude PromQL (pending period being the Prometheus-native equivalent) all make sense. The note about extending to a future log-alarm L2 is a good call too; for what it's worth, the mixin package already ships aCfnLogAlarmPropsMixinwith the same property.Since #38744 is already in review, the discussion can continue there. Thanks for contributing!
pahud commentedon Sep 21, 2026
Until this lands as a first-class L2 prop, the CDK Mixins mechanism (GA in
aws-cdk-lib) gives a clean, reusable way to setWarmUpConfigurationtoday — the property is already available on the L1CfnAlarm.Verified with
aws-cdk-lib@2.270.0(compiles under strict TS, synthesizes, and the property appears on theAWS::CloudWatch::Alarmresource):Synthesized output on the alarm:
Because the mixin targets the L1, it also works when applied to a whole scope (e.g.
Mixins.of(stack).apply(...)to warm up every alarm in a stack).requireAny()makes synth fail if nothing matched, so you don't silently no-op.Let me know if it works.
github-actions commentedon Sep 23, 2026
This issue has not received a response in a while. If you want to keep this issue open, please leave a comment below and auto-close will be canceled.