Skip to main content

alarms

Creates, updates, deletes, gets or lists an alarms resource.

Overview​

Namealarms
TypeResource
Idaws.cloudwatch.alarms

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
actions_enabledbooleanIndicates whether actions should be executed during any changes to the alarm state.
alarm_actionsarrayThe actions to execute when this alarm transitions to the ALARM state from any other state. Each action is specified as an Amazon Resource Name (ARN).
alarm_arnstringThe Amazon Resource Name (ARN) of the alarm.
alarm_configuration_updated_timestampstring (date-time)The time stamp of the last update to the alarm configuration.
alarm_descriptionstringThe description of the alarm.
alarm_namestringThe name of the alarm.
comparison_operatorstringThe arithmetic operation to use when comparing the specified statistic and threshold. The specified statistic value is used as the first operand. (GreaterThanOrEqualToThreshold, GreaterThanThreshold, LessThanThreshold, LessThanOrEqualToThreshold, LessThanLowerOrGreaterThanUpperThreshold, LessThanLowerThreshold, GreaterThanUpperThreshold)
datapoints_to_alarmintegerThe number of data points that must be breaching to trigger the alarm.
dimensionsarrayThe dimensions for the metric associated with the alarm.
evaluate_low_sample_count_percentilestringUsed 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.
evaluation_criteriaobjectThe evaluation criteria for the alarm.
evaluation_intervalintegerThe frequency, in seconds, at which the alarm is evaluated.
evaluation_periodsintegerThe number of periods over which data is compared to the specified threshold.
evaluation_statestringIf the value of this field is PARTIAL_DATA, it indicates that not all the available data was able to be retrieved due to quota limitations. For more information, see Create alarms on Metrics Insights queries. If the value of this field is EVALUATION_ERROR, it indicates configuration errors in alarm setup that require review and correction. Refer to StateReason field of the alarm for more details. If the value of this field is EVALUATION_FAILURE, it indicates temporary CloudWatch issues. We recommend manual monitoring until the issue is resolved (PARTIAL_DATA, EVALUATION_FAILURE, EVALUATION_ERROR)
evaluation_windowobjectThe evaluation window that the alarm uses to select the range of metric data that it evaluates. This is either a sliding window or a wall clock window. For more information, see Alarm evaluation windows in the CloudWatch User Guide.
extended_statisticstringThe percentile statistic for the metric associated with the alarm. Specify a value between p0.0 and p100.
insufficient_data_actionsarrayThe 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).
metric_namestringThe name of the metric associated with the alarm, if this is an alarm based on a single metric.
metricsarrayAn array of MetricDataQuery structures, used in an alarm based on a metric math expression. Each structure either retrieves a metric or performs a math expression. One item in the Metrics array is the math expression that the alarm watches. This expression by designated by having ReturnData set to true.
namespacestringThe namespace of the metric associated with the alarm. (pattern: <code>[^:].*</code>)
ok_actionsarrayThe 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).
periodintegerThe period, in seconds, over which the statistic is applied.
state_reasonstringAn explanation for the alarm state, in text format.
state_reason_datastringAn explanation for the alarm state, in JSON format.
state_transitioned_timestampstring (date-time)The date and time that the alarm's StateValue most recently changed.
state_updated_timestampstring (date-time)The time stamp of the last update to the value of either the StateValue or EvaluationState parameters.
state_valuestringThe state value for the alarm. (OK, ALARM, INSUFFICIENT_DATA)
statisticstringThe statistic for the metric associated with the alarm, other than percentile. For percentile statistics, use ExtendedStatistic. (SampleCount, Average, Sum, Minimum, Maximum)
thresholdnumber (double)The value to compare with the specified statistic.
threshold_metric_idstringIn 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.
treat_missing_datastringSets how this alarm is to handle missing data points. The valid values are breaching, notBreaching, ignore, and missing. For more information, see Configuring how CloudWatch alarms treat missing data. If this parameter is omitted, the default behavior of missing is used. This parameter is not applicable to PromQL alarms.
unitstringThe unit of the metric associated with the alarm. (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)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_alarmsselectregionRetrieves the specified alarms. You can filter the results by specifying a prefix for the alarm name, the alarm state, or a prefix for any action. To use this operation and return information about composite alarms, you must be signed on with the cloudwatch:DescribeAlarms permission that is scoped to *. You can't return information about composite alarms if your cloudwatch:DescribeAlarms permission has a narrower scope.
set_alarm_stateupdateregion, AlarmName, StateValue, StateReasonTemporarily sets the state of an alarm for testing purposes. When the updated state differs from the previous value, the action configured for the appropriate state is invoked. For example, if your alarm is configured to send an Amazon SNS message when an alarm is triggered, temporarily changing the alarm state to ALARM sends an SNS message. Metric alarms returns to their actual state quickly, often within seconds. Because the metric alarm state change happens quickly, it is typically only visible in the alarm's History tab in the Amazon CloudWatch console or through DescribeAlarmHistory. If you use SetAlarmState on a composite alarm, the composite alarm is not guaranteed to return to its actual state. It returns to its actual state only once any of its children alarms change state. It is also reevaluated if you update its configuration. If an alarm triggers EC2 Auto Scaling policies or application Auto Scaling policies, you must include information in the StateReasonData parameter to enable the policy to take the correct action.
put_log_alarmreplaceregion, AlarmName, ScheduledQueryConfiguration, QueryResultsToEvaluate, QueryResultsToAlarm, ComparisonOperatorCreates or updates a log alarm. A log alarm evaluates the results of a CloudWatch Logs scheduled query against the configured threshold and comparison operator to determine its state. When you create a log alarm, the operation creates a service-managed CloudWatch Logs scheduled query that runs the query string you provide on the schedule you configure. Each scheduled query execution returns one or more aggregated values determined by the AggregationExpression, and each aggregated value is compared against the alarm Threshold to determine the alarm state. The alarm uses M-out-of-N evaluation: if QueryResultsToAlarm out of the most recent QueryResultsToEvaluate query results breach the threshold, the alarm transitions to ALARM. Log alarms support the alarm states (OK, ALARM, INSUFFICIENT_DATA). Configure transition actions using OKActions, AlarmActions, and InsufficientDataActions. If you call this operation with the name of an existing log alarm, the operation replaces the previous configuration of that alarm. Permissions To create or update a log alarm, you must have the cloudwatch:PutLogAlarm permission. The IAM role specified in ScheduledQueryRoleARN must grant the CloudWatch Alarms service permission to execute scheduled queries on the specified log groups. If you set ActionLogLineCount, the role specified in ActionLogLineRoleArn must grant permission to retrieve log events for inclusion in alarm notifications.
put_composite_alarmreplaceregion, AlarmName, AlarmRuleCreates or updates a composite alarm. When you create a composite alarm, you specify a rule expression for the alarm that takes into account the alarm states of other alarms that you have created. The composite alarm goes into ALARM state only if all conditions of the rule are met. The alarms specified in a composite alarm's rule expression can include metric alarms and other composite alarms. The rule expression of a composite alarm can include as many as 100 underlying alarms. Any single alarm can be included in the rule expressions of as many as 150 composite alarms. Using composite alarms can reduce alarm noise. You can create multiple metric alarms, and also create a composite alarm and set up alerts only for the composite alarm. For example, you could create a composite alarm that goes into ALARM state only when more than one of the underlying metric alarms are in ALARM state. Composite alarms can take the following actions: Notify Amazon SNS topics. Invoke Lambda functions. Create OpsItems in Systems Manager Ops Center. Create incidents in Systems Manager Incident Manager. It is possible to create a loop or cycle of composite alarms, where composite alarm A depends on composite alarm B, and composite alarm B also depends on composite alarm A. In this scenario, you can't delete any composite alarm that is part of the cycle because there is always still a composite alarm that depends on that alarm that you want to delete. To get out of such a situation, you must break the cycle by changing the rule of one of the composite alarms in the cycle to remove a dependency that creates the cycle. The simplest change to make to break a cycle is to change the AlarmRule of one of the alarms to false. Additionally, the evaluation of composite alarms stops if CloudWatch detects a cycle in the evaluation path. 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. For a composite alarm, this initial time after creation is the only time that the alarm can be in INSUFFICIENT_DATA state. When you update an existing alarm, its state is left unchanged, but the update completely overwrites the previous configuration of the alarm. To use this operation, you must be signed on with the cloudwatch:PutCompositeAlarm permission that is scoped to *. You can't create a composite alarms if your cloudwatch:PutCompositeAlarm permission has a narrower scope. If you are an IAM user, you must have iam:CreateServiceLinkedRole to create a composite alarm that has Systems Manager OpsItem actions.
put_metric_alarmreplaceregion, AlarmNameCreates or updates an alarm and associates it with the specified metric, metric math expression, anomaly detection model, Metrics Insights query, or PromQL query. For more information about using a Metrics Insights query for an alarm, see Create alarms on Metrics Insights queries. Alarms based on anomaly detection models cannot have Auto Scaling actions. When this operation creates an alarm, the alarm state is immediately set to INSUFFICIENT_DATA. For PromQL alarms, the alarm state is instead immediately set to OK. 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. If you are an IAM user, you must have Amazon EC2 permissions for some alarm operations: The iam:CreateServiceLinkedRole permission for all alarms with EC2 actions The iam:CreateServiceLinkedRole permissions to create an alarm with Systems Manager OpsItem or response plan actions. The first time you create an alarm in the Amazon Web Services Management Console, the CLI, or by using the PutMetricAlarm API, CloudWatch creates the necessary service-linked role for you. The service-linked roles are called AWSServiceRoleForCloudWatchEvents and AWSServiceRoleForCloudWatchAlarms_ActionSSM. For more information, see Amazon Web Services service-linked role. Each PutMetricAlarm action has a maximum uncompressed payload of 120 KB. Cross-account alarms You can set an alarm on metrics in the current account, or in another account. To create a cross-account alarm that watches a metric in a different account, you must have completed the following pre-requisites: The account where the metrics are located (the sharing account) must already have a sharing role named CloudWatch-CrossAccountSharingRole. If it does not already have this role, you must create it using the instructions in Set up a sharing account in Cross-account cross-Region CloudWatch console. The policy for that role must grant access to the ID of the account where you are creating the alarm. The account where you are creating the alarm (the monitoring account) must already have a service-linked role named AWSServiceRoleForCloudWatchCrossAccount to allow CloudWatch to assume the sharing role in the sharing account. If it does not, you must create it following the directions in Set up a monitoring account in Cross-account cross-Region CloudWatch console.
delete_alarmsdeleteregionDeletes the specified alarms. You can delete up to 100 alarms in one operation. However, this total can include no more than one composite alarm. For example, you could delete 99 metric alarms and one composite alarms with one operation, but you can't delete two composite alarms with one operation. Log alarms cannot be batch deleted. If you specify any incorrect alarm names, the alarms you specify with correct names are still deleted. Other syntax errors might result in no alarms being deleted. To confirm that alarms were deleted successfully, you can use the DescribeAlarms operation after using DeleteAlarms. It is possible to create a loop or cycle of composite alarms, where composite alarm A depends on composite alarm B, and composite alarm B also depends on composite alarm A. In this scenario, you can't delete any composite alarm that is part of the cycle because there is always still a composite alarm that depends on that alarm that you want to delete. To get out of such a situation, you must break the cycle by changing the rule of one of the composite alarms in the cycle to remove a dependency that creates the cycle. The simplest change to make to break a cycle is to change the AlarmRule of one of the alarms to false. Additionally, the evaluation of composite alarms stops if CloudWatch detects a cycle in the evaluation path.
disable_alarm_actionsexecregion, AlarmNamesDisables the actions for the specified alarms. When an alarm's actions are disabled, the alarm actions do not execute when the alarm state changes.
enable_alarm_actionsexecregion, AlarmNamesEnables the actions for the specified alarms.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Retrieves the specified alarms. You can filter the results by specifying a prefix for the alarm name, the alarm state, or a prefix for any action. To use this operation and return information about composite alarms, you must be signed on with the cloudwatch:DescribeAlarms permission that is scoped to *. You can't return information about composite alarms if your cloudwatch:DescribeAlarms permission has a narrower scope.

