AWS::CloudWatch::Alarm - AWS CloudFormation
SyntaxPropertiesReturn valuesExamplesSee also

This is the new AWS CloudFormation Template Reference Guide. Please update your bookmarks and links. For help getting started with CloudFormation, see the AWS CloudFormation User Guide.

AWS::CloudWatch::Alarm

The AWS::CloudWatch::Alarm type specifies an alarm and associates it with the specified metric or metric math expression.

When this operation creates an alarm, the alarm state is immediately set to INSUFFICIENT_DATA. The alarm is then evaluated and its state is set appropriately. Any actions associated with the new state are then executed.

When you update an existing alarm, its state is left unchanged, but the update completely overwrites the previous configuration of the alarm.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
  "Type" : "AWS::CloudWatch::Alarm",
  "Properties" : {
      "ActionsEnabled" : Boolean,
      "AlarmActions" : [ String, ... ],
      "AlarmDescription" : String,
      "AlarmName" : String,
      "ComparisonOperator" : String,
      "DatapointsToAlarm" : Integer,
      "Dimensions" : [ Dimension, ... ],
      "EvaluateLowSampleCountPercentile" : String,
      "EvaluationPeriods" : Integer,
      "ExtendedStatistic" : String,
      "InsufficientDataActions" : [ String, ... ],
      "MetricName" : String,
      "Metrics" : [ MetricDataQuery, ... ],
      "Namespace" : String,
      "OKActions" : [ String, ... ],
      "Period" : Integer,
      "Statistic" : String,
      "Tags" : [ Tag, ... ],
      "Threshold" : Number,
      "ThresholdMetricId" : String,
      "TreatMissingData" : String,
      "Unit" : String
    }
}

YAML

Type: AWS::CloudWatch::Alarm
Properties:
  ActionsEnabled: Boolean
  AlarmActions: 
    - String
  AlarmDescription: String
  AlarmName: String
  ComparisonOperator: String
  DatapointsToAlarm: Integer
  Dimensions: 
    - Dimension
  EvaluateLowSampleCountPercentile: String
  EvaluationPeriods: Integer
  ExtendedStatistic: String
  InsufficientDataActions: 
    - String
  MetricName: String
  Metrics: 
    - MetricDataQuery
  Namespace: String
  OKActions: 
    - String
  Period: Integer
  Statistic: String
  Tags: 
    - Tag
  Threshold: Number
  ThresholdMetricId: String
  TreatMissingData: String
  Unit: String

Properties

ActionsEnabled

Indicates whether actions should be executed during any changes to the alarm state. The default is TRUE.

Required: No

Type: Boolean

Update requires: No interruption

AlarmActions

The list of actions to execute when this alarm transitions into an ALARM state from any other state. Specify each action as an Amazon Resource Name (ARN). For more information about creating alarms and the actions that you can specify, see PutMetricAlarm in the Amazon CloudWatch API Reference.

Required: No

Type: Array of String

Maximum: 5

Update requires: No interruption

AlarmDescription

The description of the alarm.

Required: No

Type: String

Minimum: 0

Maximum: 1024

Update requires: No interruption

AlarmName

The name of the alarm. If you don't specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the alarm name.

Important

If you specify a name, you cannot perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you must replace the resource, specify a new name.

Required: No

Type: String

Minimum: 1

Maximum: 255

Update requires: Replacement

ComparisonOperator

The arithmetic operation to use when comparing the specified statistic and threshold. The specified statistic value is used as the first operand.

Required: Yes

Type: String

Allowed values: GreaterThanOrEqualToThreshold | GreaterThanThreshold | LessThanThreshold | LessThanOrEqualToThreshold | LessThanLowerOrGreaterThanUpperThreshold | LessThanLowerThreshold | GreaterThanUpperThreshold

Update requires: No interruption

DatapointsToAlarm

The number of datapoints that must be breaching to trigger the alarm. This is used only if you are setting an "M out of N" alarm. In that case, this value is the M, and the value that you set for EvaluationPeriods is the N value. For more information, see Evaluating an Alarm in the Amazon CloudWatch User Guide.

If you omit this parameter, CloudWatch uses the same value here that you set for EvaluationPeriods, and the alarm goes to alarm state if that many consecutive periods are breaching.

