alarms

Creates, updates, deletes or gets an alarm resource or lists alarms in a region

Overview

Name	alarms
Type	Resource
Description	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.
Id	aws.cloudwatch.alarms

Fields

Name	Datatype	Description
threshold_metric_id	string	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.
evaluate_low_sample_count_percentile	string	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.
extended_statistic	string	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.
comparison_operator	string	The arithmetic operation to use when comparing the specified statistic and threshold. The specified statistic value is used as the first operand.
treat_missing_data	string	Sets how this alarm is to handle missing data points. Valid values are breaching, notBreaching, ignore, and missing. For more information, see [Configuring How Alarms Treat Missing Data](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data) in the *Amazon User Guide*. If you omit this parameter, the default behavior of missing is used.
dimensions	array	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.
period	integer	The period, in seconds, over which the statistic is applied. This is required for an alarm based on a metric. Valid values are 10, 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
evaluation_periods	integer	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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarm-evaluation) in the *User Guide*.
unit	string	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.
namespace	string	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 [Services That Publish Metrics.](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/aws-services-cloudwatch-metrics.html)
ok_actions	array	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).
alarm_actions	array	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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html) in the *API Reference*.
metric_name	string	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.
actions_enabled	boolean	Indicates whether actions should be executed during any changes to the alarm state. The default is TRUE.
metrics	array	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.
alarm_description	string	The description of the alarm.
alarm_name	string	The name of the alarm. If you don't specify a name, CFN generates a unique physical ID and uses that ID for the alarm name. 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.
statistic	string	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.
insufficient_data_actions	array	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).
arn	string
datapoints_to_alarm	integer	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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarm-evaluation) in the *User Guide*. If you omit this parameter, CW uses the same value here that you set for EvaluationPeriods, and the alarm goes to alarm state if that many consecutive periods are breaching.
threshold	number	The value to compare with the specified statistic.
tags	array
region	string	AWS region.

Methods

Name	Accessible by	Required Params
create_resource	INSERT	ComparisonOperator, EvaluationPeriods, region
delete_resource	DELETE	data__Identifier, region
update_resource	UPDATE	data__Identifier, data__PatchDocument, region
list_resources	SELECT	region
get_resource	SELECT	data__Identifier, region

SELECT examples

Gets all alarms in a region.

SELECT
region,
threshold_metric_id,
evaluate_low_sample_count_percentile,
extended_statistic,
comparison_operator,
treat_missing_data,
dimensions,
period,
evaluation_periods,
unit,
namespace,
ok_actions,
alarm_actions,
metric_name,
actions_enabled,
metrics,
alarm_description,
alarm_name,
statistic,
insufficient_data_actions,
arn,
datapoints_to_alarm,
threshold,
tags
FROM aws.cloudwatch.alarms
WHERE region = 'us-east-1';

Gets all properties from an individual alarm.

SELECT
region,
threshold_metric_id,
evaluate_low_sample_count_percentile,
extended_statistic,
comparison_operator,
treat_missing_data,
dimensions,
period,
evaluation_periods,
unit,
namespace,
ok_actions,
alarm_actions,
metric_name,
actions_enabled,
metrics,
alarm_description,
alarm_name,
statistic,
insufficient_data_actions,
arn,
datapoints_to_alarm,
threshold,
tags
FROM aws.cloudwatch.alarms
WHERE region = 'us-east-1' AND data__Identifier = '<AlarmName>';

INSERT example

Use the following StackQL query and manifest file to create a new alarm resource, using stack-deploy.

Required Properties

/*+ create */
INSERT INTO aws.cloudwatch.alarms (
 ComparisonOperator,
 EvaluationPeriods,
 region
)
SELECT 
'{{ ComparisonOperator }}',
 '{{ EvaluationPeriods }}',
'{{ region }}';

All Properties

