acw-api-2010-08-01

8/13/2019 acw-api-2010-08-01

http://slidepdf.com/reader/full/acw-api-2010-08-01 1/42

Amazon CloudWatch

API Reference

API Version 2010-08-01

8/13/2019 acw-api-2010-08-01


Amazon CloudWatch: API ReferenceCopyright © 2012 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

The following are trademarks or registered trademarks of Amazon: Amazon, Amazon.com, Amazon.comDesign, Amazon DevPay, Amazon EC2, Amazon Web Services Design, AWS, CloudFront, EC2, Elastic

Compute Cloud, Kindle, and Mechanical Turk. In addition, Amazon.com graphics, logos, page headers,button icons, scripts, and service names are trademarks, or trade dress of Amazon in the U.S. and/or othercountries. 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 l ikely to cause confusion among customers, or in any mannerthat 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.

Amazon CloudWatch API Reference

8/13/2019 acw-api-2010-08-01


Welcome ................................................................................................................................................. 1Actions .................................................................................................................................................... 3DeleteAlarms .......................................................................................................................................... 4DescribeAlarmHistory ............................................................................................................................. 5DescribeAlarms ...................................................................................................................................... 7DescribeAlarmsForMetric ....................................................................................................................... 9

DisableAlarmActions ............................................................................................................................ 11EnableAlarmActions ............................................................................................................................. 12GetMetricStatistics ................................................................................................................................ 13ListMetrics ............................................................................................................................................ 16PutMetricAlarm ..................................................................................................................................... 18PutMetricData ....................................................................................................................................... 21SetAlarmState ...................................................................................................................................... 24Data Types ............................................................................................................................................ 26AlarmHistoryItem .................................................................................................................................. 26Datapoint .............................................................................................................................................. 27DescribeAlarmHistoryResult ................................................................................................................ 28DescribeAlarmsForMetricResult ........................................................................................................... 28DescribeAlarmsResult .......................................................................................................................... 29Dimension ............................................................................................................................................. 29

DimensionFilter ..................................................................................................................................... 30GetMetricStatisticsResult ..................................................................................................................... 30ListMetricsResult .................................................................................................................................. 30Metric .................................................................................................................................................... 31MetricAlarm .......................................................................................................................................... 31MetricDatum ......................................................................................................................................... 34StatisticSet ............................................................................................................................................ 35Common Query Parameters ................................................................................................................. 36Common Errors .................................................................................................................................... 38


3


8/13/2019 acw-api-2010-08-01


Welcome

This is the Amazon CloudWatch API Reference . This guide provides detailed information about Amazon

CloudWatch actions, data types, parameters, and errors. For detailed information about AmazonCloudWatch features and their associated API calls, go to the Amazon CloudWatch Developer Guide.

Amazon CloudWatch is a web service that enables you to publish, monitor, and manage various metrics,as well as configure alarm actions based on data from metrics. For more information about this productgo to http://aws.amazon.com/cloudwatch.

For information about the namespace, metric names, and dimensions that other Amazon Web Servicesproducts use to send metrics to Cloudwatch, go to Amazon CloudWatch Metrics, Namespaces, andDimensions Reference in the Amazon CloudWatch Developer Guide .

Use the following links to get started using the Amazon CloudWatch API Reference :

• Actions: An alphabetical list of all Amazon CloudWatch actions.

• Data Types: An alphabetical list of all Amazon CloudWatch data types.• Common Parameters: Parameters that all Query actions can use.

• Common Errors: Client and server errors that all actions can return.

• Regions and Endpoints: Itemized regions and endpoints for all AWS products.

• WSDL Location: http://monitoring.amazonaws.com/doc/2010-08-01/CloudWatch.wsdl

In addition to using the Amazon CloudWatch API, you can also use the following SDKs and third-partylibraries to access Amazon CloudWatch programmatically.

• AWS SDK for Java Documentation

• AWS SDK for .NET Documentation

• AWS SDK for PHP Documentation

• AWS SDK for Ruby Documentation

Developers in the AWS developer community also provide their own libraries, which you can find at thefollowing AWS developer centers:

• AWS Java Developer Center

• AWS PHP Developer Center

• AWS Python Developer Center

• AWS Ruby Developer Center


1


http://docs.amazonwebservices.com/AmazonCloudWatch/latest/DeveloperGuide

http://aws.amazon.com/cloudwatch

http://docs.amazonwebservices.com/AmazonCloudWatch/latest/DeveloperGuide/CW_Support_For_AWS.html


http://docs.amazonwebservices.com/AmazonCloudWatch/latest/APIReference/API_Operations.html

http://docs.amazonwebservices.com/AmazonCloudWatch/latest/APIReference/API_Types.html

http://docs.amazonwebservices.com/AmazonCloudWatch/latest/APIReference/CommonParameters.html

http://docs.amazonwebservices.com/AmazonCloudWatch/latest/APIReference/CommonErrors.html

