acw-api

Amazon CloudWatchAPI Reference

API Version 2010-08-01

Amazon CloudWatch: API ReferenceCopyright © 2011 Amazon Web Services LLC or its affiliates. All rights reserved.

Amazon CloudWatch API Reference

Table of ContentsWelcome ............................................................................................................................................................. 1Actions ................................................................................................................................................................ 2

DeleteAlarms .......................................................................................................................................... 3DescribeAlarmHistory ............................................................................................................................. 4DescribeAlarms ...................................................................................................................................... 6DescribeAlarmsForMetric ....................................................................................................................... 8DisableAlarmActions ............................................................................................................................ 10EnableAlarmActions ............................................................................................................................. 11GetMetricStatistics ................................................................................................................................ 12ListMetrics ............................................................................................................................................ 15PutMetricAlarm ..................................................................................................................................... 17PutMetricData ....................................................................................................................................... 20SetAlarmState ...................................................................................................................................... 23

Data Types ........................................................................................................................................................ 24AlarmHistoryItem .................................................................................................................................. 25Datapoint .............................................................................................................................................. 25DescribeAlarmHistoryResult ................................................................................................................ 26DescribeAlarmsForMetricResult ........................................................................................................... 26DescribeAlarmsResult .......................................................................................................................... 27Dimension ............................................................................................................................................. 27DimensionFilter ..................................................................................................................................... 28GetMetricStatisticsResult ..................................................................................................................... 28ListMetricsResult .................................................................................................................................. 28Metric .................................................................................................................................................... 29MetricAlarm .......................................................................................................................................... 29MetricDatum ......................................................................................................................................... 32StatisticSet ............................................................................................................................................ 33

Common Query Parameters ............................................................................................................................. 35Common Errors ................................................................................................................................................ 37


Welcome

This is the Amazon CloudWatch API Reference. This guide provides detailed information about AmazonCloudWatch 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.

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

This document was last updated on August 22, 2011.



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

http://aws.amazon.com/cloudwatch

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

Actions

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

The following actions are supported:

• DeleteAlarms (p. 3)

• DescribeAlarmHistory (p. 4)

• DescribeAlarms (p. 6)

• DescribeAlarmsForMetric (p. 8)

• DisableAlarmActions (p. 10)

• EnableAlarmActions (p. 11)

• GetMetricStatistics (p. 12)

• ListMetrics (p. 15)

• PutMetricAlarm (p. 17)

• PutMetricData (p. 20)

• SetAlarmState (p. 23)



DeleteAlarms

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

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

RequiredDescriptionName

YesA list of alarms to be deleted.Type: String list

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

AlarmNames.member.N

ErrorsFor information about the common errors that all actions use, see Common Errors (p. 37).

HTTPStatusCode

DescriptionError

404The named resource does not exist.ResourceNotFound


Amazon CloudWatch API ReferenceDeleteAlarms

DescribeAlarmHistory

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

Note

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



NoThe name of the alarm.Type: String

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

AlarmName

NoThe ending date to retrieve alarm history.Type: DateTime

EndDate

NoThe type of alarm histories to retrieve.Type: String

Valid Values: ConfigurationUpdate | StateUpdate |Action

HistoryItemType

NoThe maximum number of alarm history records to retrieve.Type: Integer

MaxRecords

NoThe token returned by a previous call to indicate that there is moredata available.Type: String

NextToken

NoThe starting date to retrieve alarm history.Type: DateTime

StartDate

Response ElementsThe following elements come wrapped in a DescribeAlarmHistoryResult structure.

DescriptionName

A list of alarm histories in JSON format.Type: AlarmHistoryItem (p. 25) list

AlarmHistoryItems

A string that marks the start of the next batch of returned results.Type: String

NextToken


Amazon CloudWatch API ReferenceDescribeAlarmHistory


HTTPStatusCode

DescriptionError

400The next token specified is invalid.InvalidNextToken


Amazon CloudWatch API ReferenceErrors

DescribeAlarms

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



NoThe action name prefix.Type: String

Length constraints: Minimum value of 1. Maximum value of1024.

ActionPrefix

NoThe alarm name prefix. AlarmNames cannot be specified ifthis parameter is specified.Type: String


AlarmNamePrefix

NoA list of alarm names to retrieve information for.Type: String list


AlarmNames.member.N

NoThe maximum number of alarm descriptions to retrieve.Type: Integer

