Menu
Amazon CloudWatch
Command Line Reference (API Version 2010-08-01)

mon-put-metric-alarm

Description

Creates or updates an alarm and associates it with the specified Amazon CloudWatch metric. You can also use this command to associate one or more Amazon Simple Notification Service (Amazon SNS) resources with an alarm.

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

Note

When updating an existing alarm, its StateValue is left unchanged.

Syntax

mon-put-metric-alarm AlarmName --comparison-operator value --evaluation-periods value --metric-name value --namespace value --period value --statistic value --threshold value [--actions-enabled value] [--alarm-actions value[,value...] ] [--alarm-description value] [--dimensions "key1=value1,key2=value2..."] [--ok-actions value[,value...] ] [--unit value] [--insufficient-data-actions value[,value...]] [Common Options]

Options

NameDescriptionRequired

AlarmName

Specify the name of the alarm to update or create. The name must be unique within your AWS account. You can also set this value using --alarm-name.

Type: Argument

Valid values: A UTF-8 string.

Default: n/a

Yes

--actions-enabled VALUE

Specify whether actions should be executed when the alarm changes state.

Type: Boolean

Valid values: True or False

Default: True

No

--alarm-actions VALUE1,VALUE2,VALUE3...

Specify the list of actions (up to five) to execute when this alarm transitions into an ALARM state from any other state. Each action is specified as an Amazon Resource Name (ARN). Using alarm actions, you can publish to an Amazon SNS topic, activate an Auto Scaling policy, or stop, terminate, or recover an Amazon EC2 instance.

Note

If you are using an AWS Identity and Access Management (IAM) account to create or modify an alarm, you must have the following Amazon EC2 permissions:

  • ec2:DescribeInstanceStatus and ec2:DescribeInstances for all alarms on Amazon EC2 instance status metrics.

  • ec2:StopInstances for alarms with stop actions.

  • ec2:TerminateInstances for alarms with terminate actions.

  • ec2:DescribeInstanceRecoveryAttribute, and ec2:RecoverInstances for alarms with recover actions.

If you have read/write permissions for Amazon CloudWatch but not for Amazon EC2, you can still create an alarm but the stop or terminate actions won’t be performed on the Amazon EC2 instance. However, if you are later granted permission to use the associated Amazon EC2 APIs, the alarm actions you created earlier will be performed. For more information about IAM permissions, see Permissions and Policies in IAM User Guide.

If you are using an IAM role (e.g., an Amazon EC2 instance profile), you cannot stop or terminate the instance using alarm actions. However, you can still see the alarm state and perform any other actions such as Amazon SNS notifications or Auto Scaling policies.

If you are using temporary security credentials granted using the AWS Security Token Service (AWS STS), you cannot stop or terminate an Amazon EC2 instance using alarm actions.

Type: String

Valid values: An ARN for an Amazon SNS topic, an Auto Scaling policy, or an ARN to stop, terminate, or recover an Amazon EC2 instance.

Default: n/a

No

--alarm-description VALUE

Specify the description of the alarm.

Type: String

Valid values: Any Unicode string between 1 and 255 characters in length.

Default: n/a

No

--comparison-operator VALUE

Specify the comparison operator that will be used to compare a data point to the threshold.

Type: Enumeration

Valid values: one of GreaterThanOrEqualToThreshold, GreaterThanThreshold, LessThanThreshold, or LessThanOrEqualToThreshold

Default: n/a

Yes

--dimensions "key1=value1,key2=value2..."

Specify the dimensions of the metric to create that you want to create an alarm for. You can specify dimensions two ways and the formats can be combined or used interchangeably:

  • One option per dimension e.g. --dimensions "key1=value1" --dimensions "key2=value2"

  • All in one option e.g. --dimensions "key1=value1,key2=value2"

Type: Map

Valid values: A string of the format name=value, where the key is the name of the dimension, and the value is the dimension's value. The dimension names, and values must be an ANSI string between 1 and 250 characters long. A maximum of 10 dimensions are allowed.

Default: n/a

No

--evaluation-periods VALUE

Specify the number of consecutive periods for which the value of the metric will be compared to the threshold to determine alarm status.

Type: Integer

Valid values: A number greater than zero.

Default: n/a

Yes

--metric-name VALUE

Specify the name of the metric on which to alarm.

Type: Argument

Valid values: An ANSI string between 1 and 250 characters in length.

Default: n/a

Yes

--namespace VALUE

Specify the namespace of the metric on which to alarm. For more information about namespaces, see AWS Namespaces.

Type: String

Valid values: An ANSI string between 1 and 250 characters in length.

Default: n/a

Yes

--ok-actions VALUE1,VALUE2,VALUE3...

Specify a list of actions (up to five) to execute when this alarm transitions into an OK state from any other state. Each action is specified as an Amazon Resource Name (ARN).

Type: String

Valid values: A valid ARN identifier.

Default: n/a

No

--period VALUE

Specify the period of metric on which to alarm (in seconds).

Type: Argument

Valid values: A number, in seconds that is a multiple of 60 seconds.

Default: n/a

Yes

--statistic VALUE

Specify the statistic of the metric on which to alarm.

Type: Enumeration

Valid values: SampleCount, Average, Sum, Minimum, or Maximum

Default: n/a

Yes

--threshold VALUE

Specify the threshold that data points will be compared with to determine the alarm state.

Type: Double

