cloudwatch: AnomalyDetectionAlarm metric period is not applied properly

[holomekc]

Describe the bug

It seems with 2.198.0 AnomalyDetectionAlarm was introduced. In the past we used the normal Alarm and adjusted then the CfnAlarm via escape hatches. So we tried to update to the AnomalyDetectionAlarm construct. Sadly we receive some warnings:
[Warning at /.../.../...] Periods of metrics in 'usingMetrics' for Math expression 'ANOMALY_DETECTION_BAND(m0, 2)' have been overridden to 300 seconds. [ack: CloudWatch:Math:MetricsPeriodsOverridden]

This happens although the userd Metric itself has the period of 60s defined. The only way to get rid of this was to set the period directly on the AnomalyDetectionAlarm. This method is deprecated though with the information to use the period of the used Metric.

What is the intended way to solve this issue?

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Library Version

No response

Expected Behavior

The period of the metric is used for the math expression period

Current Behavior

Currently the period of the metric is not used and the construct falls back to the default of 5m period.

Reproduction Steps

Define a AnomalyDetectionAlarm as in the documentation:

 // Create a metric
 Metric metric = Metric.Builder.create()
         .namespace("AWS/EC2")
         .metricName("CPUUtilization")
         .statistic("Average")
         .period(Duration.minutes(5))
         .build();
 // Create an anomaly detection alarm
 AnomalyDetectionAlarm alarm = AnomalyDetectionAlarm.Builder.create(this, "AnomalyAlarm")
         .metric(metric)
         .evaluationPeriods(1)
         // Number of standard deviations for the band (default: 2)
         .stdDevs(2)
         // Alarm outside on either side of the band, or just below or above it (default: outside)
         .comparisonOperator(ComparisonOperator.LESS_THAN_LOWER_OR_GREATER_THAN_UPPER_THRESHOLD)
         .alarmDescription("Alarm when metric is outside the expected band")
         .build();

Possible Solution

No response

Additional Information/Context

No response

AWS CDK Library version (aws-cdk-lib)

2.199.0

AWS CDK CLI version

2.1017.1

Node.js Version

22.x

OS

Mac OSX

Language

Java

Language Version

21

Other information

No response

[ykethan]

Hey @holomekc, thank you for reaching out. I was able to reproduce this behavior using the following.

    const metric = new Metric({
      namespace: 'AWS/EC2',
      metricName: 'CPUUtilization',
      statistic: 'Average',
      period: Duration.minutes(1), // always defaults 5 minutes
    });

    // Create an anomaly detection alarm
    const alarm = new AnomalyDetectionAlarm(this, 'AnomalyAlarm', {
      metric: metric,

      evaluationPeriods: 5,

      // Number of standard deviations for the band (default: 2)
      stdDevs: 2,
      // Alarm outside on either side of the band, or just below or above it (default: outside)
      comparisonOperator:
        ComparisonOperator.LESS_THAN_LOWER_OR_GREATER_THAN_UPPER_THRESHOLD,
      alarmDescription: 'Alarm when metric is outside the expected band',
    });

CloudFormation template:

  AnomalyAlarm4A93F8A2:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmDescription: Alarm when metric is outside the expected band
      ComparisonOperator: LessThanLowerOrGreaterThanUpperThreshold
      EvaluationPeriods: 5
      Metrics:
        - Expression: ANOMALY_DETECTION_BAND(m0, 2)
          Id: expr_1
          Label: Anomaly Detection Band
          ReturnData: true
        - Id: m0
          MetricStat:
            Metric:
              MetricName: CPUUtilization
              Namespace: AWS/EC2
            Period: 300 // always sets to 300
            Stat: Average
          ReturnData: true

From the CloudFormation documentation it does support 1, 5, 10, 20, 30, 60, or any multiple of 60.

Workarounds

1. Create MathExpression Manually

import { MathExpression } from 'aws-cdk-lib/aws-cloudwatch';

