amazon cloud watch-dg

Amazon CloudWatchDeveloper Guide

API Version 2009-05-15

Amazon CloudWatch Developer Guide

Amazon CloudWatch: Developer GuideCopyright © 2009 Amazon Web Services LLC or its affiliates. All rights reserved.


Table of ContentsWelcome ............................................................................................................................................................ 1What's New ....................................................................................................................................................... 4Introduction to Amazon CloudWatch ................................................................................................................ 5Using Amazon CloudWatch ............................................................................................................................ 14

Getting Started with Amazon CloudWatch .......................................................................................... 16Using the Query API ........................................................................................................................... 19Using the SOAP API ........................................................................................................................... 22Metrics ................................................................................................................................................. 26Statistics .............................................................................................................................................. 28About Dimensions ............................................................................................................................... 29Amazon CloudWatch Dimensions ....................................................................................................... 31User Scenarios .................................................................................................................................... 32

Get Average CPUUtilization for EC2 Instances With a Particular ImageId ................................ 33Get Maximum CPUUtilization per EC2 Instance ....................................................................... 35Compare RequestCount by Availability Zone for a Load Balanced EC2 Application ................. 37Get Latency Statistics for a LoadBalancer ................................................................................ 39Get Total DiskWriteBytes for a Capacity-Managed EC2 Application ......................................... 41Get A Single Metric Across All Dimensions .............................................................................. 43Get Available Metrics Across Multiple Instances ....................................................................... 45

API Reference ................................................................................................................................................. 47API Conventions .................................................................................................................................. 47Common Request Parameters ............................................................................................................ 49Error Codes ......................................................................................................................................... 50Amazon CloudWatch Operations ........................................................................................................ 54

GetMetricStatistics ...................................................................................................................... 55ListMetrics .................................................................................................................................. 60

Data Types .......................................................................................................................................... 62Datapoint .................................................................................................................................... 63Datapoints .................................................................................................................................. 64Dimension .................................................................................................................................. 65Dimensions ................................................................................................................................. 66StandardUnit ............................................................................................................................... 67Statistics ..................................................................................................................................... 68

Glossary .......................................................................................................................................................... 69Document Conventions ................................................................................................................................... 71Index ................................................................................................................................................................ 74

Amazon CloudWatch Developer GuideWho Should Read This Guide


Welcome

Topics

• Who Should Read This Guide (p. 1)

• How This Guide Is Organized (p. 2)

• Amazon CloudWatch Resources (p. 2)

Amazon CloudWatch is an easy-to-use web service that provides comprehensive monitoring forAmazon Elastic Compute Cloud (Amazon EC2) and Elastic Load Balancing.

This is the Amazon CloudWatch Developer Guide. This section describes who should read this guide,how the guide is organized, and other resources related to Amazon CloudWatch.

The following Amazon Web Services (AWS) products will occasionally be referred to using thefollowing abbreviated forms; all copyrights and legal protections still apply.

Full Name Abbreviated Form

Amazon Elastic ComputeCloud

Amazon EC2

Amazon Machine Image AMI

Who Should Read This GuideThis guide is intended for developers, as well as those in IT/Operations, who are building webapplications or services hosted in the Amazon Elastic Compute Cloud.

Required Knowledge and SkillsUse of this guide assumes you are familiar with the following:

• XML. For an overview, go to the W3 Schools XML Tutorial.

• Web services. For an overview, go to the W3 Schools Web Services Tutorial.

http://www.w3schools.com/xml/default.asp

http://www.w3schools.com/webservices/default.asp

Amazon CloudWatch Developer GuideHow This Guide Is Organized


• A programming language for consuming a web service and any related tools.

• Programming Amazon Elastic Cloud Computing (EC2) applications or services that use AmazonEC2 web service APIs. For information about Amazon EC2, go to the Amazon EC2 productinformation page.

How This Guide Is OrganizedThis guide is organized into several major sections described in the table below.

Information Relevant Sections

General information about AmazonCloudWatch

What is Amazon CloudWatch? (p. 6)

Conceptual information about AmazonCloudWatch

• Conceptual Overview of Amazon CloudWatch (p. 10)

• Terminology and Key Concepts (p. 7)

API Reference and ProgrammingRelated Information

• API Reference (p. 47)

• Using Amazon CloudWatch (p. 14)

Typographic and symbol conventions Document Conventions (p. 71)

There are more sections under each category to help you with more specific information as well as aglossary and an index. Most sections are written to stand on their own with some cross dependencies.You should, in general, be able to look up the information you need and go back to work. However, youcan also read through the major sections sequentially to get in-depth knowledge about the service.

Amazon CloudWatch ResourcesThe table below lists related resources that you'll find useful as you work with this service.

Resource Description

Amazon CloudWatch Technical FAQ The FAQ covers the top 20 questions developers haveasked about this product.

Release notes The release notes give a high-level overview of thecurrent release. They specifically note any new features,corrections, and known issues.

AWS Developer Resource Center A central starting point to find documentation, codesamples, release notes, and other information to help youbuild innovative applications with AWS.

AWS Management Console The console allows you to perform most of the functionsof Amazon CloudWatch and various other AWS productswithout programming.

Discussion Forums A community-based forum for developers to discusstechnical questions related to Amazon Web Services.

AWS Support Center The home page for AWS Technical Support, includingaccess to our Developer Forums, Technical FAQs, ServiceStatus page, and Premium Support.

http://aws.amazon.com/ec2

http://aws.amazon.com/ec2

http://aws.amazon.com/ec2/faqs/

http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=86


http://aws.amazon.com/console/

http://developer.amazonwebservices.com/connect/forum.jspa?forumID=30

http://developer.amazonwebservices.com/connect/support.jspa

Amazon CloudWatch Developer GuideAmazon CloudWatch Resources


Resource Description

AWS Premium Support The primary web page for information about AWS PremiumSupport, a one-on-one, fast-response support channel tohelp you build and run applications on AWS InfrastructureServices.

Amazon CloudWatch productinformation

The primary web page for information about AmazonCloudWatch.

Contact Us A central contact point for inquiries concerning AWS billing,account, events, abuse etc.

Conditions of Use Detailed information about the copyright and trademarkusage at Amazon.com and other topics.

http://aws.amazon.com/premiumsupport

http://aws.amazon.com/cloudwatch/

http://aws.amazon.com/cloudwatch/

http://aws.amazon.com/contact-us/

http://www.amazon.com/gp/help/customer/display.html/104-5054883-7838319?ie=UTF8&%2AVersion%2A=1&nodeId=508088&%2Aentries%2A=0



What's New

This What's New is associated with the 2009-05-15 release of Amazon CloudWatch. This guide waslast updated on December 09, 2009.

The following table describes the important changes since the last release of the Amazon CloudWatchDeveloper Guide.

Change Description Release Date

Updated/addedcontent

Added new US-West (Northern California) Regioninformation.

02 December 2009

Added content Added information about .NET SDK support. Formore information, see Programming LanguageSupport (p. 22).

11 November 2009

Added/updatedcontent

Bug fixes; added new Region information. 14 September 2009

Added content Added instructions on how to enable monitoringusing the AWS Management Console to the GettingStarted (p. 16) section.

31 August 2009

Updated content Bug fixes. 21 July 2009

Added content Instructions for Command Line Tools have beenadded to the User Scenarios (p. 32) section.

28 May 2009

New Service This is the first release of Amazon CloudWatchDeveloper Guide. Future updates and changes willbe noted here.

18 May 2009



Introduction to AmazonCloudWatch

Topics

• What Is Amazon CloudWatch? (p. 6)

• Amazon CloudWatch Concepts (p. 7)

• Amazon CloudWatch Conceptual Overview (p. 10)

This introduction is intended to give you a detailed summary of this set of web services. After readingthis section, you should have a good idea of what they offer and how they can fit with your businessand application needs.

Amazon CloudWatch Developer GuideWhat Is Amazon CloudWatch?


What Is Amazon CloudWatch?Amazon CloudWatch is an easy to use web service that provides visibility into your cloud assets. It isdesigned to provide comprehensive monitoring for all of the following AWS services:

• Amazon Elastic Compute Cloud or Amazon EC2 (including instances of paid AMIs)

• Elastic Load Balancing

Benefits• Visibility—Amazon CloudWatch enables visibility into all of your cloud assets. You receive

comprehensive operational views of all AWS services.

• Ease of Use—Amazon CloudWatch uses a simple API call for developers. There is no upfront setupin order to start getting the metrics.

Amazon CloudWatch Developer GuideAmazon CloudWatch Concepts


Amazon CloudWatch ConceptsThis section introduces you to Amazon CloudWatch terminology and concepts. Many of the conceptsintroduced here are discussed in more specific contexts in later sections. The concepts are brieflypresented here to give you a basic understanding of common Amazon CloudWatch terms.

DimensionA dimension is used by the developer to specify how a measure will be aggregated, such as byInstanceID, Availability Zone, or AutoScalingGroup. If you do not specify a dimension name or value,then all data for a particular measure and timespan will be aggregated into a single metric.

For more information, see About Dimensions (p. 29). For a list of currently available dimensions,please see Amazon CloudWatch Dimensions (p. 31).

MeasureA measure is an observed value with a name, a set of dimensions, a namespace, a unit, and atimestamp. Measures are the fundamental input to the Amazon CloudWatch. Measures are the rawdata that goes into the system and that are rolled up (aggregated) into bigger chunks called metrics.Measures have the following attributes:

• Measures have a unique name

• Measures might have one or more dimensions

• Measures can arrive at any time, in any order, with the same resulting metrics

• The service that the measure is recorded from is identified by the namespace

Measures have the following characteristics:

• If multiple measures with the same name and dimensions have the same measure values within thesame one-minute period, they will be rolled up into one-minute aggregations

• All incoming measurements for any time slot are buffered for one-minute to perform aggregationprocessing before they can be read

• Measures are retained by Amazon CloudWatch for a period of two weeks

MetricA metric is an aggregation of raw measure data that was published to Amazon CloudWatch,aggregated by a particular unit of measure, such as bytes or seconds. Metrics are the fundamentalstored elements in the Amazon CloudWatch system.

Metrics have the following attributes:

• A metric has a measure name that comes from or is derived from the input measures

• A metric may have additional dimensions to make it more specific, e.g. InstanceID="i-a123b4cd"

• Every metric has a unique set of matching criteria and a namespace

NamespaceNamespaces provide isolation within the Amazon CloudWatch system for metrics that were generatedby different sources. All AWS services that provide Amazon CloudWatch data use a namespace stringbeginning with “AWS/”.

Amazon CloudWatch Developer GuideStatistic


For example, all EC2 metrics are published using the Namespace “AWS/EC2”. This ensures thatcustomers who request data associated with the namespace “AWS/EC2” only get back results frommeasures that were stored by EC2.

At present, there are two AWS services that store data in Amazon CloudWatch: Amazon ElasticCompute Cloud (EC2) and Elastic Load Balancing (ELB).

• To request metrics from Amazon EC2, set the Namespace in your GetMetricStatistics call toAWS/EC2. For an example, see GetMetricStatistics (p. 55).