MaxRecords

NoThe token returned by a previous call to indicate that there ismore data available.Type: String

NextToken

NoThe state value to be used in matching alarms.Type: String

Valid Values: OK | ALARM | INSUFFICIENT_DATA

StateValue

Response ElementsThe following elements come wrapped in a DescribeAlarmsResult structure.

DescriptionName

A list of information for the specified alarms.Type: MetricAlarm (p. 29) list

MetricAlarms


NextToken


Amazon CloudWatch API ReferenceDescribeAlarms


HTTPStatusCode

DescriptionError

400The next token specified is invalid.InvalidNextToken



DescribeAlarmsForMetric

DescriptionRetrieves all alarms for a single metric. Specify a statistic, period, or unit to filter the set of alarms further.



NoThe list of dimensions associated with the metric.Type: Dimension (p. 27) list


Dimensions.member.N

YesThe name of the metric.Type: String


MetricName

YesThe namespace of the metric.Type: String


Namespace

NoThe period in seconds over which the statistic is applied.Type: Integer

Period

NoThe statistic for the metric.Type: String

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

Statistic

NoThe 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 |Kilobits/Second | Megabits/Second |Gigabits/Second | Terabits/Second |Count/Second | None

Unit

Response ElementsThe following elements come wrapped in a DescribeAlarmsForMetricResult structure.


Amazon CloudWatch API ReferenceDescribeAlarmsForMetric

DescriptionName

A list of information for each alarm with the specified metric.Type: MetricAlarm (p. 29) list

MetricAlarms


Amazon CloudWatch API ReferenceResponse Elements

DisableAlarmActions

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



YesThe names of the alarms to disable actions for.Type: String list


AlarmNames.member.N


Amazon CloudWatch API ReferenceDisableAlarmActions

EnableAlarmActions

DescriptionEnables actions for the specified alarms.



YesThe names of the alarms to enable actions for.Type: String list


AlarmNames.member.N


Amazon CloudWatch API ReferenceEnableAlarmActions

GetMetricStatistics

DescriptionGets statistics for the specified metric.

Note

The maximum number of data points returned from a single GetMetricStatistics requestis 1,440. If a request is made that generates more than 1,440 data points, Amazon CloudWatchreturns an error. In such a case, alter the request by narrowing the specified time range orincreasing the specified period. Alternatively, 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.

Note

The maximum number of data points that can be queried is 50,850; whereas the maximumnumber of data points returned is 1,440.

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 CloudWatch Support for AWS Products in the AmazonCloudWatch Developer Guide.



NoA list of dimensions describing qualities of the metric.Type: Dimension (p. 27) list


Dimensions.member.N

YesThe time stamp to use for determining the last datapoint toreturn. The value specified is exclusive; results will includedatapoints up to the time stamp specified.Type: DateTime

EndTime


Amazon CloudWatch API ReferenceGetMetricStatistics

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


YesThe name of the metric.Type: String


MetricName

YesThe namespace of the metric.Type: String


Namespace

YesThe granularity, in seconds, of the returned datapoints.Period must be at least 60 seconds and must be a multipleof 60. The default value is 60.Type: Integer

Period

YesThe time stamp to use for determining the first datapoint toreturn. The value specified is inclusive; results includedatapoints with the time stamp specified.

Note

The specified start time is rounded down to thenearest value. Datapoints are returned for start timesup to two weeks in the past. Specified start times thatare more than two weeks in the past will not returndatapoints for metrics that are older than two weeks.

Type: DateTime

StartTime

YesThe metric statistics to return. For information about specificstatistics returned by GetMetricStatistics, go to Statistics inthe Amazon CloudWatch Developer Guide.

Valid Values: Average | Sum | SampleCount |Maximum | MinimumType: String list


Statistics.member.N

YesThe 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 |Kilobits/Second | Megabits/Second |Gigabits/Second | Terabits/Second |Count/Second | None

Unit


Amazon CloudWatch API ReferenceRequest Parameters

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

Response ElementsThe following elements come wrapped in a GetMetricStatisticsResult structure.

DescriptionName

The datapoints for the specified metric.Type: Datapoint (p. 25) list

Datapoints

A label describing the specified metric.Type: String

Label


HTTPStatusCode

DescriptionError

500Indicates that the request processing has failed dueto some unknown error, exception, or failure.

InternalService

400Parameters that must not be used together were usedtogether.

InvalidParameterCombination