/*+ create */
INSERT INTO aws.cloudwatch.alarms (
 ThresholdMetricId,
 EvaluateLowSampleCountPercentile,
 ExtendedStatistic,
 ComparisonOperator,
 TreatMissingData,
 Dimensions,
 Period,
 EvaluationPeriods,
 Unit,
 Namespace,
 OKActions,
 AlarmActions,
 MetricName,
 ActionsEnabled,
 Metrics,
 AlarmDescription,
 AlarmName,
 Statistic,
 InsufficientDataActions,
 DatapointsToAlarm,
 Threshold,
 Tags,
 region
)
SELECT 
 '{{ ThresholdMetricId }}',
 '{{ EvaluateLowSampleCountPercentile }}',
 '{{ ExtendedStatistic }}',
 '{{ ComparisonOperator }}',
 '{{ TreatMissingData }}',
 '{{ Dimensions }}',
 '{{ Period }}',
 '{{ EvaluationPeriods }}',
 '{{ Unit }}',
 '{{ Namespace }}',
 '{{ OKActions }}',
 '{{ AlarmActions }}',
 '{{ MetricName }}',
 '{{ ActionsEnabled }}',
 '{{ Metrics }}',
 '{{ AlarmDescription }}',
 '{{ AlarmName }}',
 '{{ Statistic }}',
 '{{ InsufficientDataActions }}',
 '{{ DatapointsToAlarm }}',
 '{{ Threshold }}',
 '{{ Tags }}',
 '{{ region }}';

Manifest

version: 1
name: stack name
description: stack description
providers:
  - aws
globals:
  - name: region
    value: '{{ vars.AWS_REGION }}'
resources:
  - name: alarm
    props:
      - name: ThresholdMetricId
        value: '{{ ThresholdMetricId }}'
      - name: EvaluateLowSampleCountPercentile
        value: '{{ EvaluateLowSampleCountPercentile }}'
      - name: ExtendedStatistic
        value: '{{ ExtendedStatistic }}'
      - name: ComparisonOperator
        value: '{{ ComparisonOperator }}'
      - name: TreatMissingData
        value: '{{ TreatMissingData }}'
      - name: Dimensions
        value:
          - Value: '{{ Value }}'
            Name: '{{ Name }}'
      - name: Period
        value: '{{ Period }}'
      - name: EvaluationPeriods
        value: '{{ EvaluationPeriods }}'
      - name: Unit
        value: '{{ Unit }}'
      - name: Namespace
        value: '{{ Namespace }}'
      - name: OKActions
        value:
          - '{{ OKActions[0] }}'
      - name: AlarmActions
        value:
          - '{{ AlarmActions[0] }}'
      - name: MetricName
        value: '{{ MetricName }}'
      - name: ActionsEnabled
        value: '{{ ActionsEnabled }}'
      - name: Metrics
        value:
          - Label: '{{ Label }}'
            MetricStat:
              Period: '{{ Period }}'
              Metric:
                MetricName: '{{ MetricName }}'
                Dimensions:
                  - null
                Namespace: '{{ Namespace }}'
              Stat: '{{ Stat }}'
              Unit: '{{ Unit }}'
            Id: '{{ Id }}'
            ReturnData: '{{ ReturnData }}'
            Expression: '{{ Expression }}'
            Period: '{{ Period }}'
            AccountId: '{{ AccountId }}'
      - name: AlarmDescription
        value: '{{ AlarmDescription }}'
      - name: AlarmName
        value: '{{ AlarmName }}'
      - name: Statistic
        value: '{{ Statistic }}'
      - name: InsufficientDataActions
        value:
          - '{{ InsufficientDataActions[0] }}'
      - name: DatapointsToAlarm
        value: '{{ DatapointsToAlarm }}'
      - name: Threshold
        value: null
      - name: Tags
        value:
          - Key: '{{ Key }}'
            Value: '{{ Value }}'

DELETE example

/*+ delete */
DELETE FROM aws.cloudwatch.alarms
WHERE data__Identifier = '<AlarmName>'
AND region = 'us-east-1';

Permissions

To operate on the alarms resource, the following permissions are required:

Create

cloudwatch:PutMetricAlarm,
cloudwatch:DescribeAlarms,
cloudwatch:TagResource

Update

cloudwatch:PutMetricAlarm,
cloudwatch:DescribeAlarms,
cloudwatch:TagResource,
cloudwatch:UntagResource

Delete

cloudwatch:DeleteAlarms,
cloudwatch:DescribeAlarms

List

cloudwatch:DescribeAlarms

Read

cloudwatch:DescribeAlarms,
cloudwatch:ListTagsForResource