• To request metrics from Elastic Load Balancing (ELB), set the Namespace in yourGetMetricStatistics call to AWS/ELB. For a sample request, refer to the Elastic Load BalancingDeveloper Guide.

StatisticStatistics are attributes of a metric. They describe the distribution of measures that created eachAmazon CloudWatch metric.

Statistics can be used in the following ways:

• There following statistics are available: Minimum, Maximum, Sum and Average.

Note

Another statistic - Samples - is the count of the measurements that were used to compute areturn value. The Samples statistics is always returned and cannot be explicitly requested.

For example, if the values that are aggregated into a single metric are [1, 2, 5], then the statisticswould be the following: Samples = 3, Average = 4, Minimum = 1, Maximum = 5, and Sum = 8.

Please see Amazon CloudWatch Statistics Available (p. 28) for more information

• A statistic has only one value per one-minute period.

• A query using GetMetricStatistics (p. 55) specifies a finite period which aggregates all theenclosed one-minute time slots that have a value. This is known as time aggregation.

UnitEvery measure that is received by the system has a unit attached, such as seconds or bytes.

Units have the following characteristics:

• For a complete list of currently supported standard units, see StandardUnit (p. 67).

• The Units parameter is a filter for the GetMetricStatistics (p. 55) call. If you don't specify it, youget all the units that were used for the measure data when the data was put into the system. If youdo specify it, you get values that match your request. Specifying the units incorrectly can result in nodata being returned.

RegionsAmazon cloud computing resources are housed in highly available data center facilities. To provideadditional scalability and reliability, these data center facilities are located in several different physicallocations, known as Regions. Regions are large and widely dispersed geographic locations.

Amazon CloudWatch Developer GuideRegions


Note

Amazon CloudWatch does not aggregate data across Regions. Metrics are completelyseparate between Regions.

To work with instances in a specific Region, use the corresponding regional service endpoint.In the United States, the endpoints are:

• US Standard Region: https://monitoring.us-east-1.amazonaws.com

• US-West (Northern California) Region: https://monitoring.us-west-1.amazonaws.com

In the EU (Ireland) Region, the endpoint is:

• https://monitoring.eu-west-1.amazonaws.com

If no endpoint is explicitly specified, the US Standard Region endpoint is used by default.

Amazon CloudWatch Developer GuideAmazon CloudWatch Conceptual Overview


Amazon CloudWatch Conceptual OverviewAmazon CloudWatch collects raw data from AWS services such as Amazon Elastic Compute Cloud(EC2) and then processes the information into readable metrics. These metrics are recorded for aperiod of two weeks, allowing you to access historical information and providing you with a betterperspective on how your web application or service is performing.

Note

Amazon cloud computing resources can be physically located in one of several Regions.Amazon CloudWatch does not aggregate data across Regions.

The basic concept of the service is outlined in the following illustration. Amazon CloudWatch capturesthe raw data from the AWS service and creates metrics.

The raw, collected data gathered by Amazon Cloudwatch is known as a measure. A measure might besomething like CPUUtilization for a given EC2 instance, which is the percentage of EC2 compute unitsthe instance is using, or DiskWriteBytes, which is just the number of bytes that have been written.

A measure is comprised of its name, such as DiskWriteBytes, and its value, such as 0. Measures alsousually have a unit, such as Bytes. Measures also include a timestamp indicating when the data wasrecorded. Measures may include other attributes, called dimensions, which provide further context ifpresent.



The following information is part of the measure as it enters the Amazon CloudWatch system forprocessing:

• the measure's name (e.g. DiskWriteBytes)

• the unprocessed value (e.g. 20)

• the associated dimensions of this measure (e.g. InstanceType, InstanceId)

• a unit to determine the type of value (e.g. Bytes)

• a namespace to identify the service from which the measure was recorded (e.g. AWS/EC2)

Each of the blue boxes in the following illustration is a single measure from a single EC2 instance.

These measures have two dimensions:

• InstanceId—The name of the instance that generated the metric instance type

• InstanceType—The type of instance specified by the InstanceId (e.g. m1.small)

All of this information taken together makes the metric unique.



Processed data is called a metric. It has the same name, dimensions, namespace, and unit as theoriginal measures used to create the metric. A metric is the aggregate of all of the measures that arepublished to the system with a given name, within a single one-minute period. When you ask for datafrom Amazon CloudWatch, you are asking for metric data.

As Amazon CloudWatch processes measure data, the service rolls the incoming data into one-minutechunks. Therefore, if ten measures come in during a particular one-minute time slot, then ten measureswill be turned into a single chunk with statistics are that calculated to give different views of the datasuch as Average, Sum, Minimum, or Maximum.

In the following illustration, Amazon CloudWatch captures a set of 12 measures with two unique namesand processes them into two metrics.

You can query metric data using measure names, dimensions, and units for a specified measure oftime. For example, requesting the CPUUtilization data across all of your m1.small instance types fora span of 10 minutes would return the measures for all instances, rolled up into a single metric. Thismetric would be an aggregation of the one-minute chunks of data over the time span you requested,filtered by the other attributes you specified in your query.



In the following example, a developer is monitoring the health of his application, and requests severalmetrics to determine the future needs of his business. He requests the Minimum, Maximum, andAverage statistics of the CPUUtilization metric.

Using this information, the developer can adjust his services directly according to the needs of hisbusiness.

Using the RequestCount metrics represented by the green boxes in the following illustration, thedeveloper can verify the number of requests sent to his application. Using the Maximum statistic ofthe CPUUtilization metrics, represented by the purple boxes surrounded in red, the developer cancheck how stressed his application is during high volume periods. Using the Average statistic of theCPUUtilization metrics, represented by the orange metric boxes, the developer can find out how longperiods of high system stress last.

Amazon CloudWatch provides the data you need to make informed decisions. You specify the metricyou want and you receive statistics for that metric. This allows you to build complex queries in order toaccess different views of the data, for periods of one-minute up to two weeks in length.

For more information about Amazon CloudWatch, please see the Using Amazon CloudWatch (p.14) and the API Reference (p. 47).



Using Amazon CloudWatch

Topics

• Getting Started with Amazon CloudWatch (p. 16)

• Using the Query API (p. 19)

• Using the SOAP API (p. 22)

• Metrics (p. 26)

• Statistics (p. 28)

• About Dimensions (p. 29)

• Amazon CloudWatch Dimensions (p. 31)

• User Scenarios (p. 32)

This section provides task-oriented descriptions of how to use and implement Amazon CloudWatchoperations. For a complete description of Amazon CloudWatch operations, refer to the APIReference (p. 47).

Amazon CloudWatch Developer GuideGetting Started with Amazon CloudWatch


Getting Started with Amazon CloudWatchGetting started with using Amazon CloudWatch is easy. If you are signed up for the Amazon EC2service, you are automatically registered for Amazon CloudWatch. You can activate AmazonCloudWatch using the command line tools or the AWS Management Console.

Activating Amazon CloudWatch Using the AWSManagement ConsoleTo activate Amazon CloudWatch using the console, follow the steps below.

1. Sign in to the AWS Management Console.

2. On the Amazon EC2 tab, click the Launch Instances button.

3. Select an AMI from the list to display the Launch Instance Wizard dialog and configure your EC2instance.

4. On the last step of the Launch Instance Wizard, click the Enable CloudWatch monitoring forthis instance checkbox.

5. Click the Launch button.

6. Click the View your instances on the Instances page link to display a list of your instances. In afew minutes, the status of the instance you just launched will change to Running.

7. Select the running instance and click on the Monitoring tab at the bottom of the list to accessgraphs for CPU, disk, and network metrics.

Activating Amazon CloudWatch Using theCommand Line ToolsFollow the steps below to activate Amazon CloudWatch using the command line tools

1. Download the Command Line Tools from Amazon EC2 API tools Amazon EC2 API tools.

2. Use the ec2-monitor-instances command to enable monitoring for any running Amazon EC2instance. If you want to launch Amazon EC2 instances with monitoring enabled, you can do so bypassing a monitoring parameter to the ec2-run-instances command.

Note

Instances spun up by Auto Scaling are automatically monitored by Amazon CloudWatch.

3. Use the mon-get-stats to view metrics for an Amazon EC2 instance or Elastic Load Balancer.

Command Line Tools ExampleThis section shows some examples of command line tools usage.

• Use the EC2 ec2-run-instances command as in the following example.

PROMPT>ec2-run-instances ami-60a54009 -n 3 --availability-zone us-east-1a

Note

If you wanted to automatically monitor all of the EC Instances spun up by the abovecommand, you would add --monitoring. This allows you to skip Step 2 in this procedure.

http://aws.amazon.com/console/


Amazon CloudWatch Developer GuideCommand Line Tools Example


The command will return a unique identifier for each launched instance. You use the instance ID tomanipulate the instance. This includes viewing the status of the instance, terminating the instance,and so on. Launching the instance will take a few minutes.

RESERVATION r-237fed4a 853279305796 defaultINSTANCE i-d9add0b0 ami-60a54009 pending 0 m1.small 2009-05-14T12:38:24+0000 us-east-1a aki-a71cf9ce ari-a51cf9cc monitoring-disabled

• Use the mon-list-metrics command to get a list of what metrics are being stored for your AWSaccount. For example:

PROMPT>mon-list-metrics

The mon-list-metrics outputs a table containing the Measure name, Namespace, and Dimensionassociated with each metric. For example:

CPUUtilization AWS/EC2 {InstanceId=i-c385b3aa} CPUUtilization AWS/EC2 {ImageId=ami-11ca2d78} CPUUtilization AWS/EC2 {InstanceType=m1.small} CPUUtilization AWS/EC2 DiskReadBytes AWS/EC2 {ImageId=ami-11ca2d78} DiskReadBytes AWS/EC2 {InstanceType=m1.small} DiskReadBytes AWS/EC2 DiskReadBytes AWS/EC2 {InstanceId=i-c385b3aa} DiskReadOps AWS/EC2 {InstanceId=i-c385b3aa} DiskReadOps AWS/EC2 {InstanceType=m1.small} DiskReadOps AWS/EC2 DiskReadOps AWS/EC2 {ImageId=ami-11ca2d78} DiskWriteBytes AWS/EC2 {InstanceId=i-c385b3aa} DiskWriteBytes AWS/EC2 {InstanceType=m1.small} DiskWriteBytes AWS/EC2 {ImageId=ami-11ca2d78} DiskWriteBytes AWS/EC2 DiskWriteOps AWS/EC2 {InstanceId=i-c385b3aa} DiskWriteOps AWS/EC2 {ImageId=ami-11ca2d78} DiskWriteOps AWS/EC2 {InstanceType=m1.small} DiskWriteOps AWS/EC2 NetworkIn AWS/EC2 NetworkIn AWS/EC2 {InstanceId=i-c385b3aa} NetworkIn AWS/EC2 {ImageId=ami-11ca2d78} NetworkIn AWS/EC2 {InstanceType=m1.small} NetworkOut AWS/EC2 {InstanceType=m1.small} NetworkOut AWS/EC2 NetworkOut AWS/EC2 {ImageId=ami-11ca2d78} NetworkOut AWS/EC2 {InstanceId=i-c385b3aa}

