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

mon-get-stats

Description

Get time-series data for one or more statistics of a given MetricName.

Note

When 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

NameDescriptionRequired

MetricName

Specify the metric name to retrieve statistics for. 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

Yes

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

Specify 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 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

--end-time VALUE

Specify 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.

No

-n, --namespace VALUE

Specify the namespace of the metric you want to retrieve statistics for. 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

--period VALUE

Specify the granularity (in seconds) to retrieve statistics for. 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.

No

-s, --statistics VALUE1,VALUE2,VALUE3...

Specify the statistics to be returned for the given metric.

Type: Enumeration

Valid values: Average, Sum, Maximum, or Minimum

Default: n/a

Yes

--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.

No

--unit VALUE

Specify 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

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 returns a table that contains the following:

  • Time - Time the metrics were taken.

  • SampleCount - No description available for this column.

  • Average - Average value.

  • Sum - Sum of values.

  • Minimum - Minimum observed value.

  • Maximum - Maximum observed value.

  • Unit - 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.

PROMPT>  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.

PROMPT>  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.

PROMPT>  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".

PROMPT> 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"