SELECT
actions_enabled,
alarm_actions,
alarm_arn,
alarm_configuration_updated_timestamp,
alarm_description,
alarm_name,
comparison_operator,
datapoints_to_alarm,
dimensions,
evaluate_low_sample_count_percentile,
evaluation_criteria,
evaluation_interval,
evaluation_periods,
evaluation_state,
evaluation_window,
extended_statistic,
insufficient_data_actions,
metric_name,
metrics,
namespace,
ok_actions,
period,
state_reason,
state_reason_data,
state_transitioned_timestamp,
state_updated_timestamp,
state_value,
statistic,
threshold,
threshold_metric_id,
treat_missing_data,
unit
FROM aws.cloudwatch.alarms
WHERE region = '{{ region }}' -- required
;

UPDATE examples​

Temporarily sets the state of an alarm for testing purposes. When the updated state differs from the previous value, the action configured for the appropriate state is invoked. For example, if your alarm is configured to send an Amazon SNS message when an alarm is triggered, temporarily changing the alarm state to ALARM sends an SNS message. Metric alarms returns to their actual state quickly, often within seconds. Because the metric alarm state change happens quickly, it is typically only visible in the alarm's History tab in the Amazon CloudWatch console or through DescribeAlarmHistory. If you use SetAlarmState on a composite alarm, the composite alarm is not guaranteed to return to its actual state. It returns to its actual state only once any of its children alarms change state. It is also reevaluated if you update its configuration. If an alarm triggers EC2 Auto Scaling policies or application Auto Scaling policies, you must include information in the StateReasonData parameter to enable the policy to take the correct action.