• Use the EC2 ec2-monitor-instances command as in the following example.

PROMPT> ec2-monitor-instances i-43a4412a

ec2-monitor-instances returns a table that contains the selected instance IDs and the currentMonitoring state.

i-43a4412a monitoring-pending

• Use the Amazon CloudWatch mon-get-stats command as in the following example.

Amazon CloudWatch Developer GuideCommand Line Tools Example


PROMPT> mon-get-stats CPUUtilization --start-time 2009-05-15T00:00:00 --end-time 2009-05-16T00:00:00 --period 60 --statistics "Average" --namespace "AWS/EC2" --dimensions "ImageId=ami-60a54009"

Amazon CloudWatch returns a response similar to the following (the data has been truncated forbrevity):

2009-05-15 22:42:00 6.0 0.38 Percent2009-05-15 22:48:00 6.0 0.39 Percent2009-05-15 22:54:00 6.0 0.38 Percent

Note

Amazon CloudWatch returns the data for this function in the following order: date, time,sample, CPUUtilization, and unit.

Amazon CloudWatch Developer GuideUsing the Query API


Using the Query APIQuery requests are HTTP or HTTPS requests that use the HTTP verb GET or POST and a Queryparameter named Action or Operation. Action is used throughout this documentation, althoughOperation is supported for backward compatibility with other AWS Query APIs.

Query ParametersEach Query request must include some common parameters to handle authentication and selection ofan action. For more information, see Common Request Parameters (p. 49).

Note

Some API operations take lists of parameters. These lists are specified using the followingnotation: param.member.n. Values of n are integers starting from 1. All lists of parametersmust follow this notation, including lists that only contain one parameter. For example, a Queryparameter list looks like this:

&attribute.member.1=this&attribute.member.2=that

The RequestIdIn every response from Amazon Web Services (AWS), you will find ResponseMetadata, whichcontains a string element called RequestId. This is simply a unique identifier AWS assigns to providetracking information. To improve readability of the API documentation and reduce redundancy,whereas RequestId is included as part of every response, it will not be listed on the individual APIdocumentation pages.

Query API AuthenticationYou can send Query requests over either HTTP or HTTPS. Regardless of which protocol you use, youmust include a signature in every Query request. This section describes how to create the signature.The method described in the following procedure is known as signature version 2.

To create the signature

1. Create the canonicalized query string that you need later in this procedure:

a. Sort the UTF-8 query string components by parameter name with natural byte ordering.The parameters can come from the GET URI or from the POST body (when Content-Typeis application/x-www-form-urlencoded).

b. URL encode the parameter name and values according to the following rules:

• Do not URL encode any of the unreserved characters that RFC 3986 defines.These unreserved characters are A-Z, a-z, 0-9, hyphen ( - ), underscore ( _ ), period ( . ),and tilde ( ~ ).

• Percent encode all other characters with %XY, where X and Y are hex characters 0-9 anduppercase A-F.

• Percent encode extended UTF-8 characters in the form %XY%ZA....

• Percent encode the space character as %20 (and not +, as common encoding schemesdo).

Amazon CloudWatch Developer GuideQuery API Authentication


Note

Currently all AWS service parameter names use unreserved characters, so you don'tneed to encode them. However, you might want to include code to handle parameternames that use reserved characters, for possible future use.

c. Separate the encoded parameter names from their encoded values with the equals sign ( = )(ASCII character 61), even if the parameter value is empty.

d. Separate the name-value pairs with an ampersand ( & ) (ASCII code 38).

2. Create the string to sign according to the following pseudo-grammar (the "\n" represents anASCII newline).

StringToSign = HTTPVerb + "\n" +ValueOfHostHeaderInLowercase + "\n" +HTTPRequestURI + "\n" + CanonicalizedQueryString <from the preceding step>

The HTTPRequestURI component is the HTTP absolute path component of the URI up to, but notincluding, the query string. If the HTTPRequestURI is empty, use a forward slash ( / ).

3. Calculate an RFC 2104-compliant HMAC with the string you just created, your Secret AccessKey (p. 70) as the key, and SHA256 or SHA1 as the hash algorithm.

For more information, go to http://www.ietf.org/rfc/rfc2104.txt.

4. Convert the resulting value to base64.

5. Use the resulting value as the value of the Signature request parameter.

Important

The final signature you send in the request must be URL encoded as specified in RFC 3986(for more information, go to http://www.ietf.org/rfc/rfc3986.txt). If your toolkit URL encodesyour final request, then it handles the required URL encoding of the signature. If your toolkitdoesn't URL encode the final request, then make sure to URL encode the signature before youinclude it in the request. Most importantly, make sure the signature is URL encoded only once.A common mistake is to URL encode it manually during signature formation, and then againwhen the toolkit URL encodes the entire request.

http://www.ietf.org/rfc/rfc2104.txt

http://www.ietf.org/rfc/rfc3986.txt

Amazon CloudWatch Developer GuideQuery Example


Query ExampleExample ListMetrics API Request

This example uses the Amazon CloudWatch API ListMetrics (p. 60)

http://monitoring.amazonaws.com/?SignatureVersion=2&Action=ListMetrics&Version=2009-05-15&AWSAccessKeyId=XXX YOUR ACCESS KEY XXX&SignatureVersion=2&SignatureMethod=HmacSHA1&Timestamp=2009-02-17T05%3A13%3A00.000Z&Signature=%XXX YOUR SIGNATURE XXX%3D

Following is the string to sign.

http://monitoring.amazonaws.com/?SignatureVersion=2AWSAccessKeyId=<Your AWS Access Key Id>&Action=ListMetrics&SignatureMethod=HmacSHA256&SignatureVersion=2&Version=2009-05-15

Following is the signed request.

http://monitoring.amazonaws.com/?Action=ListMetrics&AWSAccessKeyId=XXX YOUR ACCESS KEY XXX&SignatureVersion=2&SignatureMethod=HmacSHA1&Timestamp=2009-10-17T05%3A13%3A00.000Z&Signature=<URLEncode(Base64Encode(Signature))>&Version=2009-05-15

Amazon CloudWatch Developer GuideUsing the SOAP API


Using the SOAP APITopics

• WSDL and Schema Definitions (p. 22)

• Programming Language Support (p. 22)

• Request Authentication (p. 22)

• The Response Structure (p. 24)

• Web Services References (p. 25)

WSDL and Schema DefinitionsYou can access Amazon CloudWatch using the SOAP web services messaging protocol. Thisinterface is described by a Web Services Description Language (WSDL) document, which definesthe operations and security model for the particular service. The WSDL references an XML Schemadocument, which strictly defines the data types that might appear in SOAP requests and responses.For more information on WSDL and SOAP, see Web Services References (p. 25).

Note

Amazon CloudWatch supports SOAP only through HTTPS.

All schemas have a version number. The version number appears in the URL of a schema file and ina schema's target namespace. This makes upgrading easy by differentiating requests based on theversion number.

Programming Language SupportSince the SOAP requests and responses in Amazon CloudWatch follow current standards, nearly anyprogramming language can be used.

Note

AWS provides libraries, sample code, tutorials, and other resources for software developerswho prefer to build applications using language-specific APIs instead of Amazon CloudWatch'sSOAP and Query APIs. These libraries provide basic functions (not included in AmazonCloudWatch's SOAP and Query APIs), such as request authentication, request retries, anderror handling so that it's easier to get started. Libraries and resources are available for thefollowing languages:

• Java

• PHP

• Ruby

• Windows and .NET

For libraries and sample code in all languages, go to Sample Code & Libraries.

Request AuthenticationAmazon CloudWatch requires you to hash and sign SOAP requests with the current WS-Securitystandard, requiring SOAP request messages to be hashed and signed for integrity and non-

http://aws.amazon.com/java

http://aws.amazon.com/php

http://aws.amazon.com/ruby

http://aws.amazon.com/net

http://aws.amazon.com/code

Amazon CloudWatch Developer GuideRequest Authentication


repudiation. WS-Security defines profiles which are used to implement various levels of security.Amazon CloudWatch secure SOAP messages use the BinarySecurityToken profile, consisting of anX.509 certificate with an RSA public key.

The following is the content of an insecure GetMetricStatistics operation:

<GetMetricStatistics xmlns="http://monitoring.amazonaws.com/doc/2009-05-15/"> <Statistics> <member>Average</member> </Statistics> <Period>60</Period> <MeasureName>CPUUtilization</MeasureName> <Dimensions> <member> <Name>InstanceType</Name> <Value>m1.small</Value> </member> <member> <Name>ImageID</Name> <Value>ami-11ca2d78</Value> </member> </Dimensions> <StartTime>2009-05-14T19:12:59Z</StartTime> <EndTime>2009-05-14T19:15:01Z<EndTime></GetMetricStatistics>

To secure the request, we add the BinarySecurityToken element.

The secure version of the request begins with the following:

<?xml version="1.0" encoding="UTF-8"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap:Header>...</soap:Header> <soap:Body wsu:Id="id-19451103" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <GetMetricStatistics xmlns="http://monitoring.amazonaws.com/doc/2009-05-15/"> <Statistics> <member>Average</member> </Statistics> <Period>60</Period> <measure name>CPUUtilization</measure name> <Dimensions> <member> <Name>InstanceType</Name> <Value>m1.small</Value> </member> <member> <Name>ImageID</Name> <Value>ami-11ca2d78</Value> </member> </Dimensions> <StartTime>2009-05-14T19:12:59Z</StartTime> <EndTime>2009-05-14T19:15:01Z<EndTime>

Amazon CloudWatch Developer GuideThe Response Structure


</GetMetricStatistics></soap:Body></soap:Envelope>

If you are matching this against requests generated by Amazon CloudWatch supplied libraries, orthose of another vendor, the following are the most important elements:

Elements

• BinarySecurityToken—Contains the X.509 certificate in base64 encoded PEM format

• Signature—Contains an XML digital signature created using the canonicalization, signaturealgorithm, and digest method

• Timestamp—Requests to Amazon CloudWatch are valid within 5 minutes of this value to helpprevent replay attacks

The Response StructureIn response to a request, Amazon CloudWatch returns an XML data structure that conforms to anXML schema defined as part of the Amazon CloudWatch WSDL. The structure of a XML responseis specific to the associated request. In general, the response data types are named according tothe operation performed and whether the data type is a container (can have children). Examples ofcontainers include groupSet for security groups and instancesSet for instances. Item elements arechildren of containers and their contents vary according to the container's role.

<?xml version="1.0" encoding="UTF-8"?><Envelope encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns="http://schemas.xmlsoap.org/soap/envelope/"> <Header>...</Header> <Body> <GetMetricStatisticsResponse xmlns="http://monitoring.amazonaws.com/doc/2009-05-15/"> <GetMetricStatisticsResult> <Label xmlns="http://monitoring.amazonaws.com/doc/2009-05-15/">CPUUtilization</Label> <Datapoints> <member> <Timestamp>2009-05-14T19:13:00Z</Timestamp> <Unit>Percent</Unit> <Samples>1.0</Samples> <Average>0.0</Average> </member> <member> <Timestamp>2009-05-14T19:12:00Z</Timestamp> <Unit>Percent</Unit> <Samples>1.0</Samples> <Average>0.0</Average> </member> </Datapoints> </GetMetricStatisticsResult> <ResponseMetadata> <RequestId>892070df</RequestId> </ResponseMetadata> </GetMetricStatisticsResponse> </Body>

Amazon CloudWatch Developer GuideWeb Services References


</Envelope>

Web Services ReferencesFor more information about using web services, go to any of the following resources:

• Web Service Description Language (WSDL)

• WS-Security BinarySecurityToken Profile

http://www.w3.org/TR/wsdl

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0.pdf

Amazon CloudWatch Developer GuideMetrics


MetricsTopics

• EC2 Metrics (p. 26)

• Elastic Load Balancing Metrics (p. 27)

Amazon CloudWatch collects measures for Amazon EC2 instances and Elastic Load Balancing.

EC2 MetricsThe following metrics are available from each EC2 instance.

Metric Description

CPUUtilization The percentage of allocated EC2 compute units that are currently in use onthe instance. This metric identifies the processing power required to run anapplication upon a selected instance.

Units: Percent

NetworkIn The number of bytes received on all network interfaces by the instance.This metric identifies the volume of incoming network traffic to anapplication on a single instance.

Units: Bytes

NetworkOut The number of bytes sent out on all network interfaces by the instance.This metric identifies the volume of outgoing network traffic to anapplication on a single instance.

Units: Bytes

DiskWriteOps Completed write operations to all hard disks available to the instance. Thismetric identifies the rate at which an application writes to a hard disk. Thiscan be used to determine the speed in which an application saves data toa hard disk.

Units: Count

DiskReadBytes Bytes read from all disks available to the instance. This metric is used todetermine the volume of the data the application reads from the hard diskof the instance. This can be used to determine the speed of the applicationfor the customer.

Units: Bytes

DiskReadOps Completed read operations from all disks available to the instances. Thismetric identifies the rate at which an application reads a disk. This can beused to determine the speed in which an application reads data from ahard disk.

Units: Count

Amazon CloudWatch Developer GuideElastic Load Balancing Metrics


Metric Description

DiskWriteBytes Bytes written to all disks available to the instance. This metric is used todetermine the volume of the data the application writes onto the hard diskof the instance. This can be used to determine the speed of the applicationfor the customer.

Units: Bytes

Amazon CloudWatch data for a new EC2 instance typically becomes available within one minute ofthe end of the first period of time requested (the aggregation period) in the query. You can use thecurrently available dimensions for EC2 instances (for example, ImageID or InstanceType) in order torefine the metrics returned.

For information about the dimensions you can use with EC2, see Amazon CloudWatch Dimensions (p.31).

Elastic Load Balancing MetricsThe following metrics are available from the Elastic Load Balancing.

Metric Section

Latency Time taken between a request and the corresponding response as seen bythe load balancer.

Units: Seconds

Valid Statistics: Minimum, Maximum, Average and Count

RequestCount The number of requests processed by the LoadBalancer.

Units: Count/Second

Valid Statistics: Minimum, Maximum and Sum

HealthyHostCount The number of healthy instances. Both Load Balancing dimensions,LoadBalancerName and AvailabilityZone, should be specified whenretrieving HealthyHostCount.

Units: Count

Valid Statistics: the Average for a LoadBalancer within an Availability Zone

UnHealthyHostCount The number of unhealthy i. Both Load Balancing dimensions,LoadBalancerName and AvailabilityZone, should be specified whenretrieving UnHealthyHostCount.

Units: Count

Valid Statistics: the Average for a LoadBalancer within an Availability Zone

You can use the currently available dimensions for Elastic Load Balancing to refine themetrics returned by a query. For example, you could use HealthyHostCount and dimensionsLoadBalancerName and AvailabilityZone to get the Average number of healthy Instances behindthe specified LoadBalancer within the specified Availability Zone for a given period of time. For thedimensions you can use with the Load Balancing Service, see Amazon CloudWatch Dimensions (p.31)

Amazon CloudWatch Developer GuideStatistics


StatisticsAmazon CloudWatch not only aggregates the raw data coming in, it also computes several statistics onthe data. The following table lists the statistics that you can request:

Statistic Description

Minimum The lowest value observed during the specified period. This can be used todetermine low volumes of activity for your application.

Maximum The highest value observed during the specified period. You can use thisto determine high volumes of activity for your application.

Sum The sum of all values received. This statistic can be useful for determiningthe total volume of a metric.

Average The Average of all values received during the specified period. Bycomparing this statistic with the minimum and maximum statistics, you candetermine the full scope of a metric and how close the average use is tothe minimum and the maximum. This will allow you to increase or decreaseyour resources as needed.

Samples The count (number) of measures used.

Note

This statistic is always returned to show the user the size of thedataset collected and cannot be explicitly requested.

Statistics are computed within the time period specified in the query. The maximum frequency withwhich statistics are gathered by Amazon CloudWatch is 1 minute.

CloudWatch data is generally available from the service within one minute from the end of the timeperiod requested in the query (the aggregation period). In some cases, delays in data propagationmight cause a delay in data becoming available to CloudWatch. In these instances, you should checkthe service’s Health Dashboard for any current operational issues with either Amazon CloudWatch orthe service collecting the data.

Amazon CloudWatch Developer GuideAbout Dimensions


About DimensionsAmazon CloudWatch organizes data into dimensions. Dimensions are name-value pairs that areprovided by the services feeding data to Amazon CloudWatch. Dimensions can be used to filter resultsets returned by Amazon CloudWatch queries.

If when you don't specify dimensions when using the GetMetricStatistics (p. 55) API to requestmetric data from Amazon CloudWatch, all data for the specified measure name will be aggregated andused to create the statistic (or statistics) that you requested.

The dimensions you can use are to filter your query results depend on which measure is requestedin the query. For example, using the EC2 metric NetworkOut, the available EC2 dimensions areInstanceType, InstanceId, and ImageId.

Note

Currently, only single dimension aggregation is supported in Amazon CloudWatch, with oneexception: you can get metrics for LoadBalancers within an AvailabilityZone by specifying thedimensions LoadBalancerName and AvailabilityZone in a single call.

The following example uses two "NetworkOut measures" coming from EC2 instances.

When the first measure comes in, it has the following name, unit, namespace, dimensions, and rawdata value:

• MeasureName—NetworkOut

• Unit—Bytes

• Namespace—AWS/EC2

• Value—0

• Dimension associated—InstanceType, m1.small

• Dimension associated—InstanceId, i-fba30092

• Dimension associated—ImageId, ami-2547a3c

Note

For simplicity, the second measure comes in during a different minute, so that we don't need toworry about the two measures getting aggregated into the same one-minute chunk.

The second measure has the following name, unit, namespace, dimensions, raw data value:

• MeasureName—NetworkOut

• Unit—Bytes

• Namespace—AWS/EC2

• Value—20

• Dimension associated—InstanceType, m1.small

• Dimension associated—Instance, i-fba30299

• Dimension associated—ImageId, ami-2547a3c

The two measures come in with timestamps as well. They are not listed here, but as noted, to makethe example easier, the two measures come in during different, adjacent minutes. So we now have twometrics with these attributes and they span two minutes.

Amazon CloudWatch Developer GuideAbout Dimensions


You'll notice that both metrics are of the InstanceType m1.small, and both have the same ImageIdami-2547a3c, but that they come from different EC2 instances. So if you were to ask a questionspecifying either ImageId or InstanceType as the dimension to use when filtering the metric data,both measures would be combined in the resulting statistic values. However, if you were to specifyyour dimension as Instance=i-fba30299, then you would get statistics calculated only from the secondmeasure.

Let’s get a bit more complex now and ask some more detailed questions, by using a (slightly) longertime interval.

Because you can currently aggregate along only a single dimension, you can ask questions like thefollowing (using the previous information):

• What is the Average number of NetworkOut bytes for all of my m1.small instances over a two minutetime interval?

In the above question, the statistic asked for is Average. The time interval (StartTime to EndTime)is 2 minutes. The measure name is NetworkOut. The dimension used is InstanceType (with the valuem1.small). The answer is the sum of 0 and 20, divided by 2, which equals 10.

• What is the maximum NetworkOut bytes for ami-2547a34c over the last two minutes?

In this question, the statistic asked for is Maximum. The time interval (StartTime to EndTime) is 2minutes. The measure name is NetworkOut. The dimension is ImageId (with the value ami-2547a3c).The maximum is the larger of 0 and 20, which is of course 20.

The user scenarios included in this guide provide more detailed examples that you can use to help youdesign your own queries. For more information, see User Scenarios (p. 32)

Amazon CloudWatch Developer GuideAmazon CloudWatch Dimensions


Amazon CloudWatch DimensionsTopics

• Dimensions for EC2 Metrics (p. 31)

• Dimensions for Load Balancing Metrics (p. 31)

Dimensions for EC2 MetricsEC2 instance data can be filtered along any of the following dimensions in the table below.

Dimension Section

ImageId This dimension filters the data you request for all instances running thisEC2 Amazon Machine Image (AMI).

AutoScalingGroupName This dimension filters the data you request for all instances in a specifiedcapacity group. An AutoScalingGroup is a collection of instances definedby customers of the Auto Scaling service. This dimension is only availablefor EC2 metrics when the instances are in such an AutoScalingGroup.

InstanceId This dimension filters the data you request for only the identified instance.This allows a user to pinpoint an exact instance from which to monitor data.

InstanceType This dimension filters the data you request for all instances running withthis specified instance type. This allows a user to categorize his data by thetype of instance running. For example, a user might compare data from anm1.small instance and an m1.large instance to determine which has thebetter business value for his application.

Dimensions for Load Balancing MetricsLoad Balancing Service data can be aggregated along any of the following dimensions shown in thetable below.

Load BalancingMetrics

Section

LoadBalancerName This dimension filters the data you request for the specified LoadBalancername. A LoadBalancer is represented by a DNS name and provides thesingle destination to which all requests intended for your application shouldbe directed. This metric allows you to examine data from all instancesconnected to a single LoadBalancer.

AvailabilityZone This dimension filters the data you request for all instances running in thatEC2 Availability Zone.

Amazon CloudWatch Developer GuideUser Scenarios


User ScenariosTopics

• Get Average CPUUtilization for EC2 Instances With a Particular ImageId (p. 33)

• Get Maximum CPUUtilization per EC2 Instance (p. 35)

• Compare RequestCount by Availability Zone for a Load Balanced EC2 Application (p. 37)

• Get Latency Statistics for a LoadBalancer (p. 39)

• Get Total DiskWriteBytes for a Capacity-Managed EC2 Application (p. 41)

• Get A Single Metric Across All Dimensions (p. 43)

