Publish Custom Metrics
You can publish your own metrics to CloudWatch using the AWS CLI or an API. You can view statistical graphs of your published metrics with the AWS Management Console.
CloudWatch stores data about a metric as a series of data points. Each data point has an associated time stamp. You can even publish an aggregated set of data points called a statistic set.
Using Dimensions
When publishing custom metrics, you will often use the dimensions
parameter. A dimension further clarifies what the metric is, and what data it stores. You can have up to 10 dimensions in
one metric, and each dimension is defined by a Name and Value pair.
Note that how you specify a dimension is different when you use different commands. With
putmetricdata, you
specify each dimension as
MyName
=MyValue
, while with getmetricstatistics or
putmetricalarm you
use the format Name=
MyName
,
Value=
MyValue
. For example, the following command
publishes a "Buffers" metric with two dimensions named InstanceId and InstanceType.
Copyaws cloudwatch putmetricdata metricname Buffers namespace MyNameSpace unit Bytes value 231434333 dimensions InstanceId=123456789,InstanceType=m1.small
And then this command retrieves statistics for that same metric. Note that you separate the Name and Value parts of a single dimension with commas, but you use a space between one dimension and the next if you have multiple dimensions.
Copyaws cloudwatch getmetricstatistics metricname Buffers namespace MyNameSpace dimensions Name=InstanceId,Value=123456789 Name=InstanceType,Value=m1.small starttime 20161015T04:00:00Z endtime 20161019T07:00:00Z statistics Average period 60
Also note that if a single metric includes multiple dimensions, you must specify a value for every defined dimension when
you use getmetricstatistics. For example, the Amazon S3 metric BucketSizeBytes
includes the dimensions BucketName
and StorageType
, so you must specify both dimensions with getmetricstatistics.
Copyaws cloudwatch getmetricstatistics metricname BucketSizeBytes starttime 20170123T14:23:00Z endtime 20170126T19:30:00Z period 3600 namespace AWS/S3 statistics Maximum dimensions Name=BucketName,Value=
MyBucketName
Name=StorageType,Value=StandardStorage output table
You can see what dimensions are defined for a metric by using the listmetrics command.
Publish Single Data Points
To publish a single data point for a new or existing metric, use the putmetricdata command with one value and time stamp. For example, the following actions each publish one data point:
Copyaws cloudwatch putmetricdata metricname
PageViewCount
namespaceMyService
value 2 timestamp20161014T12:00:00.000Z
aws cloudwatch putmetricdata metricnamePageViewCount
namespaceMyService
value 4 timestamp20161014T12:00:01.000Z
aws cloudwatch putmetricdata metricnamePageViewCount
namespaceMyService
value 5 timestamp20161014T12:00:02.000Z
If you call this command with a new metric name, CloudWatch creates a metric for you. Otherwise, CloudWatch associates your data with the existing metric that you specified.
Note
When you create a metric, it can take up to two minutes before you can retrieve statistics for the new metric using the getmetricstatistics command. However, it can take up to fifteen minutes before the new metric appears in the list of metrics retrieved using the listmetrics command.
Although you can publish data points with time stamps as granular as onethousandth of a
second, CloudWatch aggregates the data to a minimum granularity of one minute. CloudWatch records the
average (sum of all items divided by number of items) of the values received for every
1minute period, as well as number of samples, maximum value, and minimum value for the same
time period. For example, the PageViewCount
metric from the previous examples
contains three data points with time stamps just seconds apart. CloudWatch aggregates the three
data points because they all have time stamps within a oneminute period.
CloudWatch uses oneminute boundaries when aggregating data points. For example, CloudWatch
aggregates the data points from the previous example because all three data points fall
within the oneminute period that begins at 20161020T12:00:00.000Z
and ends
at 20161020T12:01:00.000Z
.
You can use the getmetricstatistics command to retrieve statistics based on the data points that you published.
Copyaws cloudwatch getmetricstatistics namespace
MyService
metricnamePageViewCount
\ statistics "Sum" "Maximum" "Minimum" "Average" "SampleCount" \ starttime20161020T12:00:00.000Z
endtime20161020T12:05:00.000Z
period 60
The following is example output:
Copy{ "Datapoints": [ { "SampleCount": 3.0, "Timestamp": "20161020T12:00:00Z", "Average": 3.6666666666666665, "Maximum": 5.0, "Minimum": 2.0, "Sum": 11.0, "Unit": "None" } ], "Label": "PageViewCount" }
Publish Statistic Sets
You can aggregate your data before you publish to CloudWatch. When you have multiple
data points per minute, aggregating data minimizes the number of calls to
putmetricdata. For example, instead of calling
putmetricdata multiple times for three data points that are within
three seconds of each other, you can aggregate the data into a statistic set that you
publish with one call, using the statisticvalues
parameter:
Copyaws cloudwatch putmetricdata metricname PageViewCount namespace
MyService
statisticvalues Sum=11,Minimum=2,Maximum=5,SampleCount=3 timestamp20161014T12:00:00.000Z
CloudWatch needs raw data points to calculate percentiles. If you publish data using a statistic set instead, you cannot retrieve percentile statistics for this data unless one of the following conditions is true:

The SampleCount of the statistic set is 1

The Min and the Max of the statistic set are equal
Publish the Value Zero
When your data is more sporadic and you have periods that have no associated data, you
can choose to publish the value zero (0
) for that period or no value at all.
You might want to publish zero instead of no value if you use periodic calls to
PutMetricData
to monitor the health of your application. For example,
you can set a CloudWatch alarm to notify you if your application fails to publish metrics every
five minutes. You want such an application to publish zeros for periods with no associated
data.
You might also publish zeros if you want to track the total number of data points or if you want statistics such as minimum and average to include data points with the value 0.