Amazon CloudWatch
Command Line Reference
API Version 2010-08-01
Amazon CloudWatch: Command Line Reference
Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon.
Table of Contents
Welcome ... 1
Set up the command line interface ... 2
Command line interface reference ... 3
mon-cmd ... 3
Description ... 3
Syntax ... 3
Output ... 3
Examples ... 4
Related Topics ... 4
mon-delete-alarms ... 4
Description ... 4
Syntax ... 4
Options ... 5
Common options ... 5
Output ... 8
Examples ... 8
Related topics ... 9
mon-describe-alarm-history ... 9
Description ... 9
Syntax ... 9
Options ... 9
Common options ... 10
Output ... 13
Examples ... 13
Related topics ... 13
mon-describe-alarms ... 14
Description ... 14
Syntax ... 14
Options ... 14
Common options ... 15
Output ... 18
Examples ... 18
Related topics ... 19
mon-describe-alarms-for-metric ... 19
Description ... 19
Syntax ... 19
Options ... 19
Common options ... 23
Output ... 25
Examples ... 26
Related topics ... 26
mon-disable-alarm-actions ... 27
Description ... 27
Syntax ... 27
Options ... 27
Common options ... 27
Output ... 30
Examples ... 30
Related topics ... 30
mon-enable-alarm-actions ... 31
Description ... 31
Syntax ... 31
Options ... 31
Common options ... 31
Output ... 34
Examples ... 34
Related topics ... 34
mon-get-stats ... 35
Description ... 35
Syntax ... 35
Options ... 35
Common options ... 39
Output ... 41
Examples ... 42
Related topics ... 43
mon-list-metrics ... 43
Description ... 43
Syntax ... 43
Options ... 43
Common options ... 44
Output ... 47
Examples ... 47
Related topics ... 48
mon-put-data ... 48
Description ... 48
Syntax ... 49
Options ... 49
Common options ... 52
Output ... 55
Examples ... 55
Related topics ... 55
mon-put-metric-alarm ... 55
Description ... 55
Syntax ... 56
Options ... 56
Common options ... 61
Output ... 64
Examples ... 64
Related topics ... 64
mon-set-alarm-state ... 64
Description ... 64
Syntax ... 64
Options ... 65
Common options ... 65
Output ... 68
Examples ... 69
Related topics ... 69
mon-version ... 69
Description ... 69
Syntax ... 69
Output ... 69
Examples ... 69
Related topics ... 70
Document history ... 71
Welcome
As of November 7, 2017, we are no longer supporting the CloudWatch command line interface with new functionality. It is not available for download. The CloudWatch CLI reference documentation is still available.
We encourage customers to use the AWS Command Line Interface. The AWS CLI includes all existing and new CloudWatch commands, and is the only command line interface being updated. For information about installing the AWS CLI, see Installing the AWS Command Line Interface. For information about CloudWatch commands in the AWS CLI, see cloudwatch.
Set up the command line interface
As of November 7, 2017, we are no longer supporting the CloudWatch command line interface with new functionality. It is not available for download. The CloudWatch CLI reference documentation is still available.
We encourage customers to use the AWS Command Line Interface. The AWS CLI includes all existing and new CloudWatch commands, and is the only command line interface being updated. For information about installing the AWS CLI, see Installing the AWS Command Line Interface. For information about CloudWatch commands in the AWS CLI, see cloudwatch.
mon-cmd
Amazon CloudWatch command line interface reference
AWS provides two sets of command line tools that each support CloudWatch. This section describes the CloudWatch command line interface (CLI).
As of November 7, 2017, we are no longer supporting this CloudWatch command line interface with new functionality and it is no longer available for download. We encourage customers to use the AWS Command Line Interface to control and automate CloudWatch on Windows, Mac, and Linux. We also offer the AWS Tools for Windows PowerShell if you prefer to script in the PowerShell environment.
Commands
• mon-cmd (p. 3)
• mon-delete-alarms (p. 4)
• mon-describe-alarm-history (p. 9)
• mon-describe-alarms (p. 14)
• mon-describe-alarms-for-metric (p. 19)
• mon-disable-alarm-actions (p. 27)
• mon-enable-alarm-actions (p. 31)
• mon-get-stats (p. 35)
• mon-list-metrics (p. 43)
• mon-put-data (p. 48)
• mon-put-metric-alarm (p. 55)
• mon-set-alarm-state (p. 64)
• mon-version (p. 69)
mon-cmd
Description
Lists all the other CloudWatch commands. For help on a specific command, use the following command:
commandname --help
Syntax
mon-cmd
Output
This command lists all of the Amazon CloudWatch commands in a table.
The Amazon CloudWatch CLI displays errors on stderr.
Examples
Examples
Example Request
This example lists all of the Amazon CloudWatch commands.
mon-cmd
Command Name Description --- --- help
mon-delete-alarms Delete alarms.
mon-describe-alarm-history Show the history of alarm transitions and actions taken.
mon-describe-alarms List alarms and show detailed alarm configuration.
mon-describe-alarms-for-metric Show alarms for a given metric.
mon-disable-alarm-actions Disable all actions for a given alarm.
mon-enable-alarm-actions Enable all actions for a given alarm.
mon-get-stats Get metric statistics.
mon-list-metrics List user's metrics.
mon-put-data Put metric data.
mon-put-metric-alarm Create a new alarm or update an existing one.
mon-set-alarm-state Manually set the state of an alarm.
mon-version Prints the version of the CLI tool and API.
For help on a specific command, type '<commandname> --help'
Related Topics
Download
• Set up the command line interface (p. 2)
Related Command
• mon-version Command (p. 69)
mon-delete-alarms
Description
Deletes the specified alarms.
Syntax
mon-delete-alarms [AlarmNames [AlarmNames ...]] [Common Options]
Options
Options
Name Description
AlarmNames AlarmNames The names of the alarms to delete, separated by a space.
You can also set this value using --alarm-name.
Type: Argument
Valid values: The name of the alarm, which must between 1 and 255 characters in length.
Default: n/a Required: Yes
-f, --force Deletes the alarms without prompting you for
confirmation. By default, the mon-delete-alarms command prompts you for confirmation before deleting alarms.
Type: Flag Valid values: n/a
Default: You are prompted before deleting each alarm.
Required: No
Common options
Name Description
--aws-credential-file VALUE The location of the file with your AWS credentials.
You can set this value 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 fails. 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 The location of your EC2 certificate file for signing requests. You can use the environment variable EC2_CERT to specify this value.
Type: String
Common options
Name Description
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 The connection timeout value, in seconds.
Type: Integer
Valid values: Any positive number.
Default: 30
--delimiter VALUE The 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, include the column headers. If you are showing XML results, return 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 The access key ID 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 is ignored. All requests to CloudWatch must be signed, otherwise the request is rejected.
Type: String
Valid values: A valid access key ID.
Default: None
Common options
Name Description
-K, --ec2-private-key-file-path VALUE
The private key that will be used to sign the request.
Using public/private keys causes the CLI to use SOAP.
The request is signed with a public certificate and private key. This parameter must be used in conjunction with EC2_CERT, otherwise the value is 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 is rejected.
Type: String
Valid values: The path to a valid ASN.1 private key.
Default: None
--region VALUE The 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 The secret access key that will be used to sign the request, in conjunction with an access key ID. This parameter must be used in conjunction with --access-key-id, otherwise this option is ignored.
Type: String
Valid values: Your access key ID.
Default: None
--show-empty-fields Shows 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
Output
Name Description
--show-table, --show-long, -- show-xml, --quiet
Specifies 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 The URL used to contact CloudWatch. You can set this value using the environment variable
AWS_CLOUDWATCH_URL. This value is used in conjunction with --region to create the expected URL. This option overrides the URL for the service call.
Type: String
Valid values: A valid HTTP or HTTPS URL.
Default: Uses the value specified in AWS_CLOUDWATCH_URL, if set.
Output
This command deletes an alarm.
The Amazon CloudWatch CLI displays errors on stderr.
Examples
Example request
This example deletes the alarm named my-alarm.
mon-delete-alarms --alarm-name my-alarm
Example request
This example deletes multiple alarms.
mon-delete-alarms --alarm-name my-alarm1 my-alarm2 my-alarm3
Related topics
Related topics
Download
• Set up the command line interface (p. 2)
Related action
• DeleteAlarms
Related commands
• mon-put-metric-alarm (p. 55)
• mon-disable-alarm-actions (p. 27)
• mon-enable-alarm-actions (p. 31)
mon-describe-alarm-history
Description
Retrieves the history for the specified alarm. You can filter alarms by date range or item type. If you don't specify an alarm name, Amazon CloudWatch returns histories for all of your alarms.
NoteAmazon CloudWatch retains the history of active and deleted alarms for two weeks.
Syntax
mon-describe-alarm-history [AlarmNames [AlarmNames ...]] [--end-date value] [-- history-item-type value] [--start-date value] [Common Options]
Options
Name Description
AlarmName AlarmNames The names of the alarms, separated by spaces. If you don't specify an alarm name, this command returns the histories of all your alarms. You can also set this value using -- alarm-name.
Type: Argument
Valid values: Any string between 1 and 255 characters in length.
Default: n/a Required: No
--end-date VALUE The end of the date range for history.
Type: Date
Common options
Name Description
Valid values: Date in YYYY-MM-DD format.
Default: The current date.
Required: No
--history-item-type VALUE The type of history items to retrieve. By default, all types are returned.
Type: Enumeration
Valid values: ConfigurationUpdate, StateUpdate, or Action Default: All types are returned.
Required: No
--start-date VALUE The start of the date range for history. By default it extends to all available history.
Type: Date
Valid values: Date in YYYY-MM-DD format.
Default: All available history.
Required: No
Common options
Name Description
--aws-credential-file VALUE The location of the file with your AWS credentials.
You can set this value 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 fails. 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 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.
Common options
Name Description
Default: Uses the environment variable EC2_CERT, if set.
--connection-timeout VALUE The connection timeout value, in seconds.
Type: Integer
Valid values: Any positive number.
Default: 30
--delimiter VALUE The 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, include the column headers. If you are showing XML results, return 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 The access key ID 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 is ignored. All requests to CloudWatch must be signed, otherwise the request is rejected.
Type: String
Valid values: A valid access key ID.
Default: None -K, --ec2-private-key-file-path
VALUE
The private key that will be used to sign the request.
Using public/private keys causes the CLI to use SOAP.
The request is signed with a public certificate and private key. This parameter must be used in conjunction with EC2_CERT, otherwise the value is 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 is rejected.
Type: String
Valid values: The path to a valid ASN.1 private key.
Default: None
Common options
Name Description
--region VALUE The 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 The secret access key that will be used to sign the request, in conjunction with an access key ID. This parameter must be used in conjunction with --access-key-id, otherwise this option is ignored.
Type: String
Valid values: Your access key ID.
Default: None
--show-empty-fields Shows 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
Specifies 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
Output
Name Description
-U, --url VALUE The URL used to contact CloudWatch. You can set this value using the environment variable
AWS_CLOUDWATCH_URL. This value is used in conjunction with --region to create the expected URL. This option overrides the URL for the service call.
Type: String
Valid values: A valid HTTP or HTTPS URL.
Default: Uses the value specified in AWS_CLOUDWATCH_URL, if set.
Output
This command returns a table that contains the following:
• ALARM - The alarm name.
• TIMESTAMP - The timestamp.
• TYPE - The type of event, one of ConfigurationUpdate, StateUpdate and Action.
• SUMMARY - A human-readable summary of history event.
• DATA - Detailed data about the event in machine-readable JSON format. This column appears only in the --show-long view.
The Amazon CloudWatch CLI displays errors on stderr.
Examples
Example request
This example describes all history items for the alarm my-alarm.
mon-describe-alarm-history--alarm-name my-alarm --headers
This is an example output of this command.
ALARM TIMESTAMP TYPE SUMMARY
my-alarm 2013-05-07T18:46:16.121Z Action Published a notification to arn:aws:sns:...
my-alarm 2013-05-07T18:46:16.118Z StateUpdate Alarm updated from INSUFFICIENT_DATA to OK
my-alarm 2013-05-07T18:46:07.362Z ConfigurationUpdate Alarm "my-alarm" created
Related topics
Download
• Set up the command line interface (p. 2)
mon-describe-alarms
Related action
• DescribeAlarmHistory
Related commands
• mon-describe-alarms (p. 14)
• mon-describe-alarms-for-metric (p. 19)
mon-describe-alarms
Description
Gets information on the specified alarms. If you don't specify an alarm name, this command returns information about all of your alarms. You can retrieve alarms by using only the alarm name prefix, the alarm state, or an action prefix.
Syntax
mon-describe-alarms [AlarmNames [AlarmNames ...]] [--action-prefix value] [-- alarm-name-prefix value] [--state-value value] [Common Options]
Options
Name Description
AlarmNames AlarmNames The names of the alarms. You can also set this value using --alarm-name. You can specify this option multiple times.
Type: Argument
Valid values: An existing alarm name, otherwise no response is returned.
Default: n/a, displays all alarms by default.
Required: No
--action-prefix VALUE Prefix of action names.
Type: Argument
Valid values: The prefix of an existing action name, in ARN format.
Default: n/a, display the first action by default.
Required: No
--alarm-name-prefix VALUE Prefix of alarm names.
Type: Argument
Common options
Name Description
Valid values: The prefix of an existing alarm name.
Default: n/a Required: No
--state-value VALUE The state of the alarm.
Type: Enumeration
Valid values: OK, ALARM, or INSUFFICIENT_DATA Default: All alarm states.
Required: No
Common options
Name Description
--aws-credential-file VALUE The location of the file with your AWS credentials.
You can set this value 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 fails. 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 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 The connection timeout value, in seconds.
Type: Integer
Valid values: Any positive number.
Default: 30
Common options
Name Description
--delimiter VALUE The 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, include the column headers. If you are showing XML results, return 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 The access key ID 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 is ignored. All requests to CloudWatch must be signed, otherwise the request is rejected.
Type: String
Valid values: A valid access key ID.
Default: None -K, --ec2-private-key-file-path
VALUE
The private key that will be used to sign the request.
Using public/private keys causes the CLI to use SOAP.
The request is signed with a public certificate and private key. This parameter must be used in conjunction with EC2_CERT, otherwise the value is 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 is rejected.
Type: String
Valid values: The path to a valid ASN.1 private key.
Default: None
Common options
Name Description
--region VALUE The 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 The secret access key that will be used to sign the request, in conjunction with an access key ID. This parameter must be used in conjunction with --access-key-id, otherwise this option is ignored.
Type: String
Valid values: Your access key ID.
Default: None
--show-empty-fields Shows 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
Specifies 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
Output
Name Description
-U, --url VALUE The URL used to contact CloudWatch. You can set this value using the environment variable
AWS_CLOUDWATCH_URL. This value is used in conjunction with --region to create the expected URL. This option overrides the URL for the service call.
Type: String
Valid values: A valid HTTP or HTTPS URL.
Default: Uses the value specified in AWS_CLOUDWATCH_URL, if set.
Output
This command returns a table that contains the following:
• ALARM - Alarm name.
• DESCRIPTION - The alarm description. This column appears only in the --show-long view.
• STATE - The alarm state.
• STATE_REASON - A human-readable reason for state. This column appears only in the --show-long view.
• STATE_REASON_DATA - A machine-readable reason for state (JSON format). This column appears only in the --show-long view.
• ENABLED - Enables or disables actions. This column appears only in the --show-long view.
• OK_ACTIONS - The action to execute on OK status. This column appears only in the --show-long view.
• ALARM_ACTIONS - The action to execute on ALARM status.
• INSUFFICIENT_DATA_ACTIONS - The action to execute on INSUFFICIENT_DATA status. This column appears only in the --show-long view.
• NAMESPACE - A namespace for the metric.
• METRIC_NAME - The name of the metric.
• DIMENSIONS - The metric dimensions. This column appears only in the --show-long view.
• PERIOD - The period.
• STATISTIC - The statistic (Average, Minimum, Maximum, Sum, SampleCount).
• EXTENDEDSTATISTIC - The percentile statistic.
• UNIT - The unit. This column appears only in the --show-long view.
• EVAL_PERIODS - The number of periods to evaluate the metric.
• COMPARISON - The comparison operator.
• THRESHOLD - The threshold.
The Amazon CloudWatch CLI displays errors on stderr.
Examples
Example request
This example describes all of your alarms whose name starts with my-alarm.
Related topics
mon-describe-alarms --alarm-name-prefix my-alarm --headers
This is an example output of this command.
ALARM STATE ALARM_ACTIONS NAMESPACE METRIC_NAME PERIOD STATISTIC EVAL_PERIODS COMPARISON THRESHOLD
my-alarm1 OK arn:aws:sns:.. AWS/EC2 CPUUtilization 60 Average 3 GreaterThanThreshold 100.0
my-alarm2 OK arn:aws:sns:.. AWS/EC2 CPUUtilization 60 Average 5 GreaterThanThreshold 80o.0
Related topics
Download
• Set up the command line interface (p. 2)
Related action
• DescribeAlarms
Related commands
• mon-describe-alarm-history (p. 9)
• mon-describe-alarms-for-metric (p. 19)
mon-describe-alarms-for-metric
Description
Gets information about the alarms associated with the specified metric.
Syntax
mon-describe-alarms-for-metric --metric-name value --namespace value [-- dimensions "key1=value1,key2=value2..."] [--period value] [--statistic value]
[--extendedstatistic value] [--unit value] [Common Options]
Options
Name Description
--dimensions -
"key1=value1,key2=value2...
The dimensions associated with the metric. You can specify dimensions two ways and the formats can be combined or used interchangeably:
• One option per dimension: --dimensions "key1=value1"
--dimensions "key2=value2"
Options
Name Description
• All in one option: --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 Required: No
--metric-name VALUE The name of the metric whose associated alarms you want to search for.
Type: Argument
Valid values: A valid metric name between 1 and 255 characters in length.
Default: n/a Required: Yes
--namespace VALUE The namespace of the metric associated with the alarm.
For more information about namespaces, see AWS Namespaces.
Type: String
Valid values: A valid namespace between 1 and 250 characters in length.
Default: n/a Required: Yes
--period VALUE The period to filter the alarms by. Only alarms that evaluate metrics at this period will be included in the results. If this isn't specified alarms on any period will be included .
Type: Argument
Valid values: A number, in seconds that is a multiple of 60 seconds.
Default: n/a Required: No
Options
Name Description
--statistic VALUE The statistic to filter alarms by. Only alarms on the specified statistic will be included. If this parameter isn't specified, alarms on any statistic are included.
Type: Enumeration
Valid values: SampleCount, Average, Sum, Minimum or Maximum
Default: n/a Required: No
--extendedstatistic VALUE The percentile statistic to filter alarms by. Only alarms on the specified statistic are included. If this parameter isn't specified, alarms on any statistic are included.
Type: String
Valid values: Any percentile, with up to two decimal places (for example, p95.45).
Default: n/a Required: No
Options
Name Description
--unit VALUE The unit to filter the alarms by. Only alarms on the specified statistics will be included. If this isn't specified than alarms on any units will be included. If the alarm doesn't have a unit specified than the only way to search for the alarm is to omit this option.
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 Required: No
Common options
Common options
Name Description
--aws-credential-file VALUE The location of the file with your AWS credentials.
You can set this value 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 fails. 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 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 The connection timeout value, in seconds.
Type: Integer
Valid values: Any positive number.
Default: 30
--delimiter VALUE The 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, include the column headers. If you are showing XML results, return 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.
Common options
Name Description
-I, --access-key-id VALUE The access key ID 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 is ignored. All requests to CloudWatch must be signed, otherwise the request is rejected.
Type: String
Valid values: A valid access key ID.
Default: None -K, --ec2-private-key-file-path
VALUE
The private key that will be used to sign the request.
Using public/private keys causes the CLI to use SOAP.
The request is signed with a public certificate and private key. This parameter must be used in conjunction with EC2_CERT, otherwise the value is 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 is rejected.
Type: String
Valid values: The path to a valid ASN.1 private key.
Default: None
--region VALUE The 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 The secret access key that will be used to sign the request, in conjunction with an access key ID. This parameter must be used in conjunction with --access-key-id, otherwise this option is ignored.
Type: String
Valid values: Your access key ID.
Default: None
Output
Name Description
--show-empty-fields Shows 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
Specifies 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 The URL used to contact CloudWatch. You can set this value using the environment variable
AWS_CLOUDWATCH_URL. This value is used in conjunction with --region to create the expected URL. This option overrides the URL for the service call.
Type: String
Valid values: A valid HTTP or HTTPS URL.
Default: Uses the value specified in AWS_CLOUDWATCH_URL, if set.
Output
This command returns a table that contains the following:
• ALARM - Alarm name.
• DESCRIPTION - The alarm description. This column appears only in the --show-long view.
• STATE - The alarm state.
• STATE_REASON - A human-readable reason for state. This column appears only in the --show-long view.
Examples
• STATE_REASON_DATA - A machine-readable reason for state (JSON format). This column appears only in the --show-long view.
• ENABLED - Enables or disables actions. This column appears only in the --show-long view.
• OK_ACTIONS - The action to execute on OK status. This column appears only in the --show-long view.
• ALARM_ACTIONS - The action to execute on ALARM status.
• INSUFFICIENT_DATA_ACTIONS - The action to execute on INSUFFICIENT_DATA status. This column appears only in the --show-long view.
• NAMESPACE - A namespace for the metric.
• METRIC_NAME - The name of the metric.
• DIMENSIONS - The metric dimensions. This column appears only in the --show-long view.
• PERIOD - The period.
• STATISTIC - The statistic (Average, Minimum, Maximum, Sum, SampleCount).
• EXTENDEDSTATISTIC - The percentile statistic.
• UNIT - The unit. This column appears only in the --show-long view.
• EVAL_PERIODS - The number of periods to evaluate the metric.
• COMPARISON - The comparison operator.
• THRESHOLD - The threshold.
The Amazon CloudWatch CLI displays errors on stderr.
Examples
Example request
This example describes an alarm for a given metric.
mon-describe-alarms-for-metric--metric-name CPUUtilization --namespace AWS/EC2 -- dimensions InstanceId=i-abcdef
This is an example output of this command.
ALARM STATE ALARM_ACTIONS NAMESPACE METRIC_NAME PERIOD STATISTIC EVAL_PERIODS COMPARISON THRESHOLD
my-alarm1 OK arn:aws:sns:.. AWS/EC2 CPUUtilization 60 Average 3 GreaterThanThreshold 100.0
my-alarm2 OK arn:aws:sns:.. AWS/EC2 CPUUtilization 60 Average 5 GreaterThanThreshold 80.0
Related topics
Download
• Set up the command line interface (p. 2)
Related action
• DescribeAlarmForMetric
mon-disable-alarm-actions
Related commands
• mon-describe-alarm-history (p. 9)
• mon-describe-alarms (p. 14)
mon-disable-alarm-actions
Description
Disables all actions for the specified alarms.
Syntax
mon-disable-alarm-actions [AlarmNames [AlarmNames ...]] [Common Options]
Options
Name Description
AlarmNames AlarmNames The names of the alarms. You can also set this value using --alarm-name.
Type: Argument
Valid values: A valid list of alarm names.
Default: n/a Required: Yes
Common options
Name Description
--aws-credential-file VALUE The location of the file with your AWS credentials.
You can set this value 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 fails. 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.
Common options
Name Description
-C, --ec2-cert-file-path VALUE 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 The connection timeout value, in seconds.
Type: Integer
Valid values: Any positive number.
Default: 30
--delimiter VALUE The 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, include the column headers. If you are showing XML results, return 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 The access key ID 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 is ignored. All requests to CloudWatch must be signed, otherwise the request is rejected.
Type: String
Valid values: A valid access key ID.
Default: None
Common options
Name Description
-K, --ec2-private-key-file-path VALUE
The private key that will be used to sign the request.
Using public/private keys causes the CLI to use SOAP.
The request is signed with a public certificate and private key. This parameter must be used in conjunction with EC2_CERT, otherwise the value is 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 is rejected.
Type: String
Valid values: The path to a valid ASN.1 private key.
Default: None
--region VALUE The 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 The secret access key that will be used to sign the request, in conjunction with an access key ID. This parameter must be used in conjunction with --access-key-id, otherwise this option is ignored.
Type: String
Valid values: Your access key ID.
Default: None
--show-empty-fields Shows 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
Output
Name Description
--show-table, --show-long, -- show-xml, --quiet
Specifies 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 The URL used to contact CloudWatch. You can set this value using the environment variable
AWS_CLOUDWATCH_URL. This value is used in conjunction with --region to create the expected URL. This option overrides the URL for the service call.
Type: String
Valid values: A valid HTTP or HTTPS URL.
Default: Uses the value specified in AWS_CLOUDWATCH_URL, if set.
Output
This command disables alarm actions for the specified alarms.
The Amazon CloudWatch CLI displays errors on stderr.
Examples
Example request
This example disables all actions for an alarm called my-alarm.
mon-disable-alarm-actions --alarm-name my-alarm
Related topics
Download
• Set up the command line interface (p. 2)
Related action
• DisableAlarmActions
mon-enable-alarm-actions
Related commands
• mon-enable-alarm-actions (p. 31)
• mon-delete-alarms (p. 4)
mon-enable-alarm-actions
Description
Enables all actions for the specified alarms.
Syntax
mon-enable-alarm-actions [AlarmNames [AlarmNames ...]] [Common Options]
Options
Name Description
AlarmNames AlarmNames The names of the alarms. You can also set this value using --alarm-name.
Type: Argument
Valid values: A valid list of alarm names.
Default: n/a Required: Yes
Common options
Name Description
--aws-credential-file VALUE The location of the file with your AWS credentials.
You can set this value 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 fails. 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.
Common options
Name Description
-C, --ec2-cert-file-path VALUE 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 The connection timeout value, in seconds.
Type: Integer
Valid values: Any positive number.
Default: 30
--delimiter VALUE The 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, include the column headers. If you are showing XML results, return 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 The access key ID 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 is ignored. All requests to CloudWatch must be signed, otherwise the request is rejected.
Type: String
Valid values: A valid access key ID.
Default: None
Common options
Name Description
-K, --ec2-private-key-file-path VALUE
The private key that will be used to sign the request.
Using public/private keys causes the CLI to use SOAP.
The request is signed with a public certificate and private key. This parameter must be used in conjunction with EC2_CERT, otherwise the value is 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 is rejected.
Type: String
Valid values: The path to a valid ASN.1 private key.
Default: None
--region VALUE The 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 The secret access key that will be used to sign the request, in conjunction with an access key ID. This parameter must be used in conjunction with --access-key-id, otherwise this option is ignored.
Type: String
Valid values: Your access key ID.
Default: None
--show-empty-fields Shows 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
Output
Name Description
--show-table, --show-long, -- show-xml, --quiet
Specifies 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 The URL used to contact CloudWatch. You can set this value using the environment variable
AWS_CLOUDWATCH_URL. This value is used in conjunction with --region to create the expected URL. This option overrides the URL for the service call.
Type: String
Valid values: A valid HTTP or HTTPS URL.
Default: Uses the value specified in AWS_CLOUDWATCH_URL, if set.
Output
This command enables alarm actions for the specified alarms.
The Amazon CloudWatch CLI displays errors on stderr.
Examples
Example request
This example enables all actions for the alarm named my-alarm.
mon-enable-alarm-actions --alarm-name my-alarm
Related topics
Download
• Set up the command line interface (p. 2)
Related action
• EnableAlarmActions
mon-get-stats
Related commands
• mon-disable-alarm-actions (p. 27)
• mon-delete-alarms (p. 4)
mon-get-stats
Description
Gets time-series data for the specified statistics.
NoteWhen you create a new metric using the mon-put-data command, it can take up to two minutes before you can retrieve statistics on the new metric using the mon-get-stats command. However, it can take up to fifteen minutes before the new metric appears in the list of metrics retrieved using the mon-list-metrics command.
Syntax
mon-get-stats MetricName --namespace value --statistics value[,value...] [-- dimensions "key1=value1,key2=value2..." ] [--end-time value] [--period value]
[--start-time value] [--unit value] [Common Options]
Options
Name Description
MetricName The name of the metric. You can also set this value using -- metric-name.
Type: Argument
Valid values: Any valid metric name between 1 and 255 characters.
Default: n/a Required: Yes --dimensions
"key1=value1,key2=value2..."
The dimensions of the metric. You can specify dimensions two ways and the formats can be combined or used interchangeably:
• One option per dimension: --dimensions "key1=value1" -- dimensions "key2=value2"
• All in one option: --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
Options
Name Description
be an ANSI string between 1 and 250 characters long. A maximum of 10 dimensions are allowed.
Default: n/a Required: No
--end-time VALUE The latest allowed timestamp for returned data points.
The ending time is exclusive. Timestamps are specified using ISO8601 combined format. For example the date and time July 30th, 2013 at 12:30:00 PST would be represented as 2013-07-30T12:30:00-07:00, or in UTC:
2013-07-30T19:30:00Z. The highest resolution that can be returned by CloudWatch is 1 minute, as such all timestamps are rounded down to the nearest minute.
Type: Argument
Valid values: A valid timestamp represented in ISO8601 format with time zone offset, or UTC indicator.
Default: The current date/time.
Required: No
-n, --namespace VALUE The namespace of the metric. For more information about namespaces, see AWS Namespaces.
Type: String
Valid values: A valid namespace between 1 and 250 characters in length.
Default: n/a Required: Yes
--period VALUE The granularity, in seconds, to retrieve statistics for. The period must be at least 60 seconds and must be a multiple of 60.
Type: Argument
Valid values: A number, in seconds that is a multiple of 60 seconds.
Default: 60 seconds.
Required: No -s, --statistics
VALUE1,VALUE2,VALUE3...
The statistics to be returned for the specified metric.
Type: Enumeration
Valid values: Average, Sum, Maximum, or Minimum Default: n/a
Required: Yes
Options
Name Description
--start-time VALUE The first allowed timestamp for returned data points.
The starting time is inclusive. Timestamps are specified using ISO8601 combined format. For example the date and time July 30th, 2013 at 12:30:00 PST would be represented as 2013-07-30T12:30:00-07:00, or in UTC:
2013-07-30T19:30:00Z. The highest resolution that can be returned by CloudWatch is 1 minute, as such all timestamps are rounded down to the nearest minute.
Type: Argument
Valid values: A valid timestamp represented in ISO8601 format with time zone offset, or UTC indicator.
Default: One hour before the current time.
Required: No
Options
Name Description
--unit VALUE The unit to retrieve the metrics for. Metrics may be reported in multiple units, this retrieve a specific unit for a given metric. Not requesting a unit will result in all units being returned. If the metric is only ever reported with one unit this will have no effect.
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 Required: No
Common options
Common options
Name Description
--aws-credential-file VALUE The location of the file with your AWS credentials.
You can set this value 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 fails. 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 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 The connection timeout value, in seconds.
Type: Integer
Valid values: Any positive number.
Default: 30
--delimiter VALUE The 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, include the column headers. If you are showing XML results, return 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.
Common options
Name Description
-I, --access-key-id VALUE The access key ID 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 is ignored. All requests to CloudWatch must be signed, otherwise the request is rejected.
Type: String
Valid values: A valid access key ID.
Default: None -K, --ec2-private-key-file-path
VALUE
The private key that will be used to sign the request.
Using public/private keys causes the CLI to use SOAP.
The request is signed with a public certificate and private key. This parameter must be used in conjunction with EC2_CERT, otherwise the value is 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 is rejected.
Type: String
Valid values: The path to a valid ASN.1 private key.
Default: None
--region VALUE The 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 The secret access key that will be used to sign the request, in conjunction with an access key ID. This parameter must be used in conjunction with --access-key-id, otherwise this option is ignored.
Type: String
Valid values: Your access key ID.
Default: None
Output
Name Description
--show-empty-fields Shows 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
Specifies 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 The URL used to contact CloudWatch. You can set this value using the environment variable
AWS_CLOUDWATCH_URL. This value is used in conjunction with --region to create the expected URL. This option overrides the URL for the service call.
Type: String
Valid values: A valid HTTP or HTTPS URL.
Default: Uses the value specified in AWS_CLOUDWATCH_URL, if set.
Output
This command returns a table that contains the following:
• Time - The time the metrics were taken.
• SampleCount - No description available for this column.
• Average - The average value.
• Sum - The sum of values.
• Minimum - The minimum observed value.
Examples
• Maximum - The maximum observed value.
• Unit - The unit of the metric.
The Amazon CloudWatch CLI displays errors on stderr.
Examples
Example request
This example returns the average, minimum, and maximum CPU utilization for EC2 instance i-c07704a9, at 1 hour resolution.
mon-get-stats CPUUtilization --start-time 2013-02-14T23:00:00.000Z --end-time
2013-03-14T23:00:00.000Z --period 3600 --statistics "Average,Minimum,Maximum" --namespace "AWS/EC2" --dimensions "InstanceId=i-c07704a9"
This is an example of an output of the Samples and Average metrics at one minute resolution.
Time Samples Average Unit 2013-05-19 00:03:00 2.0 0.19 Percent 2013-05-19 00:04:00 2.0 0 Percent 2013-05-19 00:05:00 2.0 0 Percent 2013-05-19 00:06:00 2.0 0 Percent 2013-05-19 00:07:00 2.0 0 Percent 2013-05-19 00:08:00 2.0 0 Percent 2013-05-19 00:09:00 2.0 0 Percent 2013-05-19 00:10:00 2.0 0 Percent 2013-05-19 00:11:00 2.0 0 Percent 2013-05-19 00:12:00 2.0 0.195 Percent 2013-05-19 00:13:00 2.0 0.215 Percent ...
Example request
This example returns CPU utilization across your EC2 fleet.
mon-get-stats CPUUtilization --start-time 2013-02-14T23:00:00.000Z --end-time
2013-03-14T23:00:00.000Z --period 3600 --statistics "Average,Minimum,Maximum" --namespace "AWS/EC2"
Example request
This example returns the average, minimum, and maximum request count made to the test stack of MyService for a particular user, at 1 hour resolution.
mon-get-stats RequestCount --start-time 2013-11-24T23:00:00.000Z --end-time
2013-11-25T23:00:00.000Z --period 3600 --statistics "Average,Minimum,Maximum" --namespace "MyService" --dimensions "User=SomeUser,Stack=Test"
Example request
This example shows RequestCount statistics across all of "MyService".
Related topics
mon-get-stats RequestCount --start-time 2013-11-24T23:00:00.000Z --end-time
2013-11-25T23:00:00.000Z --period 3600 --statistics "Average,Minimum,Maximum,SampleCount"
--namespace "MyService"
Related topics
Download
• Set up the command line interface (p. 2)
Related action
• GetMetricStatistics
Related commands
• mon-list-metrics (p. 43)
• mon-describe-alarms (p. 14)
mon-list-metrics
Description
Lists the names, namespaces, and dimensions of the metrics associated with your AWS account. You can filter metrics using any combination of metric name, namespace, or dimensions. If you do not specify a filter, all possible matches for the attribute are returned.
NoteThe mon-list-metrics command can take up to fifteen minutes to report new metric names, namespaces, and dimensions added by calls to mon-put-data. The data points put by mon- put-data, or other methods will be available by mon-get-statistics in less than five minutes.
Syntax
mon-list-metrics [--dimensions "key1=value1,key2=value2..."] [--metric-name value] [--namespace value] [Common Options]
Options
Name Description
-d, --dimensions
"key1=value1,key2=value2..."
The dimensions of the metric to retrieve. You can specify dimensions two ways and the formats can be combined or used interchangeably:
• One option per dimension: --dimensions "key1=value1"
--dimensions "key2=value2"
• All in one option: --dimensions
"key1=value1,key2=value2"
Common options
Name Description
If no dimensions are specified, no filtering of dimensions will be done. Any other requested filters will still be applied. To be included in the result a metric must contain all specified dimensions, although the metric may contain additional dimensions beyond the requested metrics.
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 Required: No
-m, --metric-name VALUE The name of the metric. To be included in the results, the metric name must match the requested metric name exactly. If no metric name is specified no filtering is done.
Any other requested filters are applied.
Type: Simple
Valid values: Any valid metric name between 1 and 250 characters in length.
Default: n/a Required: No
-n, --namespace VALUE The namespace to use to filter metrics. For more information about namespaces, see AWS Namespaces.
Type: String
Valid values: A valid namespace between 1 and 250 characters in length.
Default: n/a Required: No
Common options
Name Description
--aws-credential-file VALUE The location of the file with your AWS credentials.
You can set this value 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 fails. All CloudWatch requests must be signed using your access key ID and secret access key.
Common options
Name Description
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 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 The connection timeout value, in seconds.
Type: Integer
Valid values: Any positive number.
Default: 30
--delimiter VALUE The 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, include the column headers. If you are showing XML results, return 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 The access key ID 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 is ignored. All requests to CloudWatch must be signed, otherwise the request is rejected.
Type: String
Valid values: A valid access key ID.
Default: None
