Use PutMetricAlarm with an AWS SDK or CLI - Amazon CloudWatch

Use PutMetricAlarm with an AWS SDK or CLI

The following code examples show how to use PutMetricAlarm.

Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code examples:

.NET
AWS SDK for .NET
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

/// <summary> /// Add a metric alarm to send an email when the metric passes a threshold. /// </summary> /// <param name="alarmDescription">A description of the alarm.</param> /// <param name="alarmName">The name for the alarm.</param> /// <param name="comparison">The type of comparison to use.</param> /// <param name="metricName">The name of the metric for the alarm.</param> /// <param name="metricNamespace">The namespace of the metric.</param> /// <param name="threshold">The threshold value for the alarm.</param> /// <param name="alarmActions">Optional actions to execute when in an alarm state.</param> /// <returns>True if successful.</returns> public async Task<bool> PutMetricEmailAlarm(string alarmDescription, string alarmName, ComparisonOperator comparison, string metricName, string metricNamespace, double threshold, List<string> alarmActions = null!) { try { var putEmailAlarmResponse = await _amazonCloudWatch.PutMetricAlarmAsync( new PutMetricAlarmRequest() { AlarmActions = alarmActions, AlarmDescription = alarmDescription, AlarmName = alarmName, ComparisonOperator = comparison, Threshold = threshold, Namespace = metricNamespace, MetricName = metricName, EvaluationPeriods = 1, Period = 10, Statistic = new Statistic("Maximum"), DatapointsToAlarm = 1, TreatMissingData = "ignore" }); return putEmailAlarmResponse.HttpStatusCode == HttpStatusCode.OK; } catch (LimitExceededException lex) { _logger.LogError(lex, $"Unable to add alarm {alarmName}. Alarm quota has already been reached."); } return false; } /// <summary> /// Add specific email actions to a list of action strings for a CloudWatch alarm. /// </summary> /// <param name="accountId">The AccountId for the alarm.</param> /// <param name="region">The region for the alarm.</param> /// <param name="emailTopicName">An Amazon Simple Notification Service (SNS) topic for the alarm email.</param> /// <param name="alarmActions">Optional list of existing alarm actions to append to.</param> /// <returns>A list of string actions for an alarm.</returns> public List<string> AddEmailAlarmAction(string accountId, string region, string emailTopicName, List<string>? alarmActions = null) { alarmActions ??= new List<string>(); var snsAlarmAction = $"arn:aws:sns:{region}:{accountId}:{emailTopicName}"; alarmActions.Add(snsAlarmAction); return alarmActions; }
  • For API details, see PutMetricAlarm in AWS SDK for .NET API Reference.

C++
SDK for C++
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

Include the required files.

#include <aws/core/Aws.h> #include <aws/monitoring/CloudWatchClient.h> #include <aws/monitoring/model/PutMetricAlarmRequest.h> #include <iostream>

Create the alarm to watch the metric.

Aws::CloudWatch::CloudWatchClient cw; Aws::CloudWatch::Model::PutMetricAlarmRequest request; request.SetAlarmName(alarm_name); request.SetComparisonOperator( Aws::CloudWatch::Model::ComparisonOperator::GreaterThanThreshold); request.SetEvaluationPeriods(1); request.SetMetricName("CPUUtilization"); request.SetNamespace("AWS/EC2"); request.SetPeriod(60); request.SetStatistic(Aws::CloudWatch::Model::Statistic::Average); request.SetThreshold(70.0); request.SetActionsEnabled(false); request.SetAlarmDescription("Alarm when server CPU exceeds 70%"); request.SetUnit(Aws::CloudWatch::Model::StandardUnit::Seconds); Aws::CloudWatch::Model::Dimension dimension; dimension.SetName("InstanceId"); dimension.SetValue(instanceId); request.AddDimensions(dimension); auto outcome = cw.PutMetricAlarm(request); if (!outcome.IsSuccess()) { std::cout << "Failed to create CloudWatch alarm:" << outcome.GetError().GetMessage() << std::endl; } else { std::cout << "Successfully created CloudWatch alarm " << alarm_name << std::endl; }
  • For API details, see PutMetricAlarm in AWS SDK for C++ API Reference.