400Bad or out-of-range value was supplied for the inputparameter.

InvalidParameterValue

400An input parameter that is mandatory for processingthe request is not supplied.

MissingRequiredParameter


Amazon CloudWatch API ReferenceResponse Elements

ListMetrics

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

Note

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

Note

If you create a metric with the PutMetricData (p. 20) 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. 12).



NoA list of dimensions to filter against.Type: DimensionFilter (p. 28) list


Dimensions.member.N

NoThe name of the metric to filter against.Type: String


MetricName

NoThe namespace to filter against.Type: String


Namespace

NoThe token returned by a previous call to indicate that there ismore data available.Type: String

NextToken

Response ElementsThe following elements come wrapped in a ListMetricsResult structure.

DescriptionName

A list of metrics used to generate statistics for an AWS account.Type: Metric (p. 29) list

Metrics


Amazon CloudWatch API ReferenceListMetrics

DescriptionName


NextToken


HTTPStatusCode

DescriptionError

500Indicates that the request processing has failed due to someunknown error, exception, or failure.

InternalService

400Bad or out-of-range value was supplied for the input parameter.InvalidParameterValue



PutMetricAlarm

DescriptionCreates 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 StateValueis then executed.

Note

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



NoIndicates whether or not actions should beexecuted during any changes to thealarm's state.Type: Boolean

ActionsEnabled

NoThe list of actions to execute when thisalarm transitions into an ALARM state fromany other state. Each action is specifiedas an Amazon Resource Number (ARN).Currently the only action supported ispublishing to an Amazon SNS topic or anAmazon Auto Scaling policy.Type: String list

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

AlarmActions.member.N

NoThe description for the alarm.Type: String

Length constraints: Minimum value of 0.Maximum value of 255.

AlarmDescription

YesThe descriptive name for the alarm. Thisname must be unique within the user'sAWS accountType: String


AlarmName


Amazon CloudWatch API ReferencePutMetricAlarm


YesThe arithmetic operation to use whencomparing the specified Statistic andThreshold. The specified Statisticvalue is used as the first operand.Type: String

Valid Values:GreaterThanOrEqualToThreshold |GreaterThanThreshold |LessThanThreshold |LessThanOrEqualToThreshold

ComparisonOperator

NoThe dimensions for the alarm's associatedmetric.Type: Dimension (p. 27) list

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

Dimensions.member.N

YesThe number of periods over which data iscompared to the specified threshold.Type: Integer

EvaluationPeriods

NoThe list of actions to execute when thisalarm transitions into anINSUFFICIENT_DATA state from any otherstate. Each action is specified as anAmazon Resource Number (ARN).Currently the only action supported ispublishing to an Amazon SNS topic or anAmazon Auto Scaling policy.Type: String list


InsufficientDataActions.member.N

YesThe name for the alarm's associatedmetric.Type: String


MetricName

YesThe namespace for the alarm's associatedmetric.Type: String


Namespace


Amazon CloudWatch API ReferenceRequest Parameters


NoThe list of actions to execute when thisalarm transitions into an OK state from anyother state. Each action is specified as anAmazon Resource Number (ARN).Currently the only action supported ispublishing to an Amazon SNS topic or anAmazon Auto Scaling policy.Type: String list


OKActions.member.N

YesThe period in seconds over which thespecified statistic is applied.Type: Integer

Period

YesThe statistic to apply to the alarm'sassociated metric.Type: String

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

Statistic

YesThe value against which the specifiedstatistic is compared.Type: Double

Threshold

NoThe unit for the alarm's associated 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| Kilobits/Second |Megabits/Second |Gigabits/Second |Terabits/Second | Count/Second| None

Unit


HTTPStatusCode

DescriptionError

400The quota for alarms for this customer has already been reached.LimitExceeded



PutMetricData

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

Note

If you create a metric with the PutMetricData action, allow up to fifteen minutes for the metricto appear in calls to the ListMetrics (p. 15) action.

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

Important

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



YesA list of data describing the metric.Type: MetricDatum (p. 32) list

MetricData.member.N

YesThe namespace for the metric data.

Note

You cannot specify a namespace that begins with"AWS/". Namespaces that begin with "AWS/" arereserved for other Amazon Web Services productsthat send metrics to Amazon CloudWatch.

Type: String


Namespace



Amazon CloudWatch API ReferencePutMetricData

HTTPStatusCode

DescriptionError