Required: No

Type: Integer

Minimum: 1

Update requires: No interruption

Dimensions

The dimensions for the metric associated with the alarm. For an alarm based on a math expression, you can't specify Dimensions. Instead, you use Metrics.

Required: No

Type: Array of Dimension

Maximum: 30

Update requires: No interruption

EvaluateLowSampleCountPercentile

Used only for alarms based on percentiles. If ignore, the alarm state does not change during periods with too few data points to be statistically significant. If evaluate or this parameter is not used, the alarm is always evaluated and possibly changes state no matter how many data points are available.

Required: No

Type: String

Minimum: 1

Maximum: 255

Update requires: No interruption

EvaluationPeriods

The number of periods over which data is compared to the specified threshold. If you are setting an alarm that requires that a number of consecutive data points be breaching to trigger the alarm, this value specifies that number. If you are setting an "M out of N" alarm, this value is the N, and DatapointsToAlarm is the M.

For more information, see Evaluating an Alarm in the Amazon CloudWatch User Guide.

Required: Yes

Type: Integer

Minimum: 1

Update requires: No interruption

ExtendedStatistic

The percentile statistic for the metric associated with the alarm. Specify a value between p0.0 and p100.

For an alarm based on a metric, you must specify either Statistic or ExtendedStatistic but not both.

For an alarm based on a math expression, you can't specify ExtendedStatistic. Instead, you use Metrics.

Required: No

Type: String

Update requires: No interruption

InsufficientDataActions

The actions to execute when this alarm transitions to the INSUFFICIENT_DATA state from any other state. Each action is specified as an Amazon Resource Name (ARN).

Required: No

Type: Array of String

Maximum: 5

Update requires: No interruption

MetricName

The name of the metric associated with the alarm. This is required for an alarm based on a metric. For an alarm based on a math expression, you use Metrics instead and you can't specify MetricName.

Required: No

Type: String

Minimum: 1

Maximum: 255

Update requires: No interruption

Metrics

An array that enables you to create an alarm based on the result of a metric math expression. Each item in the array either retrieves a metric or performs a math expression.

If you specify the Metrics parameter, you cannot specify MetricName, Dimensions, Period, Namespace, Statistic, ExtendedStatistic, or Unit.

Required: No

Type: Array of MetricDataQuery

Update requires: No interruption

Namespace

The namespace of the metric associated with the alarm. This is required for an alarm based on a metric. For an alarm based on a math expression, you can't specify Namespace and you use Metrics instead.

For a list of namespaces for metrics from AWS services, see AWS Services That Publish CloudWatchMetrics.

Required: No

Type: String

Pattern: [^:].*

Minimum: 1

Maximum: 255

Update requires: No interruption

OKActions

The actions to execute when this alarm transitions to the OK state from any other state. Each action is specified as an Amazon Resource Name (ARN).

Required: No

Type: Array of String

Maximum: 5

Update requires: No interruption

Period

The period, in seconds, over which the statistic is applied. This is required for an alarm based on a metric. Valid values are 10, 20, 30, 60, and any multiple of 60.

For an alarm based on a math expression, you can't specify Period, and instead you use the Metrics parameter.

Minimum: 10

Required: No

Type: Integer

Update requires: No interruption

Statistic

The statistic for the metric associated with the alarm, other than percentile. For percentile statistics, use ExtendedStatistic.

For an alarm based on a metric, you must specify either Statistic or ExtendedStatistic but not both.

For an alarm based on a math expression, you can't specify Statistic. Instead, you use Metrics.

Required: No

Type: String

Allowed values: SampleCount | Average | Sum | Minimum | Maximum

Update requires: No interruption

Tags

A list of key-value pairs to associate with the alarm. You can associate as many as 50 tags with an alarm. To be able to associate tags with the alarm when you create the alarm, you must have the cloudwatch:TagResource permission.

Tags can help you organize and categorize your resources. You can also use them to scope user permissions by granting a user permission to access or change only resources with certain tag values.

Required: No

Type: Array of Tag

Maximum: 50

Update requires: No interruption

Threshold

The value to compare with the specified statistic.

Required: No

Type: Number

Update requires: No interruption