http://docs.amazonwebservices.com/general/latest/gr/index.html?rande.html

http://monitoring.amazonaws.com/doc/2010-08-01/CloudWatch.wsdl

http://aws.amazon.com/documentation/sdkforjava/

http://aws.amazon.com/documentation/sdkfornet/

http://aws.amazon.com/documentation/sdkforphp/

http://aws.amazon.com/documentation/sdkforruby/

http://aws.amazon.com/java/

http://aws.amazon.com/php/

http://aws.amazon.com/python/

http://aws.amazon.com/ruby/

http://aws.amazon.com/ruby/

http://aws.amazon.com/python/

http://aws.amazon.com/php/

http://aws.amazon.com/java/

http://aws.amazon.com/documentation/sdkforruby/

http://aws.amazon.com/documentation/sdkforphp/

http://aws.amazon.com/documentation/sdkfornet/

http://aws.amazon.com/documentation/sdkforjava/

http://monitoring.amazonaws.com/doc/2010-08-01/CloudWatch.wsdl

http://docs.amazonwebservices.com/general/latest/gr/index.html?rande.html

http://docs.amazonwebservices.com/AmazonCloudWatch/latest/APIReference/CommonErrors.html

http://docs.amazonwebservices.com/AmazonCloudWatch/latest/APIReference/CommonParameters.html

http://docs.amazonwebservices.com/AmazonCloudWatch/latest/APIReference/API_Types.html

http://docs.amazonwebservices.com/AmazonCloudWatch/latest/APIReference/API_Operations.html



http://aws.amazon.com/cloudwatch

http://docs.amazonwebservices.com/AmazonCloudWatch/latest/DeveloperGuide

8/13/2019 acw-api-2010-08-01


• AWS Windows and .NET Developer Center

This document was last updated on December 20, 2012.


2


http://aws.amazon.com/net/

http://aws.amazon.com/net/

8/13/2019 acw-api-2010-08-01


Actions

The actions described in this guide are called by using the AWS Query protocol.

The following actions are supported:

• DeleteAlarms (p. 4)

• DescribeAlarmHistory (p. 5)

• DescribeAlarms (p. 7)

• DescribeAlarmsForMetric (p. 9)

• DisableAlarmActions (p. 11)

• EnableAlarmActions (p. 12)

• GetMetricStatistics (p. 13)

• ListMetrics (p. 16)

• PutMetricAlarm (p. 18)

• PutMetricData (p. 21)• SetAlarmState (p. 24)


3


8/13/2019 acw-api-2010-08-01


DeleteAlarms

Description

Deletes all specified alarms. In the event of an error, no alarms are deleted.

Request Parameters

For information about the common parameters that all actions use, see Common Query Parameters (p.36).

AlarmNames.member.NA list of alarms to be deleted.

Type: String list

Length constraints: Minimum of 0 item(s) in the list. Maximum of 100 item(s) in the list.

Required:Yes

Errors

For information about the errors that are common to all actions, see Common Errors (p. 38).

ResourceNotFoundThe named resource does not exist.

HTTP Status Code: 404


4


DeleteAlarms

8/13/2019 acw-api-2010-08-01


DescribeAlarmHistory

Description

Retrieves history for the specified alarm. Filter alarms by date range or item type. If an alarm name is notspecified, Amazon CloudWatch returns histories for all of the owner's alarms.

NoteAmazon CloudWatch retains the history of an alarm for two weeks, whether or not you deletethe alarm.

Request Parameters


AlarmNameThe name of the alarm.

Type: String

Length constraints: Minimum length of 1. Maximum length of 255.

Required: No

EndDateThe ending date to retrieve alarm history.

Type: DateTime

Required: No

HistoryItemTypeThe type of alarm histories to retrieve.

Type: String

Valid Values: ConfigurationUpdate | StateUpdate | Action

Required: No

MaxRecordsThe maximum number of alarm history records to retrieve.

Type: Integer

Required: No

NextTokenThe token returned by a previous call to indicate that there is more data available.

Type: String

Required: No

StartDateThe starting date to retrieve alarm history.

Type: DateTime


5


DescribeAlarmHistory

8/13/2019 acw-api-2010-08-01


Required: No

Response Elements

The following elements are returned in a DescribeAlarmHistoryResult structure.

AlarmHistoryItemsA list of alarm histories in JSON format.

Type: AlarmHistoryItem (p. 26) list

NextTokenA string that marks the start of the next batch of returned results.

Type: String

Errors


InvalidNextTokenThe next token specified is invalid.



6


Response Elements

8/13/2019 acw-api-2010-08-01


DescribeAlarms

Description

Retrieves alarms with the specified names. If no name is specified, all alarms for the user are returned.Alarms can be retrieved by using only a prefix for the alarm name, the alarm state, or a prefix for anyaction.

Request Parameters


ActionPrefixThe action name prefix.

Type: String


Required: No

AlarmNamePrefixThe alarm name prefix. AlarmNames cannot be specified if this parameter is specified.

Type: String


Required: No

AlarmNames.member.NA list of alarm names to retrieve information for.

Type: String list


Required: No

MaxRecordsThe maximum number of alarm descriptions to retrieve.

Type: Integer

Required: No


Type: String

Required: No

StateValueThe state value to be used in matching alarms.

Type: String

Valid Values: OK | ALARM | INSUFFICIENT_DATA


7


DescribeAlarms

8/13/2019 acw-api-2010-08-01


Required: No

Response Elements

The following elements are returned in a DescribeAlarmsResult structure.

MetricAlarmsA list of information for the specified alarms.

Type: MetricAlarm (p. 31) list


Type: String

Errors


InvalidNextTokenThe next token specified is invalid.



8


Response Elements

8/13/2019 acw-api-2010-08-01


DescribeAlarmsForMetric

Description

Retrieves all alarms for a single metric. Specify a statistic, period, or unit to filter the set of alarms fur ther.

Request Parameters


Dimensions.member.NThe list of dimensions associated with the metric.

Type: Dimension (p. 29) list


Required: No

MetricNameThe name of the metric.

Type: String


Required:Yes

NamespaceThe namespace of the metric.

Type: String


Required:Yes

PeriodThe period in seconds over which the statistic is applied.

Type: Integer

Required: No

StatisticThe statistic for the metric.

Type: String

Valid Values: SampleCount | Average | Sum | Minimum | Maximum

Required: No

UnitThe unit for the metric.

Type: String

Valid Values: 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 |


9


DescribeAlarmsForMetric

8/13/2019 acw-api-2010-08-01


Kilobits/Second | Megabits/Second | Gigabits/Second | Terabits/Second |

Count/Second | None

Required: No

Response ElementsThe following element is returned in a DescribeAlarmsForMetricResult structure.

MetricAlarmsA list of information for each alarm with the specified metric.



10


Response Elements

8/13/2019 acw-api-2010-08-01


DisableAlarmActions

Description

Disables actions for the specified alarms. When an alarm's actions are disabled the alarm's state maychange, but none of the alarm's actions will execute.

Request Parameters


AlarmNames.member.NThe names of the alarms to disable actions for.

Type: String list


Required:Yes


11


DisableAlarmActions

8/13/2019 acw-api-2010-08-01


EnableAlarmActions

Description

Enables actions for the specified alarms.

Request Parameters


AlarmNames.member.NThe names of the alarms to enable actions for.

Type: String list


Required:Yes


12


EnableAlarmActions

8/13/2019 acw-api-2010-08-01


GetMetricStatistics

Description

Gets statistics for the specified metric.

The maximum number of data points returned from a single GetMetricStatistics request is 1,440,

wereas the maximum number of data points that can be queried is 50,850. If you make a request thatgenerates more than 1,440 data points, Amazon CloudWatch returns an error. In such a case, you canalter the request by narrowing the specified time range or increasing the specified period. Alternatively,you can make multiple requests across adjacent time ranges.

Amazon CloudWatch aggregates data points based on the length of the period that you specify. Forexample, if you request statistics with a one-minute granularity, Amazon CloudWatch aggregates datapoints with time stamps that fall within the same one-minute period. In such a case, the data points queriedcan greatly outnumber the data points returned.

The following examples show various statistics allowed by the data point query maximum of 50,850 whenyou call GetMetricStatistics on Amazon EC2 instances with detailed (one-minute) monitoringenabled:

• Statistics for up to 400 instances for a span of one hour

• Statistics for up to 35 instances over a span of 24 hours

• Statistics for up to 2 instances over a span of 2 weeks

For information about the namespace, metric names, and dimensions that other Amazon Web Servicesproducts use to send metrics to Cloudwatch, go to Amazon CloudWatch Metrics, Namespaces, andDimensions Reference in the Amazon CloudWatch Developer Guide .

Request Parameters


Dimensions.member.NA list of dimensions describing qualities of the metric.



Required: No

EndTimeThe time stamp to use for determining the last datapoint to return.The value specified is exclusive;results will include datapoints up to the time stamp specified.

Type: DateTime

Required:Yes

MetricNameThe name of the metric, with or without spaces.

Type: String



13


GetMetricStatistics





8/13/2019 acw-api-2010-08-01


Required:Yes

NamespaceThe namespace of the metric, with or without spaces.

Type: String


Required:Yes

PeriodThe granularity, in seconds, of the returned datapoints. Period must be at least 60 seconds andmust be a multiple of 60. The default value is 60.

Type: Integer

Required:Yes

StartTimeThe time stamp to use for determining the first datapoint to return.The value specified is inclusive;results include datapoints with the time stamp specified.

NoteThe specified start time is rounded down to the nearest value. Datapoints are returned forstart times up to two weeks in the past. Specified start times that are more than two weeksin the past will not return datapoints for metrics that are older than two weeks.

Data that is timestamped 24 hours or more in the past may take in excess of 48 hours tobecome available from submission time using GetMetricStatistics.

Type: DateTime

Required:Yes

Statistics.member.NThe metric statistics to return. For information about specific statistics returned by GetMetricStatistics,go to Statistics in the Amazon CloudWatch Developer Guide .

Valid Values: Average | Sum | SampleCount | Maximum | Minimum

Type: String list


Required:Yes

UnitThe unit for the metric.

Type: String


Megabytes | Gigabytes | Terabytes | Bits | Kilobits | Megabits | Gigabits

| Terabits | Percent | Count | Bytes/Second | Kilobytes/Second |Megabytes/Second | Gigabytes/Second | Terabytes/Second | Bits/Second |


Count/Second | None


14


Request Parameters

http://docs.amazonwebservices.com/AmazonCloudWatch/latest/DeveloperGuide/index.html?CHAP_TerminologyandKeyConcepts.html#Statistic

http://docs.amazonwebservices.com/AmazonCloudWatch/latest/DeveloperGuide/index.html?CHAP_TerminologyandKeyConcepts.html#Statistic

8/13/2019 acw-api-2010-08-01


Required: No

Response Elements

The following elements are returned in a GetMetricStatisticsResult structure.

DatapointsThe datapoints for the specified metric.

Type: Datapoint (p. 27) list

LabelA label describing the specified metric.

Type: String

Errors


InternalServiceIndicates that the request processing has failed due to some unknown error, exception, or failure.


InvalidParameterCombinationParameters that must not be used together were used together.


InvalidParameterValueBad or out-of-range value was supplied for the input parameter.


MissingRequiredParameterAn input parameter that is mandatory for processing the request is not supplied.



15


Response Elements

8/13/2019 acw-api-2010-08-01


ListMetrics

Description

Returns a list of valid metrics stored for the AWS account owner. Returned metrics can be used withGetMetricStatistics (p. 13) to obtain statistical data for a given metric.

NoteUp to 500 results are returned for any one call.To retrieve further results, use returned NextTokenvalues with subsequent ListMetrics operations.

NoteIf you create a metric with the PutMetricData (p. 21) action, allow up to fifteen minutes for themetric to appear in calls to the ListMetrics action. Statistics about the metric, however, areavailable sooner using GetMetricStatistics (p. 13).

Request Parameters


Dimensions.member.NA list of dimensions to filter against.

Type: DimensionFilter (p. 30) list


Required: No

MetricNameThe name of the metric to filter against.

Type: String


Required: No

NamespaceThe namespace to filter against.

Type: String


Required: No


Type: String

Required: No

Response Elements

The following elements are returned in a ListMetricsResult structure.


16


ListMetrics

8/13/2019 acw-api-2010-08-01


MetricsA list of metrics used to generate statistics for an AWS account.

Type: Metric (p.31) list


Type: String

Errors







17


Errors

8/13/2019 acw-api-2010-08-01


PutMetricAlarm

Description

Creates or updates an alarm and associates it with the specified Amazon CloudWatch metric. Optionally,this operation can associate one or more Amazon Simple Notification Service resources with the alarm.

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

is then executed.

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

Request Parameters


ActionsEnabledIndicates whether or not actions should be executed during any changes to the alarm's state.

Type: Boolean

Required: No

AlarmActions.member.NThe list of actions to execute when this alarm transitions into an ALARM state from any other state.Each action is specified as an Amazon Resource Number (ARN). Currently the only action supportedis publishing to an Amazon SNS topic or an Amazon Auto Scaling policy.

Type: String list


Required: No

AlarmDescriptionThe description for the alarm.

Type: String


Required: No

AlarmNameThe descriptive name for the alarm. This name must be unique within the user's AWS account

Type: String


Required:Yes

ComparisonOperatorThe arithmetic operation to use when comparing the specified Statistic and Threshold.Thespecified Statistic value is used as the first operand.

Type: String


18


PutMetricAlarm

8/13/2019 acw-api-2010-08-01


Valid Values: GreaterThanOrEqualToThreshold | GreaterThanThreshold |LessThanThreshold | LessThanOrEqualToThreshold

Required:Yes

Dimensions.member.NThe dimensions for the alarm's associated metric.



Required: No

EvaluationPeriodsThe number of periods over which data is compared to the specified threshold.

Type: Integer

Required:Yes

InsufficientDataActions.member.NThe list of actions to execute when this alarm transitions into an INSUFFICIENT_DATA state from

any other state. Each action is specified as an Amazon Resource Number (ARN). Currently the onlyaction supported is publishing to an Amazon SNS topic or an Amazon Auto Scaling policy.

Type: String list


Required: No

MetricNameThe name for the alarm's associated metric.

Type: String


Required:Yes

NamespaceThe namespace for the alarm's associated metric.

Type: String


Required:Yes

OKActions.member.NThe list of actions to execute when this alarm transitions into an OK state from any other state. Eachaction is specified as an Amazon Resource Number (ARN). Currently the only action supported ispublishing to an Amazon SNS topic or an Amazon Auto Scaling policy.

Type: String list


Required: No

PeriodThe period in seconds over which the specified statistic is applied.

Type: Integer


19


Request Parameters

8/13/2019 acw-api-2010-08-01


Required:Yes

StatisticThe statistic to apply to the alarm's associated metric.

Type: String

Valid Values: SampleCount | Average | Sum | Minimum | Maximum

Required:Yes

ThresholdThe value against which the specified statistic is compared.

Type: Double

Required:Yes

UnitThe unit for the alarm's associated metric.

Type: String

Valid Values: Seconds | Microseconds | Milliseconds | Bytes | Kilobytes |Megabytes | Gigabytes | Terabytes | Bits | Kilobits | Megabits | Gigabits




Count/Second | None

Required: No

Errors


LimitExceededThe quota for alarms for this customer has already been reached.



20


Errors

8/13/2019 acw-api-2010-08-01


PutMetricData

Description

Publishes metric data points to Amazon CloudWatch. Amazon Cloudwatch associates the data pointswith the specified metric. If the specified metric does not exist, Amazon CloudWatch creates the metric.It can take up to fifteen minutes for a new metric to appear in calls to the ListMetrics (p. 16) action.

The size of a request is limited to 8 KB for HTTP GET requests and 40 KB for HTTP POST requests.

ImportantAlthough the Value parameter accepts numbers of type Double, Amazon CloudWatch truncatesvalues with very large exponents.Values with base-10 exponents greater than 126 (1 x 10^126)are truncated. Likewise, values with base-10 exponents less than -130 (1 x 10^-130) are alsotruncated.

Data that is timestamped 24 hours or more in the past may take in excess of 48 hours to become availablefrom submission time using GetMetricStatistics.

Request ParametersFor information about the common parameters that all actions use, see Common Query Parameters (p.36).

MetricData.member.NA list of data describing the metric.

Type: MetricDatum (p. 34) list

Required:Yes

NamespaceThe namespace for the metric data.

Note

You cannot specify a namespace that begins with "AWS/". Namespaces that begin with"AWS/" are reserved for other Amazon Web Services products that send metrics to AmazonCloudWatch.

Type: String


Required:Yes

Errors




InvalidParameterCombinationParameters that must not be used together were used together.



21


PutMetricData

8/13/2019 acw-api-2010-08-01




MissingRequiredParameterAn input parameter that is mandatory for processing the request is not supplied.


Examples

Sample Request

The following example puts data for a single metric containing one dimension:

https://monitoring.amazonaws.com/doc/2010-08-01/

?Action=PutMetricData

&Version=2010-08-01

&Namespace=TestNamespace

&MetricData.member.1.MetricName=buffers

&MetricData.member.1.Unit=Bytes

&MetricData.member.1.Value=231434333

&MetricData.member.1.Dimensions.member.1.Name=InstanceType

&MetricData.member.1.Dimensions.member.1.Value=m1.small

&AUTHPARAMS

The following example puts data for a single metric containing two dimensions:

https://monitoring.amazonaws.com/doc/2010-08-01/

?Action=PutMetricData

&Version=2010-08-01&Namespace=TestNamespace




&MetricData.member.1.Dimensions.member.1.Name=InstanceID

&MetricData.member.1.Dimensions.member.1.Value=i-aaba32d4



&AUTHPARAMS

The following example puts data for two metrics, each with two dimensions:

https://monitoring.amazonaws.com/doc/2010-08-01/?Action=PutMetricData

&Version=2010-08-01

&Namespace=TestNamespace







22


Examples

8/13/2019 acw-api-2010-08-01




&MetricData.member.2.MetricName=latency

&MetricData.member.2.Unit=Milliseconds






&AUTHPARAMS

Sample Response

<PutMetricDataResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">

<ResponseMetadata>

<RequestId>e16fc4d3-9a04-11e0-9362-093a1cae5385</RequestId> </ResponseMetadata>

</PutMetricDataResponse>


23


Examples

8/13/2019 acw-api-2010-08-01


SetAlarmState

Description

Temporarily sets the state of an alarm. When the updated StateValue differs from the previous value,the action configured for the appropriate state is invoked.This is not a permanent change.The nextperiodic alarm check (in about a minute) will set the alarm to its actual state.

Request Parameters


AlarmNameThe descriptive name for the alarm.This name must be unique within the user's AWS account.Themaximum length is 255 characters.

Type: String


Required:Yes

StateReasonThe reason that this alarm is set to this specific state (in human-readable text format)

Type: String


Required:Yes

StateReasonDataThe reason that this alarm is set to this specific state (in machine-readable JSON format)

Type: String


Required: No

StateValueThe value of the state.

Type: String


Required:Yes

ErrorsFor information about the errors that are common to all actions, see Common Errors (p. 38).

InvalidFormatData was not syntactically valid JSON.



24


SetAlarmState

8/13/2019 acw-api-2010-08-01


ResourceNotFoundThe named resource does not exist.



25


Errors

8/13/2019 acw-api-2010-08-01


Data Types

The Amazon CloudWatch API contains several data types that various actions use.This section describes

each data type in detail.NoteThe order of each element in the response is not guaranteed. Applications should not assumea particular order.

The following data types are supported:

• AlarmHistoryItem (p. 26)

• Datapoint (p.27)

• DescribeAlarmHistoryResult (p. 28)

• DescribeAlarmsForMetricResult (p. 28)

• DescribeAlarmsResult (p. 29)

• Dimension (p.29)

• DimensionFilter (p. 30)

• GetMetricStatisticsResult (p. 30)

• ListMetricsResult (p. 30)

• Metric (p. 31)

• MetricAlarm (p.31)

• MetricDatum (p.34)

• StatisticSet (p. 35)

AlarmHistoryItem

Description

The AlarmHistoryItem data type contains descriptive information about the history of a specific alarm.If you call DescribeAlarmHistory (p. 5), Amazon CloudWatch returns this data type as part of theDescribeAlarmHistoryResult (p. 28) data type.


26


AlarmHistoryItem

8/13/2019 acw-api-2010-08-01


Contents

AlarmNameThe descriptive name for the alarm.

Type: String


HistoryDataMachine-readable data about the alarm in JSON format.

Type: String


HistoryItemTypeThe type of alarm history item.

Type: String

Valid Values: ConfigurationUpdate | StateUpdate | Action

HistorySummaryA human-readable summary of the alarm history.

Type: String


TimestampThe time stamp for the alarm history item. Amazon CloudWatch uses Coordinated Universal Time(UTC) when returning time stamps, which do not accommodate seasonal adjustments such as daylightsavings time. For more information, see Time stamps in the Amazon CloudWatch Developer Guide .

Type: DateTime

Datapoint

Description

The Datapoint data type encapsulates the statistical data that Amazon CloudWatch computes frommetric data.

Contents

AverageThe average of metric values that correspond to the datapoint.

Type: Double

MaximumThe maximum of the metric value used for the datapoint.

Type: Double

MinimumThe minimum metric value used for the datapoint.

Type: Double


27


Contents

http://docs.amazonwebservices.com/AmazonCloudWatch/latest/DeveloperGuide/cloudwatch_concepts.html#about_timestamp


8/13/2019 acw-api-2010-08-01


SampleCountThe number of metric values that contributed to the aggregate value of this datapoint.

Type: Double

SumThe sum of metric values used for the datapoint.

Type: Double

TimestampThe time stamp used for the datapoint. Amazon CloudWatch uses Coordinated Universal Time (UTC)when returning time stamps, which do not accommodate seasonal adjustments such as daylightsavings time. For more information, see Time stamps in the Amazon CloudWatch Developer Guide .

Type: DateTime

UnitThe standard unit used for the datapoint.

Type: String


Megabytes | Gigabytes | Terabytes | Bits | Kilobits | Megabits | Gigabits| Terabits | Percent | Count | Bytes/Second | Kilobytes/Second |



Count/Second | None

DescribeAlarmHistoryResult

Description

The output for the DescribeAlarmHistory (p. 5) action.

Contents

AlarmHistoryItemsA list of alarm histories in JSON format.

Type: AlarmHistoryItem (p. 26) list


Type: String

DescribeAlarmsForMetricResultDescription

The output for the DescribeAlarmsForMetric (p. 9) action.


28


DescribeAlarmHistoryResult



8/13/2019 acw-api-2010-08-01


Contents

MetricAlarmsA list of information for each alarm with the specified metric.


DescribeAlarmsResult

Description

The output for the DescribeAlarms (p. 7) action.

Contents

MetricAlarms

A list of information for the specified alarms.



Type: String

Dimension

Description

The Dimension data type further expands on the identity of a metric using a Name, Value pair.

For examples that use one or more dimensions, see PutMetricData (p. 21).

Contents

NameThe name of the dimension.

Type: String


ValueThe value representing the dimension measurement

Type: String



29


Contents

8/13/2019 acw-api-2010-08-01


DimensionFilter

Description

The DimensionFilter data type is used to filter ListMetrics (p.16) results.

Contents

NameThe dimension name to be matched.

Type: String


ValueThe value of the dimension to be matched.

Note

Specifying a Name without specifying a Value returns all values associated with that Name.

Type: String


GetMetricStatisticsResult

Description

The output for the GetMetricStatistics (p. 13) action.

Contents

DatapointsThe datapoints for the specified metric.

Type: Datapoint (p. 27) list

LabelA label describing the specified metric.

Type: String

ListMetricsResultDescription

The output for the ListMetrics (p.16) action.


30


DimensionFilter

8/13/2019 acw-api-2010-08-01


Contents

MetricsA list of metrics used to generate statistics for an AWS account.

Type: Metric (p.31) list


Type: String

Metric

Description

The Metric data type contains information about a specific metric. If you call ListMetrics (p.16), AmazonCloudWatch returns information contained by this data type.

The example in the Examples section publishes two metrics named buffers and latency. Both metrics arein the examples namespace. Both metrics have two dimensions, InstanceID and InstanceType.

Contents

DimensionsA list of dimensions associated with the metric.



MetricName

The name of the metric.

Type: String


NamespaceThe namespace of the metric.

Type: String


MetricAlarmDescription

The MetricAlarm (p.31) data type represents an alarm. You can use PutMetricAlarm (p. 18) to create orupdate an alarm.


31


Contents

8/13/2019 acw-api-2010-08-01


Contents

ActionsEnabledIndicates whether actions should be executed during any changes to the alarm's state.

Type: Boolean

AlarmActionsThe list of actions to execute when this alarm transitions into an ALARM state from any other state.Each action is specified as an Amazon Resource Number (ARN). Currently the only actions supportedare publishing to an Amazon SNS topic and triggering an Auto Scaling policy.

Type: String list


AlarmArnThe Amazon Resource Name (ARN) of the alarm.

Type: String


AlarmConfigurationUpdatedTimestampThe time stamp of the last update to the alarm configuration. Amazon CloudWatch uses CoordinatedUniversal Time (UTC) when returning time stamps, which do not accommodate seasonal adjustmentssuch as daylight savings time. For more information, see Time stamps in the Amazon CloudWatch Developer Guide .

Type: DateTime

AlarmDescriptionThe description for the alarm.

Type: String


AlarmNameThe name of the alarm.

Type: String


ComparisonOperatorThe arithmetic operation to use when comparing the specified Statistic and Threshold.Thespecified Statistic value is used as the first operand.

Type: String

Valid Values: GreaterThanOrEqualToThreshold | GreaterThanThreshold |LessThanThreshold | LessThanOrEqualToThreshold

DimensionsThe list of dimensions associated with the alarm's associated metric.



EvaluationPeriodsThe number of periods over which data is compared to the specified threshold.

Type: Integer


32


Contents



8/13/2019 acw-api-2010-08-01


InsufficientDataActionsThe list of actions to execute when this alarm transitions into an INSUFFICIENT_DATA state fromany other state. Each action is specified as an Amazon Resource Number (ARN). Currently the onlyactions supported are publishing to an Amazon SNS topic or triggering an Auto Scaling policy.

ImportantThe current WSDL lists this attribute as UnknownActions.

Type: String list


MetricNameThe name of the alarm's metric.

Type: String


NamespaceThe namespace of alarm's associated metric.

Type: String


OKActionsThe list of actions to execute when this alarm transitions into an OK state from any other state. Eachaction is specified as an Amazon Resource Number (ARN). Currently the only actions supported arepublishing to an Amazon SNS topic and triggering an Auto Scaling policy.

Type: String list


PeriodThe period in seconds over which the statistic is applied.

Type: Integer

StateReasonA human-readable explanation for the alarm's state.

Type: String


StateReasonDataAn explanation for the alarm's state in machine-readable JSON format

Type: String


StateUpdatedTimestampThe time stamp of the last update to the alarm's state. Amazon CloudWatch uses CoordinatedUniversal Time (UTC) when returning time stamps, which do not accommodate seasonal adjustmentssuch as daylight savings time. For more information, see Time stamps in the Amazon CloudWatch Developer Guide .

Type: DateTime

StateValueThe state value for the alarm.

Type: String


33


Contents



8/13/2019 acw-api-2010-08-01



StatisticThe statistic to apply to the alarm's associated metric.

Type: String

Valid Values: SampleCount | Average | Sum | Minimum | MaximumThreshold

The value against which the specified statistic is compared.

Type: Double

UnitThe unit of the alarm's associated metric.

Type: String




Kilobits/Second | Megabits/Second | Gigabits/Second | Terabits/Second |Count/Second | None

MetricDatum

Description

The MetricDatum data type encapsulates the information sent with PutMetricData (p.21) to either create

a new metric or add new values to be aggregated into an existing metric.

ContentsDimensions

A list of dimensions associated with the metric. Note, when using the Dimensions value in a query,you need to append .member.N to it (e.g., Dimensions.member.N).



MetricNameThe name of the metric.

Type: String


StatisticValuesA set of statistical values describing the metric.

Type: StatisticSet (p. 35)