500Indicates that the request processing has failed dueto some unknown error, exception, or failure.

InternalService

400Parameters that must not be used together were usedtogether.


400Bad or out-of-range value was supplied for the inputparameter.


400An input parameter that is mandatory for processingthe request is not supplied.

MissingRequiredParameter

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.MetricName=buffers&MetricData.member.1.Unit=Bytes&MetricData.member.1.Value=231434333&MetricData.member.1.Dimensions.member.1.Name=InstanceID&MetricData.member.1.Dimensions.member.1.Value=i-aaba32d4&MetricData.member.1.Dimensions.member.2.Name=InstanceType&MetricData.member.1.Dimensions.member.2.Value=m1.small&AUTHPARAMS

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

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


Amazon CloudWatch API ReferenceExamples

&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=InstanceID&MetricData.member.1.Dimensions.member.1.Value=i-aaba32d4&MetricData.member.1.Dimensions.member.2.Name=InstanceType&MetricData.member.1.Dimensions.member.2.Value=m1.small&MetricData.member.2.MetricName=latency&MetricData.member.2.Unit=Milliseconds&MetricData.member.2.Value=23&MetricData.member.2.Dimensions.member.1.Name=InstanceID&MetricData.member.2.Dimensions.member.1.Value=i-aaba32d4&MetricData.member.2.Dimensions.member.2.Name=InstanceType&MetricData.member.2.Dimensions.member.2.Value=m1.small&AUTHPARAMS

Sample Response

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

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


Amazon CloudWatch API ReferenceExamples

SetAlarmState

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



YesThe descriptive name for the alarm. This name must be uniquewithin the user's AWS account. The maximum length is 255characters.Type: String


AlarmName

YesThe reason that this alarm is set to this specific state (inhuman-readable text format)Type: String


StateReason

NoThe reason that this alarm is set to this specific state (inmachine-readable JSON format)Type: String


StateReasonData

YesThe value of the state.Type: String

Valid Values: OK | ALARM | INSUFFICIENT_DATA

StateValue


HTTPStatusCode

DescriptionError

400Data was not syntactically valid JSON.InvalidFormat

404The named resource does not exist.ResourceNotFound


Amazon CloudWatch API ReferenceSetAlarmState

Data Types

The Amazon CloudWatch API contains several data types that various actions use.This section describeseach data type in detail.

Note

The order of each element in the response is not guaranteed. Applications should not assumea particular order.

The following data types are supported:

• AlarmHistoryItem (p. 25)

• Datapoint (p. 25)

• DescribeAlarmHistoryResult (p. 26)

• DescribeAlarmsForMetricResult (p. 26)

• DescribeAlarmsResult (p. 27)

• Dimension (p. 27)

• DimensionFilter (p. 28)

• GetMetricStatisticsResult (p. 28)

• ListMetricsResult (p. 28)

• Metric (p. 29)

• MetricAlarm (p. 29)

• MetricDatum (p. 32)

• StatisticSet (p. 33)



AlarmHistoryItem

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

Contents

DescriptionName

The descriptive name for the alarm.Type: String


AlarmName

Machine-readable data about the alarm in JSON format.Type: String


HistoryData

The type of alarm history item.Type: String

Valid Values: ConfigurationUpdate | StateUpdate | Action

HistoryItemType

A human-readable summary of the alarm history.Type: String


HistorySummary

The time stamp for the alarm history item.Type: DateTime

Timestamp

Datapoint

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

Contents

DescriptionName

The average of metric values that correspond to the datapoint.Type: Double

Average

The maximum of the metric value used for the datapoint.Type: Double

Maximum


Amazon CloudWatch API ReferenceAlarmHistoryItem

DescriptionName

The minimum metric value used for the datapoint.Type: Double

Minimum

The number of metric values that contributed to the aggregate value of this datapoint.Type: Double

SampleCount

The sum of metric values used for the datapoint.Type: Double

Sum

The time stamp used for the datapoint.Type: DateTime

Timestamp

The standard unit used for the datapoint.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 | Kilobits/Second | Megabits/Second| Gigabits/Second | Terabits/Second | Count/Second | None

Unit

DescribeAlarmHistoryResult

DescriptionThe output for the DescribeAlarmHistory (p. 4) action.

Contents

DescriptionName

A list of alarm histories in JSON format.Type: AlarmHistoryItem (p. 25) list

AlarmHistoryItems


NextToken