ThresholdMetricId

In an alarm based on an anomaly detection model, this is the ID of the ANOMALY_DETECTION_BAND function used as the threshold for the alarm.

Required: No

Type: String

Minimum: 1

Maximum: 255

Update requires: No interruption

TreatMissingData

Sets how this alarm is to handle missing data points. Valid values are breaching, notBreaching, ignore, and missing. For more information, see Configuring How CloudWatchAlarms Treat Missing Data in the Amazon CloudWatchUser Guide.

If you omit this parameter, the default behavior of missing is used.

Required: No

Type: String

Minimum: 1

Maximum: 255

Update requires: No interruption

Unit

The unit of the metric associated with the alarm. Specify this only if you are creating an alarm based on a single metric. Do not specify this if you are specifying a Metrics array.

You can specify the following values: Seconds, Microseconds, Milliseconds, Bytes, Kilobytes, Megabytes, Gigabytes, Terabytes, Bits, Kilobits, Megabits, Gigabits, Terabits, Percent, Count, Bytes/Second, Kilobytes/Second, Megabytes/Second, Gigabytes/Second, Terabytes/Second, Bits/Second, Kilobits/Second, Megabits/Second, Gigabits/Second, Terabits/Second, Count/Second, or None.

Required: No

Type: String

Allowed values: Seconds | Microseconds | Milliseconds | Bytes | Kilobytes | Megabytes | Gigabytes | Terabytes | Bits | Kilobits | Megabits | Gigabits | Terabits | Percent | Count | Bytes/Second | Kilobytes/Second | Megabytes/Second | Gigabytes/Second | Terabytes/Second | Bits/Second | Kilobits/Second | Megabits/Second | Gigabits/Second | Terabits/Second | Count/Second | None

Update requires: No interruption

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the alarm name, such as TestAlarm.

For more information about using the Ref function, see Ref.

Fn::GetAtt

The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.

Arn

The ARN of the CloudWatchalarm, such as arn:aws:cloudwatch:us-west-2:123456789012:alarm:myCloudWatchAlarm-CPUAlarm-UXMMZK36R55Z.

Examples

Alarm Based on an Anomaly Detector

This example creates an alarm that is based on an anomaly detector.

JSON

"Resources": {
    "LambdaInvocationsAnomalyDetector": {
       "Type": "AWS::CloudWatch::AnomalyDetector",
       "Properties": {
          "MetricName": "Invocations",
          "Namespace": "AWS/Lambda",
          "Stat": "Sum"
       }
    },
    "LambdaInvocationsAlarm": {
       "Type": "AWS::CloudWatch::Alarm",
       "Properties": {
          "AlarmDescription": "Lambda invocations",
          "AlarmName": "LambdaInvocationsAlarm",
          "ComparisonOperator": "LessThanLowerOrGreaterThanUpperThreshold",
          "EvaluationPeriods": 1,
          "Metrics": [
             {
                "Expression": "ANOMALY_DETECTION_BAND(m1, 2)",
                "Id": "ad1"
             },
             {
                "Id": "m1",
                "MetricStat": {
                   "Metric": {
                      "MetricName": "Invocations",
                      "Namespace": "AWS/Lambda"
                   },
                   "Period": 86400,
                   "Stat": "Sum"
                }
             }
          ],
          "ThresholdMetricId": "ad1",
          "TreatMissingData": "breaching"
       }
    }
 }

YAML

Resources:
  LambdaInvocationsAnomalyDetector:
    Type: AWS::CloudWatch::AnomalyDetector
    Properties:
      MetricName: Invocations
      Namespace: AWS/Lambda
      Stat: Sum

  LambdaInvocationsAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmDescription: Lambda invocations
      AlarmName: LambdaInvocationsAlarm
      ComparisonOperator: LessThanLowerOrGreaterThanUpperThreshold
      EvaluationPeriods: 1
      Metrics:
      - Expression: ANOMALY_DETECTION_BAND(m1, 2)
        Id: ad1
      - Id: m1
        MetricStat:
          Metric:
            MetricName: Invocations
            Namespace: AWS/Lambda
          Period: !!int 86400
          Stat: Sum
      ThresholdMetricId: ad1
      TreatMissingData: breaching

See also