// Create metric with desired period
const metric = new Metric({
  namespace: 'AWS/EC2',
  metricName: 'CPUUtilization',
  statistic: 'Average',
  period: Duration.minutes(1), // Your desired period
});

// Manually create the anomaly detection math expression with period
const anomalyExpression = new MathExpression({
  expression: 'ANOMALY_DETECTION_BAND(m0, 2)',
  usingMetrics: { m0: metric },
  period: Duration.minutes(1), // Set period 
  label: 'Anomaly Detection Band',
});

// Create alarm using the math expression
const alarm = new Alarm(this, 'AnomalyAlarm', {
  metric: anomalyExpression,
  comparisonOperator: ComparisonOperator.LESS_THAN_LOWER_OR_GREATER_THAN_UPPER_THRESHOLD,
  evaluationPeriods: 1,
  threshold: 0,
  alarmDescription: 'Alarm when metric is outside the expected band',
});

2. Use Metric.anomalyDetectionFor() with Period

// Create metric
const metric = new Metric({
  namespace: 'AWS/EC2',
  metricName: 'CPUUtilization',
  statistic: 'Average',
  period: Duration.minutes(1),
});

// Create anomaly detection metric with explicit period
const anomalyMetric = Metric.anomalyDetectionFor({
  metric: metric,
  stdDevs: 2,
  period: Duration.minutes(1), // Specify period here
});

// Create alarm
const alarm = new Alarm(this, 'AnomalyAlarm', {
  metric: anomalyMetric,
  comparisonOperator: ComparisonOperator.LESS_THAN_LOWER_OR_GREATER_THAN_UPPER_THRESHOLD,
  evaluationPeriods: 1,
  threshold: 0,
  alarmDescription: 'Alarm when metric is outside the expected band',
});

additionally, as you have provided CfnAlarm should also serve as a workaround.

Initial Analysis

From the packages/aws-cdk-lib/aws-cloudwatch/lib/alarm.ts file the issue appears to be due to period prop being undefined when the anomalyDetectionFor is called.

metric: Metric.anomalyDetectionFor(props), // props.period is undefined

in packages/aws-cdk-lib/aws-cloudwatch/lib/metric.ts the anomalyDetectionFor method:

return new MathExpression({
  expression: `ANOMALY_DETECTION_BAND(m0, ${props.stdDevs ?? 2})`,
  usingMetrics: { m0: props.metric },
  period: props.period, // undefined → defaults to 5 minutes
});

but would require further investigation to confirm this analysis. Marking as P2 bug.

[related-issues-bot-for-aws]

Hi @holomekc,

Thanks for reporting! This appears to be a duplicate issue. If you feel this is a distinct issue, please let us know in the comments. Otherwise, we'll close this ticket in 7 days and encourage you to follow the conversation threads in the potential duplicates listed below ranked by engagement.

Potential Duplicate Issues

• CloudWatch: Math expression in alarm doesn't respect period #32221: Both issues report the same problem where math expressions in CloudWatch alarms don't respect metric periods. The current issue shows AnomalyDetectionAlarm ignoring the 60-second period set on the metric and defaulting to 300 seconds (5 minutes), while issue CloudWatch: Math expression in alarm doesn't respect period #32221 describes MathExpressions in alarms not respecting the period setting. Both generate similar warnings about period overrides, affect the same CloudWatch module, and would require the same fix to ensure the period is properly propagated from metrics to math expressions in CloudFormation templates.

This message was generated automatically to help connect related conversations and improve discoverability.

Please react with 👍 or 👎 to let us know if this response was helpful!

Thank you for helping improve CDK! 🙌

Related Issues

• [aws-cloudwatch] The period of a MathExpression is not respected on CloudWatch #9156
• (aws-cloudwatch): Unable to define an alarm based on anomaly detection #19286
• MathExpression in Cloudwatch graphs are fixed to a 5min period #7153
• CloudWatch CfnAlarm does not see Period attribute value #6562
• CloudWatch: Math expression in alarm doesn't respect period #32221

[github-actions]

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.