• Get Available Metrics Across Multiple Instances (p. 45)

The following sections discuss some common user scenarios for using Amazon CloudWatch. Thesescenarios show the API or command line sequence you use to accomplish the given tasks.

Note

The examples in the following sections assume that your instances are in the US StandardRegion. If your instances are in Europe, you must specify the eu-west1 Region by using the --region eu-west-1 parameter or setting the EC2_REGION environment variable.

Amazon CloudWatch Developer GuideGet Average CPUUtilization for EC2Instances With a Particular ImageId


Get Average CPUUtilization for EC2 InstancesWith a Particular ImageIdIn this example, we use the GetMetricStatistics API or the mon-get-stats command todetermine Average CPUUtilization for all instances that match a given ImageId. The Average is over60-second time intervals for a one-day period.

Note

Start and end times must be within the last 14 days.

We assume that the EC2 instances are running an ImageId of ami-2547a34c.

API Example

To get the average CPUUtilization for an ImageId

• Call GetMetricStatistics (p. 55) with the following parameters:

• MeasureName = CPUUtilization

• Period = 60

• Statistics list includes Average

• Dimensions (Name= ImageId, Value= ami-2547a34c)

• Namespace = AWS/EC2

• StartTime = 2009-05-15T00:00:00

• EndTime = 2009-05-16T00:00:00

Command Line Tools Example

To get the average CPUUtilization for an ImageId

• Use the mon-get-stats command as in the following example.

PROMPT> mon-get-stats CPUUtilization --start-time 2009-05-15T00:00:00 --end-time 2009-05-16T00:00:00 --period 60 --statistics "Average" --namespace "AWS/EC2" --dimensions "ImageId=ami-2547a34c"

Amazon CloudWatch returns a response similar to the following (the data has been truncated forbrevity):

2009-05-15 22:42:00 6.0 0.38 Percent2009-05-15 22:48:00 6.0 0.39 Percent2009-05-15 22:54:00 6.0 0.38 Percent2009-05-15 23:00:00 6.0 0.38 Percent2009-05-15 23:06:00 6.0 0.38 Percent2009-05-15 23:12:00 6.0 0.38 Percent

Note

Amazon CloudWatch returns the data for this function in the following order: date, time,sample, average CPUUtilization, and unit.

Amazon CloudWatch Developer GuideGet Average CPUUtilization for EC2Instances With a Particular ImageId


The operation returns datapoints that are one-minute values for the one-day interval. Each valuerepresents an average CPUUtilization percentage for EC2 instances running the specified machineimage.

Give Us Your FeedbackYour input is important to us to help make our documentation helpful and easy to use. Please take aminute to give us your feedback on how well we were able to help you use Amazon CloudWatch. Justclick this feedback link. Thank you.

http://survey.amazonwebservices.com/survey/s?s=1182&opdata_page=CW_DG_2009-05-15_US_MetricAveCPU01

Amazon CloudWatch Developer GuideGet Maximum CPUUtilization per EC2 Instance


Get Maximum CPUUtilization per EC2 InstanceIn this example, we use the GetMetricStatistics API or the mon-get-stats to determine themaximum CPUUtilization.

Note


We assume that you are running multiple EC2 instances for this example.

API Example

To get the maximum CPUUtilization per hour for each EC2 instance for a 3-day period

1. Use the EC2 ec2-describe-instances command to determine the InstanceIds of each of yourrunning instances, ( e.g. i-5431413d, i-d43242bd, etc.).

2. For each instance, call GetMetricStatistics (p. 55) with the following parameters:


• Period = 3600

• Statistics list includes Maximum

• Dimension (Name=InstanceId, Value="i-5431413d" or other running EC2 instance fromstep 1)


• StartTime = 2009-05-11T23:18:00

• EndTime = 2009-05-14T23:18:00


To get the maximum CPUUtilization per EC2 instance

• Use the mon-get-stats command with the following parameters.

mon-get-stats CPUUtilization --end-time 2009-05-13T23:18:00 --start-time 2009-05-11T23:18:00 --period 360 --namespace "AWS/EC2" --statistics "Maximum" --dimensions "InstanceId=i-5431413d"

Amazon CloudWatch returns the following:

2009-05-11 23:18:00 6.0 0.38 Percent2009-05-11 23:24:00 6.0 0.38 Percent2009-05-11 23:30:00 6.0 0.38 Percent2009-05-11 23:36:00 6.0 0.38 Percent2009-05-11 23:42:00 6.0 0.38 Percent2009-05-11 23:48:00 6.0 0.39 Percent 2009-05-11 23:54:00 6.0 0.38 Percent2009-05-12 00:00:00 6.0 0.38 Percent2009-05-12 00:06:00 6.0 0.38 Percent2009-05-12 00:12:00 6.0 0.38 Percent

Amazon CloudWatch Developer GuideGet Maximum CPUUtilization per EC2 Instance


Note

Amazon CloudWatch returns the data for this function in the following order: date, time,sample, Maximum CPUUtilization, and unit.

The returned Datapoints (p. 64) are six-minute values for the requested two-day time interval. Eachvalue represents a maximum CPUUtilization percentage for a single EC2 instance.


http://survey.amazonwebservices.com/survey/s?s=1182&opdata_page=CW_DG_2009-05-15_US_MetricAveCPU01

Amazon CloudWatch Developer GuideCompare RequestCount by Availability

Zone for a Load Balanced EC2 Application


Compare RequestCount by Availability Zone fora Load Balanced EC2 ApplicationIn this example, we compare RequestCounts by using the GetMetricStatistics API or the mon-get-stats to retrieve the RequestCount for a LoadBalancer in two different Availability Zones. Statisticsin this example are calculated for six-minute time periods over a 48-hour interval. They are aggregatesover all instances in the specified Availability Zone for one LoadBalancer.

Note


For this example, we assume the EC2 application is running behind a LoadBalancerLB1242248298357-7) in two Availability Zones (us-east-1a, us-east-1b).

API Example

To get the RequestCount by Availability Zone for a load balanced EC2 application

1. Call GetMetricStatistics (p. 55) with the following parameters:

• MeasureName = RequestCount

• Period = 360

• Statistics list includes Sum

• Dimensions include:

• Dimension (Name=AvailabilityZone, Value=us-east-1a)

• Dimension (Name=LoadBalancer, Value=LB1242248298357-7)

• Namespace AWS/ELB

• StartTime = 2009-05-12T23:18:00

• EndTime = 2009-05-14T23:18:00


• MeasureName = RequestCount

• Period = 360


• Dimensions include

• Dimension (Name=AvailabilityZone, Value=us-east-1b)


• Namespace =AWS/ELB

• StartTime = 2009-05-12T23:18:00

• EndTime = 2009-05-14T23:18:00


To get the RequestCount by Availability Zone for load balanced EC2 application

1. Use the mon-get-stats command with the following parameters.

PROMPT> mon-get-stats RequestCount --end-time 2009-05-14T23:18:00 --start-time 2009-05-12T23:18:00 --period 360 --namespace "AWS/ELB" --statistics "Sum" --dimensions "LoadBalancerName=LB1242248298357-7, AvailabilityZone=us-east-1a"

Amazon CloudWatch Developer GuideCompare RequestCount by Availability

Zone for a Load Balanced EC2 Application



2009-05-13 21:30:00 127.0 127.0 Count2009-05-13 21:36:00 19.0 19.0 Count

Note

Amazon CloudWatch returns the data for this function in the following order: date, time,sample, sum, and unit.


PROMPT> mon-get-stats RequestCount --end-time 2009-05-14T23:18:00 --start-time 2009-05-12T23:18:00 --period 360 --namespace "AWS/ELB" --statistics "Sum" --dimensions "LoadBalancerName=LB1242248298357-7, AvailabilityZone=us-east-1b"


2009-05-13 21:30:00 117.0 117.0 Count2009-05-13 21:36:00 17.0 17.0 Count

Note


The returned Datapoints (p. 64) lists are six-minute time series values for a 48-hour interval. EachDatapoint (p. 63) represents a total RequestCount summed for all EC2 instances behind theLoadBalancer within a single Availability Zone.


http://survey.amazonwebservices.com/survey/s?s=1182&opdata_page=CW_DG_2009-05-15_US_MetricAveThru03

Amazon CloudWatch Developer GuideGet Latency Statistics for a LoadBalancer


Get Latency Statistics for a LoadBalancerIn this example, we use the GetMetricStatistics API or the mon-get-stats to retrieve average,minimum, and maximum latency metric data for a LoadBalancer. These statistics are calculated forone-minute periods over a one-day interval.

Note


For this example, we assume that an EC2 application is running and is load balanced with theLoadBalancer LB1242248298357-0.

API Example

To get latency statistics for a LoadBalancer


• MeasureName = Latency

• Period = 60

• Statistics list includes Average, Maximum, Minimum


• Namespace = AWS/ELB

• StartTime = 2009-05-12T23:18:00

• EndTime = 2009-05-13T23:18:00

The returned Datapoints (p. 64) are a list of one-minute values for the one-day interval. EachDatapoint (p. 63) contains Average, Minimum, and Maximum latency values for requests goingthrough the application's LoadBalancer.


To get latency statistics for a LoadBalancer


PROMPT> mon-get-stats Latency --end-time 2009-05-13T23:18:00 --start-time 2009-05-12T23:18:00 --period 60 --namespace "AWS/ELB" --statistics "Average, Maximum, Minimum" --dimensions "LoadBalancerName=LB1242248298357-0"


2009-05-13 21:12:00 46.0 2.0888 2.008324 2.22837 Seconds 2009-05-13 21:13:00 53.0 2.1441 2.00405 4.431464 Seconds 2009-05-13 21:14:00 56.0 2.0949 2.005274 2.330432 Seconds 2009-05-13 21:15:00 4.0 2.0518 2.004768 2.089594 Seconds

Note

Amazon CloudWatch returns the data for this function in the following order: date, time,average latency, minimum latency, maximum latency, and unit.

Amazon CloudWatch Developer GuideGet Latency Statistics for a LoadBalancer



http://survey.amazonwebservices.com/survey/s?s=1182&opdata_page=CW_DG_2009-05-15_US_MetricLatency04

Amazon CloudWatch Developer GuideGet Total DiskWriteBytes for a

Capacity-Managed EC2 Application


Get Total DiskWriteBytes for a Capacity-Managed EC2 ApplicationIn this example, we use the GetMetricStatistics API or the mon-get-stats with theDiskWriteBytes measure to retrieve the total bytes written to disk for one capacity group. The totalis computed for one-minute periods for a 24-hour interval across all EC2 instances in the specifiedAutoScalingGroupName.

Note


We assume for this example that an EC2 application is running and has a capacity group namedAG1242248298357-22-us-east-1a.

API ExampleTo get total DiskWriteBytes for a Capacity-managed EC2 Application

Call GetMetricStatistics (p. 55) with the following parameters:

• MeasureName = DiskWriteBytes

• Period = 60


• Unit = Bytes

• Dimension (Name=AutoScalingGroupName, Value=AG1242248298357-22-us-east-1a)


• StartTime = 2009-05-13T23:18:00

• EndTime = 2009-05-14T23:18:00

The returned Datapoints (p. 64) are one-minute totals for bytes written for the entire capacity groupover the 24-hour interval.

Command Line Tools ExampleTo get total DiskWriteBytes for a Capacity-managed EC2 Application


mon-get-stats DiskWriteBytes --end-time 2009-05-14T23:18:00 --start-time 2009-05-13T23:18:00 --period 60 --namespace AWS/EC2 --statistics Sum --dimensions "AutoScalingGroupName=AG1242248298357-22-us-east-1a"


2009-05-14 15:52:00 1.0 196608.0 Bytes 2009-05-14 15:53:00 1.0 180224.0 Bytes 2009-05-14 15:54:00 1.0 200704.0 Bytes 2009-05-14 15:55:00 1.0 200704.0 Bytes 2009-05-14 15:56:00 1.0 200704.0 Bytes 2009-05-14 15:57:00 1.0 180224.0 Bytes 2009-05-14 15:58:00 1.0 196608.0 Bytes

Amazon CloudWatch Developer GuideGet Total DiskWriteBytes for a

Capacity-Managed EC2 Application


2009-05-14 15:59:00 1.0 372736.0 Bytes 2009-05-14 16:00:00 1.0 258048.0 Bytes

Note



http://survey.amazonwebservices.com/survey/s?s=1182&opdata_page=CW_DG_2009-05-15_US_MetricDiskIO05

Amazon CloudWatch Developer GuideGet A Single Metric Across All Dimensions


Get A Single Metric Across All DimensionsIn this example, we use the GetMetricStatistics API or the mon-get-stats to get the averageCPUUtilization for all EC2 instances for the account.

Note


API Example

To get a single metric across all dimensions





• StartTime = 2009-05-13T23:18:00

• EndTime = 2009-05-15T23:18:00

• Period = 360

The returned Datapoints (p. 64) are six-minute values for the two-day interval. Each valuerepresents an average CPUUtilization percentage for all of your EC2 instances running.


To get a single metric across all dimensions


mon-get-stats CPUUtilization --end-time 2009-05-15T23:18:00 --start-time 2009-05-13T23:18:00 --period 360 --namespace "AWS/EC2" --statistics "Average"


2009-05-14 14:18:00 60.0 0.1138 Percent 2009-05-14 15:18:00 60.0 0.1078 Percent 2009-05-14 16:18:00 60.0 0.3322 Percent 2009-05-14 17:18:00 60.0 0.1397 Percent 2009-05-14 18:18:00 60.0 0.1143 Percent 2009-05-14 19:18:00 60.0 0.1082 Percent 2009-05-14 20:18:00 36.0 0.1367 Percent

Note

Amazon CloudWatch provides the data for this function in the following order: date, time,sample, value, and unit.

Amazon CloudWatch Developer GuideGet A Single Metric Across All Dimensions


Give Us Your FeedbackYour input is important to us to help make our documentation helpful and easy to use. Please take aminute to give us your feedback on how well we were able to help you use CloudWatch Just click thisfeedback link. Thank you.

http://survey.amazonwebservices.com/survey/s?s=1182&opdata_page=CW_DG_2009-05-15_US_SingleMetricMultipleHosts

Amazon CloudWatch Developer GuideGet Available Metrics Across Multiple Instances


Get Available Metrics Across Multiple InstancesIn this example, we use the ListMetrics API to determine what metrics are available, and then callGetMetricStatistics API get the Average CPUUtilization for a single instance.

Note


We assume for this example that your EC2 application is running.

API ExampleUsing ListMetrics to determine available metrics across multiple instances

1. Call API ListMetrics (p. 60) to generate a list of all of your valid metrics.

This returns a list of metrics. An example metric might look like:


• Dimension (Name=InstanceId, Value=i-5431413d)



• Metric = CPUUtilization

• Period = 360


• Dimension (Name=InstanceId, Value=i-5431413d)


• StartTime = 2009-05-11T23:18:00

• EndTime = 2009-05-13T23:18:00

The returned Datapoints (p. 64) are six-minute time series values for the two-day interval. Eachvalue represents one of the metrics being monitored for the selected EC2 instance.

Command Line Tools Example>Using ListMetrics to find determine available metrics across multiple instance

1. Use the mon-list-metrics command.

mon-list-metrics


CPUUtilization AWS/EC2 {InstanceId=i-5431413d} CPUUtilization AWS/EC2 {InstanceId=i-d43242bd} CPUUtilization AWS/EC2 {InstanceId=i-1d3d4d74} CPUUtilization AWS/EC2 {InstanceId=i-78314111} CPUUtilization AWS/EC2 {InstanceId=i-d3c8baba} CPUUtilization AWS/EC2 {InstanceId=i-0d334364} CPUUtilization AWS/EC2 {InstanceId=i-6732420e} CPUUtilization AWS/EC2 {InstanceId=i-d93141b0} CPUUtilization AWS/EC2 {InstanceId=i-e03d4d89}

Amazon CloudWatch Developer GuideGet Available Metrics Across Multiple Instances


CPUUtilization AWS/EC2 {InstanceId=i-c93d4da0} CPUUtilization AWS/EC2 {InstanceId=i-e0304089} CPUUtilization AWS/EC2 {InstanceId=i-e1304088} CPUUtilization AWS/EC2 {InstanceId=i-69334300}

Note

Amazon CloudWatch provides the data for this function in the following order:measurename, namespace, and dimensions.


mon-get-stats CPUUtilization --end-time 2009-05-13T23:18:00 --start-time 2009-05-11T23:18:00 --period 360 --namespace "AWS/EC2" --statistics "Average" --dimensions "InstanceId=i-5431413d"


2009-05-11 23:18:00 6.0 0.38 Percent 2009-05-11 23:24:00 6.0 0.38 Percent 2009-05-11 23:30:00 6.0 0.38 Percent 2009-05-11 23:36:00 6.0 0.38 Percent 2009-05-11 23:42:00 6.0 0.38 Percent 2009-05-11 23:48:00 6.0 0.39 Percent 2009-05-11 23:54:00 6.0 0.38 Percent 2009-05-12 00:00:00 6.0 0.38 Percent 2009-05-12 00:06:00 6.0 0.38 Percent 2009-05-12 00:12:00 6.0 0.38 Percent

Note

Amazon CloudWatch returns the data for this function in the following order: date, time,sample, Average CPUUtilization, and unit.


http://survey.amazonwebservices.com/survey/s?s=1182&opdata_page=CW_DG_2009-05-15_US_MultipleMetricSingleHosts

Amazon CloudWatch Developer GuideWSDL Locations


API Reference

Topics

• WSDL Locations (p. 47)

• API Conventions (p. 47)

• Common Request Parameters (p. 49)

• Error Codes (p. 50)

• Amazon CloudWatch Operations (p. 54)

• Data Types (p. 62)

The following sections of the guide provide reference material for Amazon CloudWatch. For moreinformation about any concepts or programming tasks associated with the reference material, refer tothe previous chapters in this guide.

WSDL LocationsThe WSDL for the Amazon CloudWatch is located online at http://monitoring.amazonaws.com/doc/2009-05-15/CloudWatch.wsdl.

API Conventions

Data Types and Amazon CloudWatch WSDLSome libraries can generate code directly from the WSDL. Other libraries require a little more work onyour part.

Values provided as parameters to the various operations must be of the indicated type. Standard XSDtypes (like string, boolean, int) are prefixed with xsd:. Complex types defined by the AmazonCloudWatch WSDL are prefixed. Please look at the individual WSDL for guidance.

For example, the <imagesSet> element in the following XML snippet is of type xsd:string[].

<imagesSet> <item>

Amazon CloudWatch Developer GuideData Types and Amazon CloudWatch WSDL


<ImageId>ami-61a54008</ImageId> </item> <item> <ImageId>ami-61b54608</ImageId> </item></imagesSet>

Amazon CloudWatch Developer GuideCommon Request Parameters


Common Request ParametersAll Query operations share a set of common parameters that must be present in each call:

Name Description Required

Action Indicates the action to perform.

Example: GetMetricStatistics

Yes

AWSAccessKeyId The Access Key Id for the request sender. This identifiesthe account which will be charged for the usage of theservice.

Example: 10QMXFEV71ZS32XQFTR2

Yes

Expires The date and time at which the signature includedin the request expires in the format YYYY-MM-DDThh:mm:ssZ.

Example: 2009-01-07T15:04:56Z

Conditional: Required if Timestamp is not used

Conditional

Namespace Namespace is the identifier for the service to wish torequest information from.

Example: AWS/EC2

No

Timestamp The date and time at which the request is signed,in the format YYYY-MM-DDThh:mm:ssZ. For moreinformation, go to ISO 8601.

Example: 2009-01-07T15:04:56Z

Conditional: Required if Expired is not used

Conditional

Signature The request signature. For more information, see QueryAPI Authentication (p. 19).

Example: Qnpl4Qk/7tINHzfXCiT7VbBatDA=

Yes

SignatureMethod The hash algorithm you use to create the requestsignature.

Valid values: HmacSHA256 | HmacSHA1. For moreinformation, see Query API Authentication (p. 19).

Example: HmacSHA256

Yes

SignatureVersion The signature version you use to sign the request. Setthis value to 2. For more information, see Query APIAuthentication (p. 19).

Yes

Version The API version to use, as specified in the WSDL.

Example: 2009-05-15

Yes

Note

Requests must include either Timestamp or Expires, but cannot contain both.

Parameter values must be URL-encoded. This is true for any Query parameter passed to AmazonCloudWatch, and is typically necessary in the Signature parameter. Some clients do thisautomatically, but this is not the norm.

http://www.w3.org/TR/NOTE-datetime

Amazon CloudWatch Developer GuideError Codes


Error CodesTopics

• Overview (p. 50)

• Client Error Codes (p. 50)

• Common Server Error Codes (p. 50)

• Common Client Error Codes (p. 51)

OverviewThere are two types of error codes: client and server.

Client error codes suggest that the error was caused by something the client did, such as anauthentication failure or an invalid parameter. In the SOAP API, these error codes are prefixed withClient. For example: Client.AuthFailure. In the Query API, these errors are accompanied by a400-series HTTP response code.

Server error codes suggest a server-side issue caused the error and should be reported. In the SOAPAPI, these error codes are prefixed with Server. For example: Server.Unavailable. In the QueryAPI, these errors are accompanied by a 500-series HTTP response code.

Client Error Codes

Error Code Description HTTPStatusCode

SOAP FaultCode Prefix

InvalidInterval The most likely cause is that the end timeis set to be before the start time.

400 BadRequest

Client

InvalidMeasureName No metrics exist for the specified measurename.

400 BadRequest

Client

InvalidMetric No metrics exist for the specified measurename and set of dimensions specified.

400 BadRequest

Client

InvalidPeriod The period is either less than 60 seconds,or is not a multiple of sixty seconds.

400 BadRequest

Client

Common Server Error CodesThe following server errors are common across all the services can be returned in addition to thespecific errors listed for each service.



