acw-api
TRANSCRIPT
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
Amazon CloudWatch API Reference
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.
API Version 2010-08-011
Amazon CloudWatch API Reference
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)
API Version 2010-08-012
Amazon CloudWatch API Reference
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
API Version 2010-08-013
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.
Request ParametersFor information about the common parameters that all actions use, see Common Query Parameters (p. 35).
RequiredDescriptionName
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
API Version 2010-08-014
Amazon CloudWatch API ReferenceDescribeAlarmHistory
ErrorsFor information about the common errors that all actions use, see Common Errors (p. 37).
HTTPStatusCode
DescriptionError
400The next token specified is invalid.InvalidNextToken
API Version 2010-08-015
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.
Request ParametersFor information about the common parameters that all actions use, see Common Query Parameters (p. 35).
RequiredDescriptionName
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
Length constraints: Minimum value of 1. Maximum value of255.
AlarmNamePrefix
NoA list of alarm names to retrieve information for.Type: String list
Length constraints: Minimum of 0 item(s) in the list. Maximumof 100 item(s) in the 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
A string that marks the start of the next batch of returned results.Type: String
NextToken
API Version 2010-08-016
Amazon CloudWatch API ReferenceDescribeAlarms
ErrorsFor information about the common errors that all actions use, see Common Errors (p. 37).
HTTPStatusCode
DescriptionError
400The next token specified is invalid.InvalidNextToken
API Version 2010-08-017
Amazon CloudWatch API ReferenceErrors
DescribeAlarmsForMetric
DescriptionRetrieves all alarms for a single metric. Specify a statistic, period, or unit to filter the set of alarms further.
Request ParametersFor information about the common parameters that all actions use, see Common Query Parameters (p. 35).
RequiredDescriptionName
NoThe list of dimensions associated with the metric.Type: Dimension (p. 27) list
Length constraints: Minimum of 0 item(s) in the list. Maximumof 10 item(s) in the list.
Dimensions.member.N
YesThe name of the metric.Type: String
Length constraints: Minimum value of 1. Maximum value of255.
MetricName
YesThe namespace of the metric.Type: String
Length constraints: Minimum value of 1. Maximum value of255.
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.
API Version 2010-08-018
Amazon CloudWatch API ReferenceDescribeAlarmsForMetric
DescriptionName
A list of information for each alarm with the specified metric.Type: MetricAlarm (p. 29) list
MetricAlarms
API Version 2010-08-019
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.
Request ParametersFor information about the common parameters that all actions use, see Common Query Parameters (p. 35).
RequiredDescriptionName
YesThe names of the alarms to disable actions for.Type: String list
Length constraints: Minimum of 0 item(s) in the list. Maximumof 100 item(s) in the list.
AlarmNames.member.N
API Version 2010-08-0110
Amazon CloudWatch API ReferenceDisableAlarmActions
EnableAlarmActions
DescriptionEnables actions for the specified alarms.
Request ParametersFor information about the common parameters that all actions use, see Common Query Parameters (p. 35).
RequiredDescriptionName
YesThe names of the alarms to enable actions for.Type: String list
Length constraints: Minimum of 0 item(s) in the list. Maximumof 100 item(s) in the list.
AlarmNames.member.N
API Version 2010-08-0111
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.
Request ParametersFor information about the common parameters that all actions use, see Common Query Parameters (p. 35).
RequiredDescriptionName
NoA list of dimensions describing qualities of the metric.Type: Dimension (p. 27) list
Length constraints: Minimum of 0 item(s) in the list. Maximumof 10 item(s) in the 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
API Version 2010-08-0112
Amazon CloudWatch API ReferenceGetMetricStatistics
RequiredDescriptionName
YesThe name of the metric.Type: String
Length constraints: Minimum value of 1. Maximum value of255.
MetricName
YesThe namespace of the metric.Type: String
Length constraints: Minimum value of 1. Maximum value of255.
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
Length constraints: Minimum of 1 item(s) in the list. Maximumof 5 item(s) in the 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
API Version 2010-08-0113
Amazon CloudWatch API ReferenceRequest Parameters
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
ErrorsFor information about the common errors that all actions use, see Common Errors (p. 37).
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
API Version 2010-08-0114
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).
Request ParametersFor information about the common parameters that all actions use, see Common Query Parameters (p. 35).
RequiredDescriptionName
NoA list of dimensions to filter against.Type: DimensionFilter (p. 28) list
Length constraints: Minimum of 0 item(s) in the list. Maximumof 10 item(s) in the list.
Dimensions.member.N
NoThe name of the metric to filter against.Type: String
Length constraints: Minimum value of 1. Maximum value of255.
MetricName
NoThe namespace to filter against.Type: String
Length constraints: Minimum value of 1. Maximum value of255.
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
API Version 2010-08-0115
Amazon CloudWatch API ReferenceListMetrics
DescriptionName
A string that marks the start of the next batch of returned results.Type: String
NextToken
ErrorsFor information about the common errors that all actions use, see Common Errors (p. 37).
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
API Version 2010-08-0116
Amazon CloudWatch API ReferenceErrors
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.
Request ParametersFor information about the common parameters that all actions use, see Common Query Parameters (p. 35).
RequiredDescriptionName
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
Length constraints: Minimum value of 1.Maximum value of 255.
AlarmName
API Version 2010-08-0117
Amazon CloudWatch API ReferencePutMetricAlarm
RequiredDescriptionName
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
Length constraints: Minimum of 0 item(s)in the list. Maximum of 5 item(s) in the list.
InsufficientDataActions.member.N
YesThe name for the alarm's associatedmetric.Type: String
Length constraints: Minimum value of 1.Maximum value of 255.
MetricName
YesThe namespace for the alarm's associatedmetric.Type: String
Length constraints: Minimum value of 1.Maximum value of 255.
Namespace
API Version 2010-08-0118
Amazon CloudWatch API ReferenceRequest Parameters
RequiredDescriptionName
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
Length constraints: Minimum of 0 item(s)in the list. Maximum of 5 item(s) in the 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
ErrorsFor information about the common errors that all actions use, see Common Errors (p. 37).
HTTPStatusCode
DescriptionError
400The quota for alarms for this customer has already been reached.LimitExceeded
API Version 2010-08-0119
Amazon CloudWatch API ReferenceErrors
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.
Request ParametersFor information about the common parameters that all actions use, see Common Query Parameters (p. 35).
RequiredDescriptionName
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
Length constraints: Minimum value of 1. Maximum value of255.
Namespace
ErrorsFor information about the common errors that all actions use, see Common Errors (p. 37).
API Version 2010-08-0120
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.
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
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
API Version 2010-08-0121
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>
API Version 2010-08-0122
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.
Request ParametersFor information about the common parameters that all actions use, see Common Query Parameters (p. 35).
RequiredDescriptionName
YesThe descriptive name for the alarm. This name must be uniquewithin the user's AWS account. The maximum length is 255characters.Type: String
Length constraints: Minimum value of 1. Maximum value of 255.
AlarmName
YesThe reason that this alarm is set to this specific state (inhuman-readable text format)Type: String
Length constraints: Minimum value of 0. Maximum value of 1023.
StateReason
NoThe reason that this alarm is set to this specific state (inmachine-readable JSON format)Type: String
Length constraints: Minimum value of 0. Maximum value of 4000.
StateReasonData
YesThe value of the state.Type: String
Valid Values: OK | ALARM | INSUFFICIENT_DATA
StateValue
ErrorsFor information about the common errors that all actions use, see Common Errors (p. 37).
HTTPStatusCode
DescriptionError
400Data was not syntactically valid JSON.InvalidFormat
404The named resource does not exist.ResourceNotFound
API Version 2010-08-0123
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)
API Version 2010-08-0124
Amazon CloudWatch API Reference
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
Length constraints: Minimum value of 1. Maximum value of 255.
AlarmName
Machine-readable data about the alarm in JSON format.Type: String
Length constraints: Minimum value of 1. Maximum value of 4095.
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
Length constraints: Minimum value of 1. Maximum value of 255.
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
API Version 2010-08-0125
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
A string that marks the start of the next batch of returned results.Type: String
NextToken
DescribeAlarmsForMetricResult
DescriptionThe output for the DescribeAlarmsForMetric (p. 8) action.
API Version 2010-08-0126
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
A string that marks the start of the next batch of returned results.Type: String
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
Length constraints: Minimum value of 1. Maximum value of 255.
Name
The value representing the dimension measurementType: String
Length constraints: Minimum value of 1. Maximum value of 255.
Value
API Version 2010-08-0127
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
Length constraints: Minimum value of 1. Maximum value of 255.
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
Length constraints: Minimum value of 1. Maximum value of 255.
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.
API Version 2010-08-0128
Amazon CloudWatch API ReferenceDimensionFilter
Contents
DescriptionName
A list of metrics used to generate statistics for an AWS account.Type: Metric (p. 29) list
Metrics
A string that marks the start of the next batch of returned results.Type: String
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
Length constraints: Minimum value of 1. Maximum value of 255.
MetricName
The namespace of the metric.Type: String
Length constraints: Minimum value of 1. Maximum value of 255.
Namespace
MetricAlarm
DescriptionThe MetricAlarm (p. 29) data type represents an alarm.You can use PutMetricAlarm (p. 17) to create orupdate an alarm.
API Version 2010-08-0129
Amazon CloudWatch API ReferenceContents
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
Length constraints: Minimum value of 0. Maximumvalue of 255.
AlarmDescription
The name of the alarm.Type: String
Length constraints: Minimum value of 1. Maximumvalue of 255.
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
Length constraints: Minimum of 0 item(s) in the list.Maximum of 10 item(s) in the list.
Dimensions
The number of periods over which data is comparedto the specified threshold.Type: Integer
EvaluationPeriods
API Version 2010-08-0130
Amazon CloudWatch API ReferenceContents
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
Length constraints: Minimum of 0 item(s) in the list.Maximum of 5 item(s) in the list.
InsufficientDataActions
The name of the alarm's metric.Type: String
Length constraints: Minimum value of 1. Maximumvalue of 255.
MetricName
The namespace of alarm's associated metric.Type: String
Length constraints: Minimum value of 1. Maximumvalue of 255.
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
Length constraints: Minimum of 0 item(s) in the list.Maximum of 5 item(s) in the 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
Length constraints: Minimum value of 0. Maximumvalue of 1023.
StateReason
An explanation for the alarm's state inmachine-readable JSON formatType: String
Length constraints: Minimum value of 0. Maximumvalue of 4000.
StateReasonData
API Version 2010-08-0131
Amazon CloudWatch API ReferenceContents
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
API Version 2010-08-0132
Amazon CloudWatch API ReferenceMetricDatum
DescriptionName
The name of the metric.Type: String
Length constraints: Minimum value of 1. Maximum value of 255.
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
API Version 2010-08-0133
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
API Version 2010-08-0134
Amazon CloudWatch API ReferenceContents
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
API Version 2010-08-0135
Amazon CloudWatch API Reference
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
API Version 2010-08-0136
Amazon CloudWatch API Reference
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.
InvalidParameterCombination
400A bad or out-of-range value was supplied forthe input parameter.
InvalidParameterValue
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
API Version 2010-08-0137
Amazon CloudWatch API Reference
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
API Version 2010-08-0138
Amazon CloudWatch API Reference