How can I use the AWS CLI to create a CloudWatch alarm based on anomaly detection?

3 minute read

I want to use the AWS Command Line Interface (AWS CLI) to create an Amazon CloudWatch alarm that’s based on anomaly detection.

Short description

When you activate anomaly detection for a metric, CloudWatch applies machine-learning algorithms to the metric's historical data. CloudWatch uses this data to create a model of the metric's expected values and generates two metrics:

  • The upper band of normal metric behavior
  • The lower band of normal metric behavior, with a default value of two standard deviations

For more information, see How CloudWatch anomaly detection works.


Note: If you receive errors when running AWS CLI commands, make sure that you're using the most recent AWS CLI version.

Method 1

1.    Create a JSON file to set a CloudWatch alarm based on anomaly detection:

  "AlarmActions": [
  "AlarmName": "EC2_NetworkIn_Anomaly_Alarm",
  "AlarmDescription": "Trigger when EC2 NetworkIn is outside normal traffic volume",
  "Metrics": [
      "Id": "m1",
      "ReturnData": true,
      "MetricStat": {
        "Metric": {
          "MetricName": "NetworkIn",
          "Namespace": "AWS/EC2",
          "Dimensions": [
              "Name": "InstanceId",
              "Value": "i-024de5ace7c560660"
        "Stat": "Average",
        "Period": 300
      "Id": "t1",
      "Expression": "ANOMALY_DETECTION_BAND(m1, 2)"
  "EvaluationPeriods": 2,
  "ThresholdMetricId": "t1",
  "ComparisonOperator": "LessThanLowerOrGreaterThanUpperThreshold"


  • The Id of m1 is assigned to the NetworkIn metric of an instance. t1 is the anomaly detection model function for the NetworkIn metric. The model uses three standard deviations to set the width of the band.
  • ThresholdMetricId is set to t1, and ComparisonOperator is set to LessThanLowerOrGreaterThanUpperThreshold. When the metric value is outside the anomaly model band in either direction for two consecutive evaluation periods, these settings start the alarm state.

2.    Save the JSON file as anomaly-alarm.json.

3.    To create an alarm with the anomaly detection band specified in the file, run the following command:

$ aws cloudwatch put-metric-alarm --cli-input-json file://anomaly-alarm.json

Method 2

You can also issue the AWS CLI command without the JSON file:

aws cloudwatch put-metric-alarm \
--alarm-name "EC2_NetworkIn_Anomaly_Alarm" \
--alarm-description "Trigger when EC2 NetworkIn is outside normal traffic volume" \
--alarm-actions arn:aws:sns:us-east-1:123456789012:CW-Alarm-Notification \
--comparison-operator LessThanLowerOrGreaterThanUpperThreshold \
--evaluation-periods 2 \
--threshold-metric-id t1 \
--metrics "[{\"Id\":\"m1\",\"ReturnData\":true,\"MetricStat\":{\"Metric\":{\"Namespace\":\"AWS\/EC2\",\"MetricName\":\"NetworkIn\",\"Dimensions\":[{\"Name\":\"InstanceId\",\"Value\":\"i-024de5ace7c560660\"}]},\"Stat\":\"Average\",\"Period\":300}},{\"Id\":\"t1\",\"Expression\":\"ANOMALY_DETECTION_BAND(m1,2)\"}]"

After you create the alarm, the model is generated. The band that you see in the graph initially is an approximation of the anomaly detection band. It might take up to 15 minutes for the anomaly detection band that the model generates to appear in the graph.

Related information

Create a CloudWatch alarm based on anomaly detection


AWS OFFICIALUpdated 6 months ago