Skip to content

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

Closed

Description

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

Activity

  1. topra-aws commented on Sep 2, 2026

    @topra-aws
    Author

    ^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

  2. changed the title [-][cloudwatch] Support alarm warm-up configuration in L2 alarms[/-] [+][cloudwatch] Support alarm warm-up configuration for single metrics[/+] on Sep 2, 2026
  3. changed the title [-][cloudwatch] Support alarm warm-up configuration for single metrics[/-] [+][cloudwatch] Support alarm warm-up for single-series alarms[/+] on Sep 2, 2026
  4. pahud commented on Sep 4, 2026

    @pahud
    Contributor

    Thanks for the well-scoped request — and for already opening #38744. This is a valid feature request; I confirmed CfnAlarm.warmUpConfiguration (with WarmUpConfigurationProperty) is present in the shipped aws-cdk-lib 2.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:

    import { CfnAlarmPropsMixin } from '@aws-cdk/cfn-property-mixins/lib/services/aws-cloudwatch';
    
    const alarm = metric.createAlarm(this, 'Alarm', { threshold: 1, evaluationPeriods: 3 });
    alarm.with(new CfnAlarmPropsMixin({
      warmUpConfiguration: {
        warmUpPeriodDurationInMinutes: 15,
        onlyStartEvaluatingAfterWarmUpPeriodEnds: true,
      },
    }));

    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 BY Metrics 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 a CfnLogAlarmPropsMixin with the same property.

    Since #38744 is already in review, the discussion can continue there. Thanks for contributing!

  5. added
    feature-requestA feature should be added or improved.
    effort/mediumMedium work item – several days of effort
    and removed
    needs-triageThis issue or PR still needs to be triaged.
    on Sep 4, 2026
  6. pahud commented on Sep 21, 2026

    @pahud
    Contributor

    Until this lands as a first-class L2 prop, the CDK Mixins mechanism (GA in aws-cdk-lib) gives a clean, reusable way to set WarmUpConfiguration today — the property is already available on the L1 CfnAlarm.

    Verified with aws-cdk-lib@2.270.0 (compiles under strict TS, synthesizes, and the property appears on the AWS::CloudWatch::Alarm resource):

    import { Mixin, Mixins } from 'aws-cdk-lib';
    import { IConstruct } from 'constructs';
    import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';
    
    class AlarmWarmUp extends Mixin {
      constructor(private readonly warmUp: cloudwatch.CfnAlarm.WarmUpConfigurationProperty) {
        super();
      }
      supports(construct: IConstruct): boolean {
        return cloudwatch.CfnAlarm.isCfnAlarm(construct);
      }
      applyTo(construct: IConstruct): void {
        if (!this.supports(construct)) return;
        (construct as cloudwatch.CfnAlarm).warmUpConfiguration = this.warmUp;
      }
    }
    
    const alarm = new cloudwatch.Alarm(this, 'Alarm', {
      metric: new cloudwatch.Metric({ namespace: 'MyApp', metricName: 'Errors' }),
      threshold: 1,
      evaluationPeriods: 3,
    });
    
    Mixins.of(alarm).requireAny().apply(new AlarmWarmUp({
      onlyStartEvaluatingAfterWarmUpPeriodEnds: true,
      warmUpPeriodDurationInMinutes: 15,
    }));

    Synthesized output on the alarm:

    "WarmUpConfiguration": {
      "OnlyStartEvaluatingAfterWarmUpPeriodEnds": true,
      "WarmUpPeriodDurationInMinutes": 15
    }

    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.

  7. added
    response-requestedWaiting on additional info and feedback. Will move to "closing-soon" in 7 days.
    on Sep 21, 2026
  8. github-actions commented on Sep 23, 2026

    @github-actions
    Contributor

    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.

  9. added
    closing-soonThis issue will automatically close in 4 days unless further comments are made.
    closed-for-stalenessThis issue was automatically closed because it hadn't received any attention in a while.
    and removed
    closing-soonThis issue will automatically close in 4 days unless further comments are made.
    on Sep 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    @aws-cdk/aws-cloudwatchRelated to Amazon CloudWatchclosed-for-stalenessThis issue was automatically closed because it hadn't received any attention in a while.effort/mediumMedium work item – several days of effortfeature-requestA feature should be added or improved.mixinsp2response-requestedWaiting on additional info and feedback. Will move to "closing-soon" in 7 days.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions