Amazon CloudWatch
Developer Guide (API Version 2010-08-01)

Publish Custom Metrics

You can publish your own metrics to CloudWatch with the put-metric-data command (or its Query API equivalent PutMetricData). For more information, see put-metric-data in the AWS Command Line Interface Reference. You can view statistical graphs of your published metrics with the AWS Management Console.

If you call put-metric-data with a new metric name, CloudWatch creates a new metric for you. Otherwise, CloudWatch associates your data with the existing metric that you specify.


When you create a new metric using the put-metric-data command, it can take up to two minutes before you can retrieve statistics on the new metric using the get-metric-statistics command. However, it can take up to fifteen minutes before the new metric appears in the list of metrics retrieved using the list-metrics command.

CloudWatch stores data about a metric as a series of data points. Each data point has an associated time stamp. You can publish one or more data points with each call to put-metric-data. You can even publish an aggregated set of data points called a statistics set.

Publish Single Data Points

To publish a single data point for a new or existing metric, use the put-metric-data command with one value and time stamp. For example, the following actions each publish one data point:

aws cloudwatch put-metric-data --metric-name PageViewCount --namespace "MyService" --value 2 --timestamp 2014-02-14T12:00:00.000Z
aws cloudwatch put-metric-data --metric-name PageViewCount --namespace "MyService" --value 4 --timestamp 2014-02-14T12:00:01.000Z
aws cloudwatch put-metric-data --metric-name PageViewCount --namespace "MyService" --value 5 --timestamp 2014-02-14T12:00:02.000Z


The put-metric-data command can only publish one data point per call. If you want to run this example, specify time stamps within the past two weeks.

Although you can publish data points with time stamps as granular as one-thousandth 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 1-minute 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 one-minute period.

CloudWatch uses one-minute boundaries when aggregating data points. For example, CloudWatch aggregates the data points from the previous example because all three data points fall within the one-minute period that begins at 2014-02-20T12:00:00.000Z and ends at 2014-02-20T12:01:00.000Z.

You can use the get-metric-statistics command to retrieve statistics based on the data points you have published.

aws cloudwatch get-metric-statistics --metric-name PageViewCount --namespace "MyService" --statistics "Sum" "Maximum" "Minimum" "Average" "SampleCount" --period 60 --start-time 2014-02-20T12:00:00.000Z --end-time 2014-02-20T12:05:00.000Z --output json 

CloudWatch returns the following:

    "Datapoints": [
            "SampleCount": 3.0, 
            "Timestamp": "2014-02-20T12:00:00Z", 
            "Average": 3.6666666666666665, 
            "Maximum": 5.0, 
            "Minimum": 2.0, 
            "Sum": 11.0, 
            "Unit": "None"
    "Label": "PageViewCount"

Publish Statistic Sets

You can also aggregate your data before you publish to CloudWatch. When you have multiple data points per minute, aggregating data minimizes the number of calls to put-metric-data. For example, instead of calling put-metric-data 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:

aws cloudwatch put-metric-data --metric-name PageViewCount --namespace "MyService" --statistic-value Sum=11,Minimum=2,Maximum=5,SampleCount=3 --timestamp 2014-02-14T12:00:00.000Z

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.