Amazon CloudWatch Concepts
The terminology and concepts that are central to your understanding and use of Amazon CloudWatch are described below.
A metric is the fundamental concept in CloudWatch. It represents a time-ordered set of data points that are published to CloudWatch. These data points can be either your custom metrics or metrics from other services in AWS. You can retrieve statistics about those data points as an ordered set of time-series data. Metrics exist only in the region in which they are created. Metrics cannot be deleted, but they automatically expire in 14 days if no new data is published to them.
Think of a metric as a variable to monitor, and the data points represent the values of that variable over time. For example, the CPU usage of a particular Amazon EC2 instance is one metric, and the latency of an Elastic Load Balancing load balancer is another.
The data points themselves can come from any application or business activity from which you collect data, not just Amazon Web Services products and applications. For example, a metric might be the CPU usage of a particular Amazon EC2 instance or the temperature in a refrigeration facility.
Metrics are uniquely defined by a name, a namespace, and one or more dimensions. Each data point has a time stamp, and (optionally) a unit of measure. When you request statistics, the returned data stream is identified by namespace, metric name, dimension, and (optionally) the unit.
You can use the
PutMetricData API action (or the
cloudwatch put-metric-data command) to create a custom metric and
publish data points for it. You can add the data points in any order, and at any
rate you choose. For more information, see Publish Custom Metrics.
CloudWatch stores your metric data for two weeks. You can publish metric data from multiple sources, such as incoming network traffic from dozens of different Amazon EC2 instances, or requested page views from several different web applications. You can request statistics on metric data points that occur within a specified time window.
CloudWatch namespaces are containers for metrics. Metrics in different namespaces are isolated from each other, so that metrics from different applications are not mistakenly aggregated into the same statistics.
Namespace names are strings that you define when you create a metric. The names must be
valid XML characters, typically containing the alphanumeric characters
":" (colon). AWS namespaces all follow the convention
AWS/, such as
Namespace names must be fewer than 256 characters in length.
There is no default namespace. You must specify a namespace for each data element you put into CloudWatch.
A dimension is a name/value pair that helps you to uniquely identify a metric. Every metric has specific characteristics that describe it, and you can think of dimensions as categories for those characteristics. Dimensions help you design a structure for your statistics plan. Because dimensions are part of the unique identifier for a metric, whenever you add a unique name/value pair to one of your metrics, you are creating a new metric.
You specify dimensions when you create a metric with the
PutMetricData action (or its command line equivalent
put-metric-data). Services in AWS that feed data to CloudWatch
also attach dimensions to each metric. You can use dimensions to filter result sets
that CloudWatch queries return.
For example, you can get statistics for a specific Amazon EC2 instance by calling
GetMetricStatistics with the
dimension set to a specific Amazon EC2 instance ID.
For metrics produced by certain services such as Amazon EC2, CloudWatch can aggregate data
across dimensions. For example, if you call
for a metric in the AWS/EC2 namespace and do not specify any dimensions, CloudWatch
aggregates all data for the specified metric to create the statistic that you
requested. However, CloudWatch does not aggregate across dimensions for metrics that you
You can assign up to ten dimensions to a metric.
In the figure at the end of this section, the four calls to
put-metric-data create four distinct metrics. If you make
only those four calls, you could retrieve statistics for these four dimension
You could not retrieve statistics using combinations of dimensions
that you did not specifically create. For example, you could not retrieve statistics
for any of the following combinations of dimensions unless you create new metrics
that specify these combinations with additional calls to
CloudWatch treats each unique combination of dimensions as a separate metric. For
example, each call to
put-metric-data in the following
figure creates a separate metric because each call uses a different set of
dimensions. This is true even though all four calls use the same metric name
ServerStats). For information on how this affects pricing, see
the Amazon CloudWatch product information
With Amazon CloudWatch, each metric data point must be marked with a time stamp. The time stamp can be up to two weeks in the past and up to two hours into the future. If you do not provide a time stamp, CloudWatch creates a time stamp for you based on the time the data element was received.
The time stamp you use in the request must be a
dateTime object, with
the complete date plus hours, minutes, and seconds. For more information, see http://www.w3.org/TR/xmlschema-2/#dateTime. For example:
2013-01-31T23:59:59Z. Although it is not required, we recommend that you provide the time
stamp in the Coordinated Universal Time (UTC or Greenwich Mean Time) time zone. When
you retrieve your statistics from CloudWatch, all times reflect the UTC time zone.
CloudWatch alarms check metrics based on the current time in UTC. Custom metrics sent to CloudWatch with time stamps other than the current UTC time may cause alarms to display Insufficient Data state or result in delayed alarms.
Units represent your statistic's unit of measure. For example, the
units for the Amazon EC2
NetworkIn metric are Bytes
NetworkIn tracks the number of bytes that an instance receives
on all network interfaces.
You can also specify a unit when you create a custom metric. Units help
provide conceptual meaning to your data. Metric data points that specify a unit
of measure, such as
Percent, are aggregated separately.
The following list provides some of the more common units that CloudWatch supports:
Bytes/Second(bytes per second)
Bits/Second(bits per second)
Count/Second(counts per second)
None(default when no unit is specified)
Though CloudWatch attaches no significance to a unit internally, other applications can
derive semantic information based on the unit you choose. When you publish data
without specifying a unit, CloudWatch associates it with the
None unit. When
you get statistics without specifying a unit, CloudWatch aggregates all data points of the
same unit together. If you have two otherwise identical metrics with different
units, two separate data streams will be returned, one for each unit.
Statistics are metric data aggregations over specified periods of time. CloudWatch provides statistics based on the metric data points provided by your custom data or provided by other services in AWS to CloudWatch. Aggregations are made using the namespace, metric name, dimensions, and the data point unit of measure, within the time period you specify. The following table describes the available statistics.
The lowest value observed during the specified period. You can use this value to determine low volumes of activity for your application.
The highest value observed during the specified period. You can use this value to determine high volumes of activity for your application.
All values submitted for the matching metric added together. This statistic can be useful for determining the total volume of a metric.
The value of
The count (number) of data points used for the statistical calculation.
You use the
GetMetricStatistics API action or the
get-metric-statistics command to retrieve statistics,
specifying the same values that you used for the namespace, metric name, and
dimension parameters when the metric values were created. You also specify the start
and end times that CloudWatch will use for the aggregation. The starting and ending points
can be as close together as 60 seconds, and as far apart as two weeks.
Amazon CloudWatch allows you to add pre-calculated statistics using the
PutMetricData API action (or the
put-metric-data command) with the
parameter. Instead of data point values, you specify values for
Sum (CloudWatch calculates the average for you). The values you add in
this way are aggregated with any other values associated with the matching metric.
A period is the length of time associated with a specific Amazon CloudWatch statistic. Each statistic represents an aggregation of the metrics data collected for a specified period of time. Although periods are expressed in seconds, the minimum granularity for a period is one minute. Accordingly, you specify period values as multiples of 60. For example, to specify a period of six minutes, you would use the value 360. You can adjust how the data is aggregated by varying the length of the period. A period can be as short as one minute (60 seconds) or as long as one day (86,400 seconds).
When you call
GetMetricStatistics, you can specify the period
length with the
Period parameter. Two related parameters,
the overall length of time associated with the statistics. The default value for the
Period parameter is 60 seconds, whereas the default
you the last hour's worth of statistics.
The values you select for the
EndTime parameters determine how many periods
GetMetricStatistics will return. For example, calling
GetMetricStatistics with the default values for the
StartTime parameters returns an aggregated set of
statistics for each minute of the previous hour. If you prefer statistics aggregated
into ten-minute blocks, set
Period to 600. For statistics
aggregated over the entire hour, use a
Period value of 3600.
Periods are also an important part of the CloudWatch alarms feature. When you create an alarm to monitor a specific metric, you are asking CloudWatch to compare that metric to the threshold value that you supplied. You have extensive control over how CloudWatch makes that comparison. Not only can you specify the period over which the comparison is made, but you can also specify how many consecutive periods the threshold must be breached before you are notified. For more information about alarms, see Alarms.
Amazon CloudWatch aggregates statistics according to the period length that you specify in
GetMetricStatistics. You can publish as many data
points as you want with the same or similar time stamps. CloudWatch aggregates them by
period length when you get statistics about those data points with
GetMetricStatistics. Aggregated statistics are only
available when using detailed monitoring. In addition, Amazon CloudWatch does not aggregate
data across regions.
You can publish data points for a metric that share not only the same time stamp,
but also the same namespace and dimensions. Subsequent calls to
GetMetricStatistics returns aggregated statistics about
those data points. You can even do this in one
request. CloudWatch accepts multiple data points in the same
PutMetricData call with the same time stamp. You can also
publish multiple data points for the same or different metrics, with any time stamp.
The size of a
PutMetricData request, however, is limited to 8KB
for HTTP GET requests and 40KB for HTTP POST requests. You can include a maximum of
20 data points in one
For large data sets that would make the use of
impractical, CloudWatch allows for the insertion of a pre-aggregated data set called a
StatisticSet. With StatisticSets you give CloudWatch the Min,
Max, Sum, and SampleCount of a number of data points. StatisticSets is commonly used
when you need to collect data many times in a minute. For example, let’s say you
have a metric for the request latency of a web page. It doesn’t make sense to do a
PutMetricData request with every web page hit. We suggest
you collect the latency of all hits to that web page, aggregate them together once a
minute and send that StatisticSet to CloudWatch.
Amazon CloudWatch doesn't differentiate the source of a metric. If you publish a metric with the same namespace and dimensions from different sources, CloudWatch treats this as a single metric. This can be useful for service metrics in a distributed, scaled system. For example, all the hosts in a web server application could publish identical metrics representing the latency of requests they are processing. CloudWatch treats these as a single metric, allowing you to get the statistics for minimum, maximum, average, and sum of all requests across your application.
Alarms can automatically initiate actions on your behalf, based on parameters you specify. An alarm watches a single metric over a specified time period, and performs one or more actions based on the value of the metric relative to a given threshold over a number of time periods. The action is a notification sent to an Amazon Simple Notification Service (Amazon SNS) topic or Auto Scaling policy. Alarms invoke actions for sustained state changes only. CloudWatch alarms will not invoke actions simply because they are in a particular state, the state must have changed and been maintained for a specified number of periods. Alarm actions must reside in the same region as the alarm. For example, any Amazon SNS message, Auto Scaling policy, etc. invoked by an alarm must exist in the same region as the alarm and the resource being monitored.
When creating an alarm, select a period that is greater than or equal to the frequency of the metric to be monitored. For example, basic monitoring for Amazon EC2 instances provides metrics every 5 minutes. When setting an alarm on a basic monitoring metric, select a period of at least 300 seconds (5 minutes). Detailed monitoring for Amazon EC2 instances provides metrics every 1 minute; when setting an alarm on a detailed monitoring metric, select a period of at least 60 seconds (1 minute). Alarms exist only in the region in which they are created. Alarm history is available for the last 14 days.
For examples that show you how to set up CloudWatch alarms that invoke an Auto Scaling policy and an Amazon SNS topic, see Creating Amazon CloudWatch Alarms.
Amazon cloud computing resources are housed in highly available data center facilities. To provide additional scalability and reliability, each data center facility is located in a specific geographical area, known as a region. Regions are large and widely dispersed geographic locations.
Each Amazon region is designed to be completely isolated from the other Amazon regions. This achieves the greatest possible failure isolation and stability, and it makes the locality of each Amazon resource unambiguous. Amazon CloudWatch does not aggregate data across regions. Therefore, metrics are completely separate between regions.
For more information about the endpoints that represent each region, see Regions and Endpoints in the Amazon Web Services General Reference.