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

[topra-aws]

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

• 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.

[topra-aws]

^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