UPDATE aws.cloudwatch.alarms
SET 
AlarmName = '{{ AlarmName }}',
StateValue = '{{ StateValue }}',
StateReason = '{{ StateReason }}',
StateReasonData = '{{ StateReasonData }}'
WHERE 
region = '{{ region }}' --required
AND AlarmName = '{{ AlarmName }}' --required
AND StateValue = '{{ StateValue }}' --required
AND StateReason = '{{ StateReason }}' --required;

REPLACE examples​

Creates or updates a log alarm. A log alarm evaluates the results of a CloudWatch Logs scheduled query against the configured threshold and comparison operator to determine its state. When you create a log alarm, the operation creates a service-managed CloudWatch Logs scheduled query that runs the query string you provide on the schedule you configure. Each scheduled query execution returns one or more aggregated values determined by the AggregationExpression, and each aggregated value is compared against the alarm Threshold to determine the alarm state. The alarm uses M-out-of-N evaluation: if QueryResultsToAlarm out of the most recent QueryResultsToEvaluate query results breach the threshold, the alarm transitions to ALARM. Log alarms support the alarm states (OK, ALARM, INSUFFICIENT_DATA). Configure transition actions using OKActions, AlarmActions, and InsufficientDataActions. If you call this operation with the name of an existing log alarm, the operation replaces the previous configuration of that alarm. Permissions To create or update a log alarm, you must have the cloudwatch:PutLogAlarm permission. The IAM role specified in ScheduledQueryRoleARN must grant the CloudWatch Alarms service permission to execute scheduled queries on the specified log groups. If you set ActionLogLineCount, the role specified in ActionLogLineRoleArn must grant permission to retrieve log events for inclusion in alarm notifications.

