Sign In to the Console
AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource and Property Types Reference » Amazon CloudWatch Resource Types Reference » AWS::CloudWatch::Alarm

AWS::CloudWatch::Alarm

The AWS::CloudWatch::Alarm type creates a CloudWatch alarm.

This type supports updates. For more information about updating this resource, see PutMetricAlarm. For more information about updating stacks, see AWS CloudFormation Stacks Updates.

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,
      "Threshold" : Double,
      "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
  Threshold: Double
  TreatMissingData: String
  Unit: String

Properties

ActionsEnabled

Indicates whether actions should be executed during changes to the CloudWatch alarm's state.

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 and Creating Amazon CloudWatch Alarms in the Amazon CloudWatch User Guide.

Note

For Auto Scaling scaling polices, you can specify only one policy. If you associate more than one policy, Amazon CloudWatch executes only the first scaling policy.

Required: No

Type: List of String values

Update requires: No interruption

AlarmDescription

The description of the alarm.

Required: No

Type: String

Update requires: No interruption

AlarmName

A name for the alarm. If you don't specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the alarm name. For more information, see Name Type.

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

Update requires: Replacement

ComparisonOperator

The arithmetic operation to use when comparing the specified Statistic and Threshold. AWS CloudFormation uses the value of Statistic as the first operand.

You can specify the following values: GreaterThanOrEqualToThreshold , GreaterThanThreshold, LessThanThreshold, or LessThanOrEqualToThreshold.

Required: Yes

Type: String

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. For more information, see Evaluating an Alarm in the Amazon CloudWatch User Guide.

Required: No

Type: Integer

Update requires: No interruption

Dimensions

The dimensions of the metric for the alarm.

Required: No

Type: List of Metric Dimension

Update requires: No interruption

EvaluateLowSampleCountPercentile

Used only for alarms that are based on percentiles. Specifies whether to evaluate the data and potentially change the alarm state if there are too few data points to be statistically significant.

Required: No

Type: String

Update requires: No interruption

EvaluationPeriods

The number of periods over which data is compared to the specified threshold.

Required: Yes

Type: Integer

Update requires: No interruption

ExtendedStatistic

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

Required: Conditional. You must specify either the ExtendedStatistic or the Statistic property.

Type: String

Update requires: No interruption

InsufficientDataActions

The list of actions to execute when this alarm transitions into an INSUFFICIENT_DATA state. Specify each action as an Amazon Resource Number (ARN). Currently, the only supported actions are publishing to an Amazon SNS topic and publishing to an Auto Scaling policy.

Required: No

Type: List of String values

Update requires: No interruption

MetricName

The name of the metric associated with the alarm. For more information about the metrics that you can specify, see Amazon CloudWatch Namespaces, Dimensions, and Metrics Reference in the Amazon CloudWatch User Guide.

Required: No

Type: String

Update requires: No interruption

Metrics

Specifies the metric data to return.

Required: No

Type: List of MetricDataQuery property types

Update requires: No interruption

Namespace

The namespace of the metric that is associated with the alarm.

Required: No

Type: String

Update requires: No interruption

OKActions

The list of actions to execute when this alarm transitions into an OK state. Specify each action as an Amazon Resource Number (ARN). Currently, the only action supported is publishing to an SNS topic or an Auto Scaling policy.

Required: No

Type: List of String values

Update requires: No interruption

Period

The time over which the specified statistic is applied. Specify time in seconds, in multiples of 60.

Required: No

Type: Integer

Update requires: No interruption

Statistic

The statistic to apply to the alarm's associated metric.

You can specify the following values: SampleCount, Average, Sum, Minimum, or Maximum.

Required: Conditional. You must specify either the ExtendedStatistic or the Statistic property.

Type: String

Update requires: No interruption

Threshold

The value against which the specified statistic is compared.

Required: Yes

Type: Double

Update requires: No interruption

TreatMissingData

Sets how this alarm is to handle missing data points. If TreatMissingData is omitted, the default behavior of missing is used. For more information, see PutMetricAlarm in the Amazon CloudWatch API Reference and Configuring How CloudWatch Alarms Treats Missing Data in the Amazon CloudWatch User Guide.

Valid values: breaching, notBreaching, ignore, missing

Required: No

Type: String

Update requires: No interruption

Unit

The unit for the metric that is associated with the alarm.

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

Update requires: No interruption

Return Values

Ref

When you specify an AWS::CloudWatch::Alarm type as an argument to the Ref function, AWS CloudFormation returns the value of the AlarmName.

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

Fn::GetAtt

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

Arn

The Amazon Resource Name (ARN) of the CloudWatch alarm, such as arn:aws:cloudwatch:us-east-2:123456789012:alarm:myCloudWatchAlarm-CPUAlarm-UXMMZK36R55Z.

For more information about using Fn::GetAtt, see Fn::GetAtt.

Examples

For examples, see Amazon CloudWatch Template Snippets.