CLI
AWS CLI

To send an Amazon Simple Notification Service email message when CPU utilization exceeds 70 percent

The following example uses the put-metric-alarm command to send an Amazon Simple Notification Service email message when CPU utilization exceeds 70 percent:

aws cloudwatch put-metric-alarm --alarm-name cpu-mon --alarm-description "Alarm when CPU exceeds 70 percent" --metric-name CPUUtilization --namespace AWS/EC2 --statistic Average --period 300 --threshold 70 --comparison-operator GreaterThanThreshold --dimensions "Name=InstanceId,Value=i-12345678" --evaluation-periods 2 --alarm-actions arn:aws:sns:us-east-1:111122223333:MyTopic --unit Percent

This command returns to the prompt if successful. If an alarm with the same name already exists, it will be overwritten by the new alarm.

To specify multiple dimensions

The following example illustrates how to specify multiple dimensions. Each dimension is specified as a Name/Value pair, with a comma between the name and the value. Multiple dimensions are separated by a space:

aws cloudwatch put-metric-alarm --alarm-name "Default_Test_Alarm3" --alarm-description "The default example alarm" --namespace "CW EXAMPLE METRICS" --metric-name Default_Test --statistic Average --period 60 --evaluation-periods 3 --threshold 50 --comparison-operator GreaterThanOrEqualToThreshold --dimensions Name=key1,Value=value1 Name=key2,Value=value2
Java
SDK for Java 2.x
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