REPLACE aws.cloudwatch.alarms
SET 
AlarmName = '{{ AlarmName }}',
AlarmDescription = '{{ AlarmDescription }}',
ScheduledQueryConfiguration = '{{ ScheduledQueryConfiguration }}',
ActionLogLineCount = {{ ActionLogLineCount }},
ActionLogLineRoleArn = '{{ ActionLogLineRoleArn }}',
ActionsEnabled = {{ ActionsEnabled }},
OKActions = '{{ OKActions }}',
AlarmActions = '{{ AlarmActions }}',
InsufficientDataActions = '{{ InsufficientDataActions }}',
QueryResultsToEvaluate = {{ QueryResultsToEvaluate }},
QueryResultsToAlarm = {{ QueryResultsToAlarm }},
Threshold = {{ Threshold }},
ComparisonOperator = '{{ ComparisonOperator }}',
TreatMissingData = '{{ TreatMissingData }}',
Tags = '{{ Tags }}'
WHERE 
region = '{{ region }}' --required
AND AlarmName = '{{ AlarmName }}' --required
AND ScheduledQueryConfiguration = '{{ ScheduledQueryConfiguration }}' --required
AND QueryResultsToEvaluate = '{{ QueryResultsToEvaluate }}' --required
AND QueryResultsToAlarm = '{{ QueryResultsToAlarm }}' --required
AND ComparisonOperator = '{{ ComparisonOperator }}' --required;

DELETE examples​

Deletes the specified alarms. You can delete up to 100 alarms in one operation. However, this total can include no more than one composite alarm. For example, you could delete 99 metric alarms and one composite alarms with one operation, but you can't delete two composite alarms with one operation. Log alarms cannot be batch deleted. If you specify any incorrect alarm names, the alarms you specify with correct names are still deleted. Other syntax errors might result in no alarms being deleted. To confirm that alarms were deleted successfully, you can use the DescribeAlarms operation after using DeleteAlarms. It is possible to create a loop or cycle of composite alarms, where composite alarm A depends on composite alarm B, and composite alarm B also depends on composite alarm A. In this scenario, you can't delete any composite alarm that is part of the cycle because there is always still a composite alarm that depends on that alarm that you want to delete. To get out of such a situation, you must break the cycle by changing the rule of one of the composite alarms in the cycle to remove a dependency that creates the cycle. The simplest change to make to break a cycle is to change the AlarmRule of one of the alarms to false. Additionally, the evaluation of composite alarms stops if CloudWatch detects a cycle in the evaluation path.

DELETE FROM aws.cloudwatch.alarms
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

Disables the actions for the specified alarms. When an alarm's actions are disabled, the alarm actions do not execute when the alarm state changes.

EXEC aws.cloudwatch.alarms.disable_alarm_actions 
@region='{{ region }}' --required 
@@json=
'{
"AlarmNames": "{{ AlarmNames }}"
}'
;
Last updated on