TimestampThe time stamp used for the metric. If not specified, the default value is set to the time the metricdata was received. Amazon CloudWatch uses Coordinated Universal Time (UTC) when returningtime stamps, which do not accommodate seasonal adjustments such as daylight savings time. Formore information, see Time stamps in the Amazon CloudWatch Developer Guide .


34


MetricDatum



8/13/2019 acw-api-2010-08-01


Type: DateTime

UnitThe unit of the metric.

Type: String





Count/Second | None

ValueThe value for the metric.

ImportantAlthough the Value parameter accepts numbers of type Double, Amazon CloudWatch

truncates values with very large exponents.Values with base-10 exponents greater than126 (1 x 10^126) are truncated. Likewise, values with base-10 exponents less than -130 (1x 10^-130) are also truncated.

Type: Double

StatisticSet

Description

The StatisticSet data type describes the StatisticValues component of MetricDatum (p. 34),and represents a set of statistics that describes a specific metric.

Contents

MaximumThe maximum value of the sample set.

Type: Double

MinimumThe minimum value of the sample set.

Type: Double

SampleCountThe number of samples used for the statistic set.

Type: Double

SumThe sum of values for the sample set.

Type: Double


35


StatisticSet

8/13/2019 acw-api-2010-08-01


Common Query Parameters

This section lists the request parameters that all actions use. Any action-specific parameters are listed

in the topic for the action.

RequiredDescriptionParameter Name

YesThe action to be performed.

Default: None

Type: Str ing

Action

ConditionalThe parameters that are required to authenticate aConditional request.

Contains:

AWSAccessKeyID

SignatureVersion

TimestampSignature

Default: None

AuthParams

YesThe access key ID that corresponds to the secretaccess key that you used to sign the request.

Default: None

Type: Str ing

AWSAccessKeyId

ConditionalThe date and time when the request signature expires,expressed in the format YYYY-MM-DDThh:mm:ssZ,as specified in the ISO 8601 standard.

Condition: Requests must include either Timestamp

or Expires, but not both.

Default: None

Type: Str ing

Expires


36


8/13/2019 acw-api-2010-08-01


RequiredDescriptionParameter Name

The temporary security token that was obtained througha call to AWS Security Token Service. For a list ofservices that support AWS Security Token Service, goto Using Temporary Security Credentials to Access

AWS in Using Temporary Security Credentials .Default: None

Type: Str ing

SecurityToken

YesThe digital signature that you created for the request.For information about generating a signature, go to theservice's developer documentation.

Default: None

Type: Str ing

Signature

YesThe hash algorithm that you used to create the requestsignature.

Default: None

Valid Values: HmacSHA256 | HmacSHA1.

Type: Str ing

SignatureMethod

YesThe signature version you use to sign the request. Setthis to the value that is recommended for your service.

Default: None

Type: Str ing

SignatureVersion

ConditionalThe date and time when the request was signed,expressed in the format YYYY-MM-DDThh:mm:ssZ,as specified in the ISO 8601 standard.

Condition: Requests must include either Timestampor Expires, but not both.

Default: None

Type: Str ing

Timestamp

YesThe API version that the request is written for,expressed in the format YYYY-MM-DD.

Default: None

Type: Str ing

Version


37


http://docs.amazonwebservices.com/IAM/latest/UsingSTS/UsingTokens.html




8/13/2019 acw-api-2010-08-01


Common Errors

This section lists the common errors that all actions return. Any action-specific errors are listed in the

topic for the action.

HTTPStatusCode

DescriptionError

400The request signature does not conform toAWS standards.

IncompleteSignature

500The request processing has failed because ofan unknown error, exception or failure.

InternalFailure

400The action or operation requested is invalid.Verify that the action is typed correctly.

InvalidAction

403The X.509 certificate or AWS access key IDprovided does not exist in our records.

InvalidClientTokenId

400Parameters that must not be used togetherwere used together.

InvalidParameterCombination

400An invalid or out-of-range value was suppliedfor the input parameter.

InvalidParameterValue

400AWS query string is malformed, does notadhere to AWS standards.

InvalidQueryParameter

404The query string contains a syntax error.MalformedQueryString

400The request is missing an action or a required

parameter.

MissingAction

403Request must contain either a valid (registered)AWS access key ID or X.509 certificate.

MissingAuthenticationToken

400A required parameter for the specified actionis not supplied.

MissingParameter

403The AWS access key ID needs a subscriptionfor the service.

OptInRequired


38


8/13/2019 acw-api-2010-08-01


HTTPStatusCode

DescriptionError

400The request reached the service more than 15minutes after the date stamp on the request or

more than 15 minutes after the requestexpiration date (such as for pre-signed URLs),or the date stamp on the request is more than15 minutes in the future.

RequestExpired

503The request has failed due to a temporaryfailure of the server.

ServiceUnavailable

400Request was denied due to request throttling.Throttling


Documents

acw-api-2010-08-01