public static String createAlarm(CloudWatchClient cw, String fileName) { try { // Read values from the JSON file. JsonParser parser = new JsonFactory().createParser(new File(fileName)); com.fasterxml.jackson.databind.JsonNode rootNode = new ObjectMapper().readTree(parser); String customMetricNamespace = rootNode.findValue("customMetricNamespace").asText(); String customMetricName = rootNode.findValue("customMetricName").asText(); String alarmName = rootNode.findValue("exampleAlarmName").asText(); String emailTopic = rootNode.findValue("emailTopic").asText(); String accountId = rootNode.findValue("accountId").asText(); String region = rootNode.findValue("region").asText(); // Create a List for alarm actions. List<String> alarmActions = new ArrayList<>(); alarmActions.add("arn:aws:sns:" + region + ":" + accountId + ":" + emailTopic); PutMetricAlarmRequest alarmRequest = PutMetricAlarmRequest.builder() .alarmActions(alarmActions) .alarmDescription("Example metric alarm") .alarmName(alarmName) .comparisonOperator(ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD) .threshold(100.00) .metricName(customMetricName) .namespace(customMetricNamespace) .evaluationPeriods(1) .period(10) .statistic("Maximum") .datapointsToAlarm(1) .treatMissingData("ignore") .build(); cw.putMetricAlarm(alarmRequest); System.out.println(alarmName + " was successfully created!"); return alarmName; } catch (CloudWatchException | IOException e) { System.err.println(e.getMessage()); System.exit(1); } return ""; }
  • For API details, see PutMetricAlarm in AWS SDK for Java 2.x API Reference.

JavaScript
SDK for JavaScript (v3)
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

Import the SDK and client modules and call the API.

import { PutMetricAlarmCommand } from "@aws-sdk/client-cloudwatch"; import { client } from "../libs/client.js"; const run = async () => { // This alarm triggers when CPUUtilization exceeds 70% for one minute. const command = new PutMetricAlarmCommand({ AlarmName: process.env.CLOUDWATCH_ALARM_NAME, // Set the value of CLOUDWATCH_ALARM_NAME to the name of an existing alarm. ComparisonOperator: "GreaterThanThreshold", EvaluationPeriods: 1, MetricName: "CPUUtilization", Namespace: "AWS/EC2", Period: 60, Statistic: "Average", Threshold: 70.0, ActionsEnabled: false, AlarmDescription: "Alarm when server CPU exceeds 70%", Dimensions: [ { Name: "InstanceId", Value: process.env.EC2_INSTANCE_ID, // Set the value of EC_INSTANCE_ID to the Id of an existing Amazon EC2 instance. }, ], Unit: "Percent", }); try { return await client.send(command); } catch (err) { console.error(err); } }; export default run();

Create the client in a separate module and export it.

import { CloudWatchClient } from "@aws-sdk/client-cloudwatch"; export const client = new CloudWatchClient({});
SDK for JavaScript (v2)
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

// Load the AWS SDK for Node.js var AWS = require("aws-sdk"); // Set the region AWS.config.update({ region: "REGION" }); // Create CloudWatch service object var cw = new AWS.CloudWatch({ apiVersion: "2010-08-01" }); var params = { AlarmName: "Web_Server_CPU_Utilization", ComparisonOperator: "GreaterThanThreshold", EvaluationPeriods: 1, MetricName: "CPUUtilization", Namespace: "AWS/EC2", Period: 60, Statistic: "Average", Threshold: 70.0, ActionsEnabled: false, AlarmDescription: "Alarm when server CPU exceeds 70%", Dimensions: [ { Name: "InstanceId", Value: "INSTANCE_ID", }, ], Unit: "Percent", }; cw.putMetricAlarm(params, function (err, data) { if (err) { console.log("Error", err); } else { console.log("Success", data); } });
Kotlin
SDK for Kotlin
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

suspend fun putMetricAlarm( alarmNameVal: String, instanceIdVal: String, ) { val dimensionOb = Dimension { name = "InstanceId" value = instanceIdVal } val request = PutMetricAlarmRequest { alarmName = alarmNameVal comparisonOperator = ComparisonOperator.GreaterThanThreshold evaluationPeriods = 1 metricName = "CPUUtilization" namespace = "AWS/EC2" period = 60 statistic = Statistic.fromValue("Average") threshold = 70.0 actionsEnabled = false alarmDescription = "An Alarm created by the Kotlin SDK when server CPU utilization exceeds 70%" unit = StandardUnit.fromValue("Seconds") dimensions = listOf(dimensionOb) } CloudWatchClient { region = "us-east-1" }.use { cwClient -> cwClient.putMetricAlarm(request) println("Successfully created an alarm with name $alarmNameVal") } }
  • For API details, see PutMetricAlarm in AWS SDK for Kotlin API reference.

Python
SDK for Python (Boto3)
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

class CloudWatchWrapper: """Encapsulates Amazon CloudWatch functions.""" def __init__(self, cloudwatch_resource): """ :param cloudwatch_resource: A Boto3 CloudWatch resource. """ self.cloudwatch_resource = cloudwatch_resource def create_metric_alarm( self, metric_namespace, metric_name, alarm_name, stat_type, period, eval_periods, threshold, comparison_op, ): """ Creates an alarm that watches a metric. :param metric_namespace: The namespace of the metric. :param metric_name: The name of the metric. :param alarm_name: The name of the alarm. :param stat_type: The type of statistic the alarm watches. :param period: The period in which metric data are grouped to calculate statistics. :param eval_periods: The number of periods that the metric must be over the alarm threshold before the alarm is set into an alarmed state. :param threshold: The threshold value to compare against the metric statistic. :param comparison_op: The comparison operation used to compare the threshold against the metric. :return: The newly created alarm. """ try: metric = self.cloudwatch_resource.Metric(metric_namespace, metric_name) alarm = metric.put_alarm( AlarmName=alarm_name, Statistic=stat_type, Period=period, EvaluationPeriods=eval_periods, Threshold=threshold, ComparisonOperator=comparison_op, ) logger.info( "Added alarm %s to track metric %s.%s.", alarm_name, metric_namespace, metric_name, ) except ClientError: logger.exception( "Couldn't add alarm %s to metric %s.%s", alarm_name, metric_namespace, metric_name, ) raise else: return alarm
  • For API details, see PutMetricAlarm in AWS SDK for Python (Boto3) API Reference.

Ruby
SDK for Ruby
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

# Creates or updates an alarm in Amazon CloudWatch. # # @param cloudwatch_client [Aws::CloudWatch::Client] # An initialized CloudWatch client. # @param alarm_name [String] The name of the alarm. # @param alarm_description [String] A description about the alarm. # @param metric_name [String] The name of the metric associated with the alarm. # @param alarm_actions [Array] A list of Strings representing the # Amazon Resource Names (ARNs) to execute when the alarm transitions to the # ALARM state. # @param namespace [String] The namespace for the metric to alarm on. # @param statistic [String] The statistic for the metric. # @param dimensions [Array] A list of dimensions for the metric, specified as # Aws::CloudWatch::Types::Dimension. # @param period [Integer] The number of seconds before re-evaluating the metric. # @param unit [String] The unit of measure for the statistic. # @param evaluation_periods [Integer] The number of periods over which data is # compared to the specified threshold. # @param theshold [Float] The value against which the specified statistic is compared. # @param comparison_operator [String] The arithmetic operation to use when # comparing the specified statistic and threshold. # @return [Boolean] true if the alarm was created or updated; otherwise, false. # @example # exit 1 unless alarm_created_or_updated?( # Aws::CloudWatch::Client.new(region: 'us-east-1'), # 'ObjectsInBucket', # 'Objects exist in this bucket for more than 1 day.', # 'NumberOfObjects', # ['arn:aws:sns:us-east-1:111111111111:Default_CloudWatch_Alarms_Topic'], # 'AWS/S3', # 'Average', # [ # { # name: 'BucketName', # value: 'doc-example-bucket' # }, # { # name: 'StorageType', # value: 'AllStorageTypes' # } # ], # 86_400, # 'Count', # 1, # 1, # 'GreaterThanThreshold' # ) def alarm_created_or_updated?( cloudwatch_client, alarm_name, alarm_description, metric_name, alarm_actions, namespace, statistic, dimensions, period, unit, evaluation_periods, threshold, comparison_operator ) cloudwatch_client.put_metric_alarm( alarm_name: alarm_name, alarm_description: alarm_description, metric_name: metric_name, alarm_actions: alarm_actions, namespace: namespace, statistic: statistic, dimensions: dimensions, period: period, unit: unit, evaluation_periods: evaluation_periods, threshold: threshold, comparison_operator: comparison_operator ) return true rescue StandardError => e puts "Error creating alarm: #{e.message}" return false end
  • For API details, see PutMetricAlarm in AWS SDK for Ruby API Reference.

SAP ABAP
SDK for SAP ABAP
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository.

TRY. lo_cwt->putmetricalarm( iv_alarmname = iv_alarm_name iv_comparisonoperator = iv_comparison_operator iv_evaluationperiods = iv_evaluation_periods iv_metricname = iv_metric_name iv_namespace = iv_namespace iv_statistic = iv_statistic iv_threshold = iv_threshold iv_actionsenabled = iv_actions_enabled iv_alarmdescription = iv_alarm_description iv_unit = iv_unit iv_period = iv_period it_dimensions = it_dimensions ). MESSAGE 'Alarm created.' TYPE 'I'. CATCH /aws1/cx_cwtlimitexceededfault. MESSAGE 'The request processing has exceeded the limit' TYPE 'E'. ENDTRY.
  • For API details, see PutMetricAlarm in AWS SDK for SAP ABAP API reference.

For a complete list of AWS SDK developer guides and code examples, see Using CloudWatch with an AWS SDK. This topic also includes information about getting started and details about previous SDK versions.