InternalFailure Indicates that the request processinghas failed due to some unknown error,exception or failure.

500 InternalFailure Error

Server

Amazon CloudWatch Developer GuideCommon Client Error Codes




ServiceUnavailable Indicates that the request has failed dueto a temporary failure of the server.

500 ServiceUnavailableError

Server

Common Client Error CodesThe following client errors are common across all the services and can be returned in addition to thespecific errors listed for each service.

Error Code Description HTTP StatusCode

SOAPFaultCodePrefix

ElementNotSigned An element that ismarked/configured tobe signed is not signed(AWS SOAP only).

403 Forbidden Client

IncompleteSignature The request signaturedoes not conform to AWSstandards.

400 BadRequest

Client

InvalidAction The action or operationrequested is invalid.

400 BadRequest

Client

InvalidClientTokenId The X.509 certificateor AWS Access Key Idprovided does not exist inour records.


InvalidParameterCombination Parameters that must notbe used together wereused together.

400 BadRequest

Client

InvalidParameterValue Bad or out of range valuewas supplied for the inputparameter.

400 BadRequest

Client

InvalidQueryParameter AWS query stringis malformed, doesnot adhere to AWSstandards.

400 BadRequest

Client

InvalidSecurity The security tokenprovided in the input ismissing or expired (AWSSOAP only).


InvalidSecurityToken Incorrect or invalid data issupplied for the securitytoken.

400 BadRequest

Client




SOAPFaultCodePrefix

InvalidSOAPRequest The SOAP request isinvalid or malformed.

400 BadRequest

Client

MalformedInput The request is invalid ormalformed.

400 BadRequest

Client

MalformedQueryString The query string ismalformed.

400 BadRequest

Client

MalformedSOAPSignature The signature elementin the SOAP request ismalformed.

400 BadRequest

Client

MissingAction The request is missingan action or operationparameter.

400 BadRequest

Client

MissingAuthenticationToken Request must containeither a valid (registered)AWS Access Key Id orX.509 certificate.


MissingParameter An input parameterthat is mandatory forprocessing the request isnot supplied.

400 BadRequest

Client

OptInRequired The AWS Access Key Idneeds a subscription forthe service


RequestExpired Request is past expiresdate or more than 15minutes past requestdate.

400 BadRequest

Client

RequiresSSL The request mustbe made over SSLconnection.

401Unauthorized

Client

Throttling Request was denied dueto request throttling.

400 BadRequest

Client

WSSecurityMultipleCredentialError More than one credentialreceived in the WS-Security header of therequest.

400 BadRequest

Client

WSSecurityEncodingTypeError The BinarySecurityTokenis not base64 encoded.

400 BadRequest

Client

WSSecurityMultipleX.509Error More than one X.509binary security tokenreceived in WS-Securityheader of the request.

400 BadRequest

Client




SOAPFaultCodePrefix

UnknownEnvelopeNamespace The envelope namespaceused to define the SOAPrequest is invalid.

400 BadRequest

Client

Amazon CloudWatch Developer GuideAmazon CloudWatch Operations


Amazon CloudWatch OperationsThe following operations are available from the Amazon CloudWatch.

Metric Retrieval Operations:

• GetMetricStatistics (p. 55)

• ListMetrics

Amazon CloudWatch Developer GuideGetMetricStatistics


GetMetricStatistics

Description

This call returns data for one or more statistics of given a metric. For more information, see Statistic (p.8) and Metric (p. 7).

Note

The maximum number of datapoints that the Amazon CloudWatch service will return in asingle GetMetricStatistics request is 1,440. If a request is made that would generate moredatapoints than this amount, Amazon CloudWatch will return an error. You can alter yourrequest by narrowing the time range (StartTime, EndTime) or increasing the Period in yoursingle request. You may also get all of the data at the granularity you originally asked for bymaking multiple requests with adjacent time ranges.

Request Parameters


CustomUnit The user-defined CustomUnit applied to aMeasure. Please see the key term Unit (p. 8).

Type: String

Default: None

Note

CustomUnits are not currentlyavailable.

No




Dimensions Amazon CloudWatch allows you to specifyone Dimension to further filter metric data on.If you don't specify a dimension, the servicereturns the aggregate of all the measures withthe given measure name and time range. Formore information, see Dimension (p. 7) for moreinformation on aggregation by dimension.

Exception: LoadBalancerName andAvailabilityZone can be used together as aspecial case of multiple-dimension aggregation.

Constraints: Must correspond to dimensions ofa currently gathered metric. Please see AmazonCloudWatch Dimensions (p. 31).

Type: String

Default: None

Note

Some API operations take listsof parameters. These lists arespecified using the following notation:param.member.n. Values of n areintegers starting from 1. All lists ofparameters must follow this notation,including lists that only contain oneparameter. For example, an Queryparameter list looks like this:

&attribute.member.1=this&attribute.member.2=that

No

EndTime The timestamp to use for determining thelast datapoint to return. This is the lastdatapoint to fetch, exclusive. For example,2008-02-26T20:00:00+00:00.