Valid values: A double value. All values must be a number between 1E-130 and 1E130.

Default: n/a

Yes

--unit VALUE

Specify the unit of the metric on which to alarm.

Type: Enumeration

Valid values: One of the following:

  • 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

Default: n/a

No

--insufficient-data-actions VALUE1,VALUE2,VALUE3...

Specify the list of actions (up to five) to execute when this alarm transitions into an INSUFFICIENT_DATA state from any other state. Each action is specified as an Amazon Resource Name (ARN).

Type: String

Valid values: A valid ARN identifier.

Default: n/a

No

Common Options

NameDescription

--aws-credential-file VALUE

Specifies the location of the file with your AWS credentials. You can set this value by using the environment variable AWS_CREDENTIAL_FILE. If you define the environment variable or you provide the path to the credential file, the file must exist or the request will fail. All CloudWatch requests must be signed using your access key ID and secret access key.

Type: String

Valid values: A valid path to a file containing your access key ID and secret access key.

Default: Uses the environment variable AWS_CREDENTIAL_FILE, if set.

-C, --ec2-cert-file-path VALUE

Specifies the location of your EC2 certificate file for signing requests. You can use the environment variable EC2_CERT to specify this value.

Type: String

Valid values: A valid file path to the PEM file provided by Amazon EC2 or AWS Identity and Access Management.

Default: Uses the environment variable EC2_CERT, if set.

--connection-timeout VALUE

Specify a connection timeout VALUE (in seconds).

Type: Integer

Valid values: Any positive number.

Default: 30

--delimiter VALUE

What delimiter to use when displaying delimited (long) results.

Type: String

Valid values: Any string.

Default: Comma (,)

--headers

If you are displaying tabular or delimited results, it includes the column headers. If you are showing xml results, it returns the HTTP headers from the service request, if applicable.

Type: Flag

Valid values: When present, shows headers.

Default: The --headers option is off by default.

-I, --access-key-id VALUE

Specifies an access key ID of VALUE that will be used, in conjunction with the secret key, to sign the request. This must be used in conjunction with --secret-key, otherwise the option will be ignored. All requests to CloudWatch must be signed, otherwise the request will be rejected.

Type: String

Valid values: A valid access key ID.

Default: None

-K, --ec2-private-key-file-path VALUE

Specifies a private key in the file VALUE that will be used to sign the request. Using public/private keys will cause the CLI to use SOAP. The request will be signed with a public certificate and private key. This parameter must be used in conjunction with EC2_CERT, otherwise the value will be ignored. The value of the environment variable EC2_PRIVATE_KEY will be used if it is set, and this option is not specified. This option is ignored if the environment variable AWS_CREDENTIAL_FILE is set, or --aws-credentials-file is used. All requests to CloudWatch must be signed, otherwise the request will be rejected.

Type: String

Valid values: The path to a valid ASN.1 private key.

Default: None

--region VALUE

Specifies which region requests are directed to. You can use the environment variable EC2_REGION to specify the value. The region is used to create the URL used to call CloudWatch, and must be a valid Amazon Web Services (AWS) region.

Type: String

Valid values: Any AWS region, for example, us-east-1.

Default: us-east-1, unless the EC2_REGION environment variable is set.

S, --secret-key VALUE

Specify a secret key of VALUE that will be used, in conjunction with an access key ID, to sign the request. This must be used in conjunction with the --access-key-id, otherwise this option will be ignored.

Type: String

Valid values: Your access key ID.

Default: None

--show-empty-fields

Show empty fields using (nil) as a placeholder to indicate that this data was not requested.

Type: Flag

Valid values: None

Default: Empty fields are not shown by default.

--show-request

Displays the URL the CLI uses to call AWS.

Type: Flag

Valid values: None

Default: false

--show-table, --show-long, --show-xml, --quiet

Specify how the results are displayed: in a table, delimited (long), XML, or no output (quiet). The --show-table display shows a subset of the data in fixed column-width form; --show-long shows all of the returned values delimited by a character; --show-xml is the raw return from the service; and --quiet suppresses all standard output. All options are mutually exclusive, with the priority --show-table, --show-long, --show-xml, and -–quiet.

Type: Flag

Valid values: None

Default: --show-table

-U, --url VALUE

Specifies the URL used to contact CloudWatch. You can set this value using the environment variable AWS_CLOUDWATCH_URL. This value will be used in conjunction with --region to create the expected URL. This option will override the URL for the service call with VALUE.

Type: String

Valid values: A valid HTTP or HTTPS URL.

Default: Uses the value specified in AWS_CLOUDWATCH_URL, if set.

Output

This command creates or updates an alarm associated with the specified metric.

The Amazon CloudWatch CLI displays errors on stderr.

Examples

Example Request

This example creates an alarm my-alarm which publishes a message to a topic when CPU utilization of an EC2 instances exceeds 90 percent for three consecutive one minute periods.

PROMPT> mon-put-metric-alarm --alarm-name my-alarm --alarm-description
          "some desc" --metric-name CPUUtilization --namespace AWS/EC2 --statistic Average  --period 60 --threshold 90 --comparison-operator GreaterThanThreshold  --dimensions InstanceId=i-abcdef --evaluation-periods 3  --unit Percent --alarm-actions arn:aws:sns:us-east-1:1234567890:my-topic
                      
                       

Related Topics

Related Action

Related Command