DescribeAlarmsForMetricResult

DescriptionThe output for the DescribeAlarmsForMetric (p. 8) action.


Amazon CloudWatch API ReferenceDescribeAlarmHistoryResult

Contents

DescriptionName

A list of information for each alarm with the specified metric.Type: MetricAlarm (p. 29) list

MetricAlarms

DescribeAlarmsResult

DescriptionThe output for the DescribeAlarms (p. 6) action.

Contents

DescriptionName

A list of information for the specified alarms.Type: MetricAlarm (p. 29) list

MetricAlarms


NextToken

Dimension

DescriptionThe 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. 20).

Contents

DescriptionName

The name of the dimension.Type: String


Name

The value representing the dimension measurementType: String


Value


Amazon CloudWatch API ReferenceContents

DimensionFilter

DescriptionThe DimensionFilter data type is used to filter ListMetrics (p. 15) results.

Contents

DescriptionName

The dimension name to be matched.Type: String


Name

The value of the dimension to be matched.

Note

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

Type: String


Value

GetMetricStatisticsResult

DescriptionThe output for the GetMetricStatistics (p. 12) action.

Contents

DescriptionName

The datapoints for the specified metric.Type: Datapoint (p. 25) list

Datapoints

A label describing the specified metric.Type: String

Label

ListMetricsResult

DescriptionThe output for the ListMetrics (p. 15) action.


Amazon CloudWatch API ReferenceDimensionFilter

Contents

DescriptionName

A list of metrics used to generate statistics for an AWS account.Type: Metric (p. 29) list

Metrics


NextToken

Metric

DescriptionThe Metric data type contains information about a specific metric. If you call ListMetrics (p. 15), 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

DescriptionName

A list of dimensions associated with the metric.Type: Dimension (p. 27) list

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

Dimensions

The name of the metric.Type: String


MetricName

The namespace of the metric.Type: String


Namespace

MetricAlarm

DescriptionThe MetricAlarm (p. 29) data type represents an alarm.You can use PutMetricAlarm (p. 17) to create orupdate an alarm.



Contents

DescriptionName

Indicates whether actions should be executed duringany changes to the alarm's state.Type: Boolean

ActionsEnabled

The list of actions to execute when this alarmtransitions into an ALARM state from any other state.Each action is specified as an Amazon ResourceNumber (ARN). Currently the only actions supportedare publishing to an Amazon SNS topic andtriggering an Auto Scaling policy.Type: String list

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

AlarmActions

The Amazon Resource Name (ARN) of the alarm.Type: String

Length constraints: Minimum value of 1. Maximumvalue of 1600.

AlarmArn

The time stamp of the last update to the alarmconfiguration.Type: DateTime

AlarmConfigurationUpdatedTimestamp

The description for the alarm.Type: String


AlarmDescription

The name of the alarm.Type: String


AlarmName

The arithmetic operation to use when comparing thespecified Statistic and Threshold.The specifiedStatistic value is used as the first operand.Type: String

Valid Values:GreaterThanOrEqualToThreshold| GreaterThanThreshold |LessThanThreshold |LessThanOrEqualToThreshold

ComparisonOperator

The list of dimensions associated with the alarm'sassociated metric.Type: Dimension (p. 27) list


Dimensions

The number of periods over which data is comparedto the specified threshold.Type: Integer

EvaluationPeriods



DescriptionName

The list of actions to execute when this alarmtransitions into an INSUFFICIENT_DATA state fromany other state. Each action is specified as anAmazon Resource Number (ARN). Currently theonly actions supported are publishing to an AmazonSNS topic or triggering an Auto Scaling policy.

Important

The current WSDL lists this attribute asUnknownActions.

Type: String list


InsufficientDataActions

The name of the alarm's metric.Type: String


MetricName

The namespace of alarm's associated metric.Type: String


Namespace

The list of actions to execute when this alarmtransitions into an OK state from any other state.Each action is specified as an Amazon ResourceNumber (ARN). Currently the only actions supportedare publishing to an Amazon SNS topic andtriggering an Auto Scaling policy.Type: String list


OKActions

The period in seconds over which the statistic isapplied.Type: Integer

Period

A human-readable explanation for the alarm's state.Type: String


StateReason

An explanation for the alarm's state inmachine-readable JSON formatType: String


StateReasonData



DescriptionName

The time stamp of the last update to the alarm'sstate.Type: DateTime