Type: dateTime (in ISO 8601 format; for moreinformation, go to http://isotc.iso.org .)

Default: None

Yes

MeasureName The measure name that corresponds to themeasure for the gathered metric.

Type: String

Default: None

Constraints: Must be a valid collected metricwith the corresponding measure name, pleasesee Available Amazon CloudWatch Metrics (p.26)

Yes

http://isotc.iso.org




Namespace The namespace corresponding to the serviceof interest. For example, AWS/EC2 representsAmazon EC2.

Type: String

Default: None

No

Period The granularity (in seconds) of the returneddatapoints.

Type: Integer

Valid Values: 60 or a multiple of 60

Default: 60

No

Statistics The statistics to be returned for the givenmetric.

Type: String

Default: None

Yes

StartTime The timestamp of the first datapointto return, inclusive. For example,2008-02-26T19:00:00+00:00. We round yourvalue down to the nearest minute.

You can set your start time for more than twoweeks in the past. However, you will only getdata for the past two weeks.

Type: dateTime (in ISO 8601 format; for moreinformation, go to http://isotc.iso.org .)

Default: None

Constraints: Must be before EndTime

Yes

Unit The standard unit of Measurement for a givenMeasure. Please see the key term Unit (p. 8).

Type: String

Default: None

Valid Values: For more information, seeStandardUnit (p. 67)

Constraints: When using count/second as theunit, you should use Sum as the statistic insteadof Average. Otherwise, the sample returns asequal to the number of requests instead of thenumber of 60-second intervals. This will causethe Average to always equals one when the unitis count/second.

Yes




Response Elements

Name Description

Datapoints A collection of Datapoint (p. 63) elements.

Type: Datapoints (p. 64)

Examples

http://monitoring.amazonaws.com/?SignatureVersion=2&Action=GetMetricStatistics&Version=2009-05-15&Period=60&Statistics.member.1=Average&Namespace=AWS/EC2&StartTime=2009-01-16T00:00:00&EndTime=2009-01-16T00:02:00&MeasureName=CPUUtilization&Timestamp=2009-01-08-18&AWSAccessKeyId=XXX YOUR ACCESS KEY XXX&Signature=%XXX YOUR SIGNATURE XXX%3D

Sample Response

<GetMetricStatisticsResponse> <GetMetricStatisticsResult> <Datapoints> <member> <Timestamp>2009-01-16T00:00:00Z</Timestamp> <Unit>Percent</Unit> <Samples>9.0</Samples> <Average>0.17777777777777778</Average> </member> <member> <Timestamp>2009-01-16T00:01:00Z</Timestamp> <Unit>Percent</Unit> <Samples>8.0</Samples> <Average>0.1</Average> </member> </Datapoints> <Label>CPUUtilization</Label> </GetMetricStatisticsResult> <ResponseMetadata> <RequestId>a9f8f3a3-e40f-11dd-af0f-cf11f65ec49d</RequestId> </ResponseMetadata></GetMetricStatisticsResponse>

Amazon CloudWatch Developer GuideListMetrics


ListMetrics

DescriptionThis call returns a list of up to 500 valid metrics for which there is recorded data available to a you anda NextToken string that can be used to query for the next set of results.

Request Parameters


NextToken The NextToken parameter is an optionalparameter that allows you to retrieve the nextset of results for your ListMetrics query.

Type: String

Default: None

No

Response Elements

Name Description

MetricsList A complete list of all of the metrics being used togenerate statistics for this customer.

Examples

http://monitoring.amazonaws.com/?SignatureVersion=2&Action=ListMetrics&Version=2009-05-15&Timestamp=2009-01-08T18%3A32%3A53.000Z&AWSAccessKeyId=XXX YOUR ACCESS KEY XXX&Signature=%XXX YOUR SIGNATURE XXX%3D&SignatureMethod=%HmacSHA256

Sample Response

<ListMetricsResponse> <ListMetricsResult> <Metrics> <member> <Dimensions/> <MeasureName>NetworkIn</MeasureName> <Namespace>AWS/EC2</Namespace> </member> <member> <Dimensions> <member>

Amazon CloudWatch Developer GuideListMetrics


<Name>InstanceId</Name> <Value>i-c385b3aa</Value> </member> </Dimensions> <MeasureName>CPUUtilization</MeasureName> <Namespace>AWS/EC2</Namespace> </member> <member> <Dimensions> <member> <Name>InstanceId</Name> <Value>i-c385b3aa</Value> </member> </Dimensions> <MeasureName>NetworkIn</MeasureName> <Namespace>AWS/EC2</Namespace> </member> <member> <Dimensions> <member> <Name>InstanceId</Name> <Value>i-c385b3aa</Value> </member> </Dimensions> <MeasureName>DiskWriteBytes</MeasureName> <Namespace>AWS/EC2</Namespace> </member> </Metrics> </ListMetricsResult> <ResponseMetadata> <RequestId>4ce61c9b-7345-11de-947b-1d8b67d70c11</RequestId> </ResponseMetadata></ListMetricsResponse>

Amazon CloudWatch Developer GuideData Types


Data TypesTopics

• Datapoint (p. 63)

• Datapoints (p. 64)

• Dimension (p. 65)

• Dimensions (p. 66)

• StandardUnit (p. 67)

• Statistics (p. 68)

The Amazon CloudWatch API contains several data types that various operations use. This sectiondescribes each data type in detail.

Since both the Query and SOAP APIs return the same XML body, the data types described in theWSDL are used in both.

Amazon CloudWatch Developer GuideDatapoint


DatapointThe Datapoint data type.

Relevant Operations• GetMetricStatistics (p. 55)

ContentsThe following table describes the elements contained in Datapoint.


Average Average of samples for the datapoint.

Type: double

No

Maximum Maximum of the samples used for the datapoint.

Type: double

No

Minimum Minimum of samples for the datapoint.

Type: double

No

Timestamp Indicates the beginning of the time aggregation for thisvalue and samples.

Type: dateTime(in ISO 8601 format; for moreinformation, go to http://isotc.iso.org.)

Note

The dateTime type uses ISO 8601. Please seethe ISO 8601 information at the following url:http://isotc.iso.org.

No

Samples The number of Measurements that contributed to theaggregate value of this datapoint.

Type: double

No

Sum Sum of samples for the datapoint.

Type: double

No

Unit Standard unit used for the datapoint.

Type: String

No

CustomUnit CustomUnit defined for the datapoint.

Type: String

No



Amazon CloudWatch Developer GuideDatapoints


DatapointsThe Datapoints data type.


ContentsThe following table describes the elements contained in Datapoints.


Datapoints A datapoint.

Type: Datapoint (p. 63)

Yes

Amazon CloudWatch Developer GuideDimension


DimensionThe Dimension data type.


ContentsThe following table describes the elements contained in Dimension.


Name Name of the dimension. For more information,see Amazon CloudWatch Dimensions (p. 31)

Type: String

Yes

Value Value of a dimension.

Type: String

Yes

Amazon CloudWatch Developer GuideDimensions


DimensionsThe Dimensions data type.


ContentsThe following table describes the elements contained in Dimensions.


Dimensions A dimension.

Type: Dimension (p. 65)

No

Amazon CloudWatch Developer GuideStandardUnit


StandardUnitThe StandardUnit data type.


ContentsThe following table describes the elements contained in Standard Units.


StandardUnit Type: String

Valid Values: Seconds, Percent, Bytes, Bits,Count, Bytes, Bits/Second, Count/Second,and None.

No

Amazon CloudWatch Developer GuideStatistics


StatisticsThe Statistics data type.


ContentsThe following table describes the elements contained in Statistics.


Statistics A statistic.

Type: String

Valid Values: Average, Maximum, Minimum,Samples,and Sum

Yes



Glossary

Access Key Id An alphanumeric token that uniquely identifies a request sender.This ID is associated with your Secret Access Key.

Amazon Elastic ComputeCloud

The Amazon Elastic Compute Cloud (Amazon EC2) is a webservice that enables you to launch and manage server instances inAmazon's data centers using APIs or available tools and utilities.

Amazon Machine Image An Amazon Machine Image (AMI) is an encrypted machine imagestored in Amazon Simple Storage Service (Amazon S3). It containsall the information necessary to boot instances of your software.

Amazon Simple QueueService

Amazon Simple Queue Service (Amazon SQS) offers a reliable,highly scalable, hosted queue for storing messages as they travelbetween computers.

Availability Zone Amazon EC2 locations are composed of Regions and AvailabilityZones. Availability Zones are distinct locations that are engineeredto be insulated from failures in other Availability Zones and provideinexpensive, low latency network connectivity to other AvailabilityZones in the same Region.

AutoScalingGroup Auto Scaling key term. A capacity group is a representation of adistributed application running on multiple Amazon Elastic ComputeCloud (EC2) instances that are to be automatically scaled. Pleasesee the detailed information on this term in the Automatic ScalingService Developer Guide.

dimension Amazon CloudWatch key term. Please see the detailed informationon this term, located at key term Dimension (p. 7).

EC2 instance After an AMI is launched in the cloud, the resulting running systemis called an instance or EC2 instance. By default, you can run up to20 EC2 instances. All instances based on the same AMI start outidentical and any information on them is lost when the instancesare terminated or fail.

LoadBalancer Elastic Load Balancing key term. An LoadBalancer is representedby a DNS name and provides the single destination to which allrequests intended for your application should be directed. Please



see the detailed information on this term in the Load BalancingService Developer Guide.

Measure Amazon CloudWatch key term. Please see the detailed informationon this term, located at key term Measure (p. 7).

metric Amazon CloudWatch key term. Please see the detailed informationon this term, located at key term Metric (p. 7).

Region Amazon EC2 locations are composed of Regions and AvailabilityZones. Regions are geographically dispersed and will be inseparate geographic areas or countries. Regions consist of one ormore Availability Zones.

scaling activity Auto Scaling key term. A scaling activity is a long-running processthat represents a change to your capacity group. Please see thedetailed information on this term in the Automatic Scaling ServiceDeveloper Guide.

Secret Access Key A key assigned to you by Amazon Web Services (AWS) when yousign up for an AWS account. Used for request authentication.

statistic Amazon CloudWatch key term. Please see the detailed informationon this term, located at key term Statistic (p. 8).

trigger Auto Scaling key term. A trigger defines the metrics and user-defined thresholds based on those metrics to be used in theautomatic scaling of capacity groups. Please see the detailedinformation on this term in the Automatic Scaling Service DeveloperGuide.

unbounded Term used in Web Service Definition Language (WSDL), i.e.maxOccurs="unbounded", meaning that the number of potentialoccurences is not limited by a set number. Very often usedwhen defining a data type that is a list of other types, such as anunbounded list of integers (element members) or an unbounded listof other complex types that are element/members of the list beingdefined.

unit Amazon CloudWatch key term. Please see the detailed informationon this term, including standard and CustomUnits, located at keyterm Unit (p. 8).

Amazon CloudWatch Developer GuideTypographical Conventions


Document Conventions

This section lists the common typographical and symbol use conventions for AWS technicalpublications.

Typographical ConventionsThis section describes common typographical use conventions.

Convention Description/Example

Call-outs A call-out is a number in the body text to give you a visual reference. Thereference point is for further discussion elsewhere.

You can use this resource regularly.

Code in text Inline code samples (including XML) and commands are identified with aspecial font.

You can use the command java -version.

Code blocks Blocks of sample code are set apart from the body and markedaccordingly.

# ls -l /var/www/html/index.html-rw-rw-r-- 1 root root 1872 Jun 21 09:33 /var/www/html/index.html# dateWed Jun 21 09:33:42 EDT 2006

Emphasis Unusual or important words and phrases are marked with a special font.

You must sign up for an account before you can use the service.

Internal crossreferences

References to a section in the same document are marked.

Logical values,constants, and regularexpressions, abstracta

A special font is used for expressions that are important to identify, but arenot code.

If the value is null, the returned response will be false.

Amazon CloudWatch Developer GuideTypographical Conventions


Convention Description/Example

Product and featurenames

Named AWS products and features are identified on first use.

Create an Amazon Machine Image (AMI).

Operations In-text references to operations.

Use the GetHITResponse operation.

Parameters In-text references to parameters.

The operation accepts the parameter AccountID.

Response elements In-text references to responses.

A container for one CollectionParent and one or moreCollectionItems.

Technical publicationreferences

References to other AWS publications. If the reference is hyperlinked, it isalso underscored.

For detailed conceptual information, see the Amazon Mechanical TurkDeveloper Guide.

User entered values A special font marks text that the user types.

At the password prompt, type MyPassword.

User interface controlsand labels

Denotes named items on the UI for easy identification.

On the File menu, click Properties.

Variables When you see this style, you must change the value of the content whenyou copy the text of a sample to a command line.

% ec2-register <your-s3-bucket>/image.manifest

See also the following symbol convention.

Amazon CloudWatch Developer GuideSymbol Conventions


Symbol ConventionsThis section describes the common use of symbols.

Convention Symbol Description/Example

Mutuallyexclusiveparameters

(Parentheses | and| vertical | bars)

Within a code description, bar separators denote options fromwhich one must be chosen.

% data = hdfread (start | stride | edge)

Optionalparameters

XML variabletext

[square brackets] Within a code description, square brackets denote completelyoptional commands or parameters.

% sed [-n, -quiet]

Use square brackets in XML examples to differentiate themfrom tags.

<CustomerId>[ID]</CustomerId>

Variables <arrow brackets> Within a code sample, arrow brackets denote a variable thatmust be replaced with a valid value.

% ec2-register <your-s3-bucket>/image.manifest



IndexAAccess Key Id, 69Amazon CloudWatch

About Dimensions, 29(see also Dimension, Statistic, Metric, Measure)

API, 54conceptual overview, 10data types, 62dimensions available, 31

(see also Retrieving Metrics Using Dimensionsand Statistics)

Getting Started, 16introductory overview, 6major features, 6metrics available, 26

(see also Retrieving Metrics Using Dimensionsand Statistics)

statistics available, 28(see also Retrieving Metrics Using Dimensionsand Statistics)

Amazon Elastic Compute Cloud (Amazon EC2), 69Amazon Machine Image (AMI), 69Amazon Simple Queue Service (Amazon SQS), 69API

Amazon CloudWatch data types, 62common query parameters, 49conventions, 47data types, 47Query, 19SOAP, 22User Scenarios, 32, 33, 35, 37, 39, 41, 43, 45

APIsGetMetricStatistics, 55ListMetrics, 60

authenticationQuery, 19signature version 2, 19SOAP, 22

AutoScalingGroup, 69Availability Zone, 69

Cclient error codes, 50Conceptual Overviews

Amazon CloudWatch, 10Regions, 8

conventionsAPI, 47

Ddata types, 47

Datapoint, 63Datapoints, 64

Dimension, 65Dimensions, 66RequestId, 19StandardUnit, 67Statistics, 68

Datapoint, 63Datapoints, 64Dimension, 65dimension, 69Dimensions, 7, 66

aggregation along dimension, 31(see also Amazon CloudWatch)

Description, 31dimensions available for EC2 data, 31

EEC2 instance, 69

Amazon CloudWatch dimensions available, 31Amazon CloudWatch metrics available, 26

Elastic Load BalancingAmazon CloudWatch metrics available, 27

error codes, 50

GGetMetricStatistics, 55

Kkey terms

Dimension, 7measure, 7Metric, 7Statistic, 8Unit, 7, 8

LListMetrics, 60LoadBalancer, 69

MMeasure, 7, 69Metric, 7metric, 69Metrics

available metrics, 26, 26, 27(see also Amazon CloudWatch)

NNamespace, 7

Ooperations

Amazon CloudWatch, 16, 54Overviews

Amazon CloudWatch , 5What is Amazon CloudWatch, 6



Pprogramming language support, 22

QQuery

API, 19authentication, 19parameters, 19

querycommon parameters, 49

Rregion, EC2 region, 69Regions

conceptual overview, 8RequestId, 19response structure, 24response structure, SOAP, 24ResponseMetadata

RequestId, 19

Sscaling activity, 69Secret Access Key, 69server error codes, 50signature version 2, 19SOAP

API, 22authentication, 22response structure, 24, 24WSDL, 22

StandardUnit, 67Statistic, 8

aggregation of data, computation of statistics ondata, 28

(see also Amazon CloudWatch)statistic, 69Statistics, 68

Ttrigger, 69

Uunbounded, 69Unit, 8unit, CustomUnit, standard unit, 69User Scenarios

API, 32Compare RequestCount by Availability Zone for aLoad Balanced EC2 Application, 37Get A Single Metric Across All Dimensions, 43Get Available Metrics Across Multiple Instances, 45Get Average CPUUtilization for EC2 Instances Witha Particular ImageId, 33Get Latency Statistics for a LoadBalancer, 39

Get Maximum CPUUtilization per EC2 Instance, 35Get Total DiskWriteBytes for a Capacity-ManagedEC2 Application, 41

Wweb services references, 25WSDL, 22

amazon cloud watch-dg

Documents