StateUpdatedTimestamp

The state value for the alarm.Type: String

Valid Values: OK | ALARM |INSUFFICIENT_DATA

StateValue

The statistic to apply to the alarm's associatedmetric.Type: String

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

Statistic

The value against which the specified statistic iscompared.Type: Double

Threshold

The unit of the alarm's associated 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 |Kilobits/Second | Megabits/Second |Gigabits/Second | Terabits/Second |Count/Second | None

Unit

MetricDatum

DescriptionThe MetricDatum data type encapsulates the information sent with PutMetricData (p. 20) to either createa new metric or add new values to be aggregated into an existing metric.

Contents

DescriptionName

A list of dimensions associated with the metric.Type: Dimension (p. 27) list

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

Dimensions


Amazon CloudWatch API ReferenceMetricDatum

DescriptionName

The name of the metric.Type: String


MetricName

A set of statistical values describing the metric.Type: StatisticSet (p. 33)

StatisticValues

The time stamp used for the metric. If not specified, the default value is set tothe time the metric data was received.Type: DateTime

Timestamp

The unit of 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 |Kilobits/Second | Megabits/Second | Gigabits/Second |Terabits/Second | Count/Second | None

Unit

The value for the metric.

Important

Although the Value parameter accepts numbers of type Double,Amazon CloudWatch truncates values with very large exponents.Valueswith 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 also truncated.

Type: Double

Value

StatisticSet

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

Contents

DescriptionName

The maximum value of the sample set.Type: Double

Maximum

The minimum value of the sample set.Type: Double

Minimum


Amazon CloudWatch API ReferenceStatisticSet

DescriptionName

The number of samples used for the statistic set.Type: Double

SampleCount

The sum of values for the sample set.Type: Double

Sum



Common Query Parameters

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

RequiredDescriptionParameter Name

YesThe action to perform.

Default: None

Type: String

Action

ConditionalThe parameters required to authenticate a queryrequest.

Contains:

AWSAccessKeyID

SignatureVersion

Timestamp

Signature

Default: None

AuthParams

YesThe Access Key ID corresponding to the AWS SecretAccess Key you used to sign the request.

Default: None

Type: String

AWSAccessKeyId

ConditionalThe date and time at which the request signatureexpires, in the format YYYY-MM-DDThh:mm:ssZ, asspecified in the ISO 8601 standard.

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

Default: None

Type: String

Expires



RequiredDescriptionParameter Name

The temporary security token obtained through a callto AWS Security Token Service. Only available foractions in the following AWS services: Amazon EC2,Amazon Simple Notification Service, Amazon SQS,and AWS SimpleDB.

Default: None

Type: String

SecurityToken

YesThe digital signature you created for the request. Referto the service's developer documentation for informationabout how to generate the signature.

Default: None

Type: String

Signature

YesThe hash algorithm you used to create the requestsignature.

Default: None

Valid Values: HmacSHA256 | HmacSHA1.

Type: String

SignatureMethod

YesThe signature version you use to sign the request. Setthis to the value recommended in your product-specificdocumentation on security.

Default: None

Type: String

SignatureVersion

ConditionalThe date and time the request was signed, in the formatYYYY-MM-DDThh:mm:ssZ, as specified in the ISO8601 standard.

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

Default: None

Type: String

Timestamp

YesThe API version to use, in the format YYYY-MM-DD.

Default: None

Type: String

Version



Common Errors

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

HTTPStatusCode

DescriptionError

400The request signature does not conform toAWS standards.

IncompleteSignature

500The request processing has failed due to someunknown error, exception or failure.

InternalFailure

400The action or operation requested is invalid.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.


400A bad or out-of-range value was supplied forthe input parameter.


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

InvalidQueryParameter

404The query string is malformed.MalformedQueryString

400The request is missing an action or operationparameter.

MissingAction

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

MissingAuthenticationToken

400An input parameter that is mandatory forprocessing the request is not supplied.

MissingParameter



HTTPStatusCode

DescriptionError

403The AWS Access Key ID needs a subscriptionfor the service.

OptInRequired

400Request is past expires date or the requestdate (either with 15 minute padding), or therequest date occurs more than 15 minutes inthe future.

RequestExpired

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

ServiceUnavailable

400Request was denied due to request throttling.Throttling



acw-api

Documents

auto scaling

string length

amazon sns

parameter

amazon resource

amazon cloudwatch

string valid

common query