Did this page help you? Yes No Tell us about it...

Publishing Custom Metrics

You can publish your own metrics to Amazon CloudWatch with the mon-put-data command (or its Query API equivalent PutMetricData). You can view statistical graphs of your published metrics with the AWS Management Console.

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

	Note
	The `mon-list-metrics` command can take up to two minutes to report metrics created by calls to `mon-put-data`. The Query API equivalent `ListMetrics`, however, can take up to fifteen minutes.

Amazon 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 mon-put-data. You can even publish an aggregated set of data points called a statistics set.

Publishing Single Data Points

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

mon-put-data --metric-name PageViewCount --namespace "MyService" --value 2 --timestamp 2011-03-14T12:00:00.000Z
mon-put-data --metric-name PageViewCount --namespace "MyService" --value 4 --timestamp 2011-03-14T12:00:01.000Z
mon-put-data --metric-name PageViewCount --namespace "MyService" --value 5 --timestamp 2011-03-14T12:00:02.000Z

	Note
	If you want to run this example, specify time stamps within the past two weeks.

If you use the Query API instead of the command-line tools, you can publish up to 20 data points in a single call to PutMetricData by passing a list of data points. The list can contain data points that apply to different metrics, but the metrics must all belong to the same namespace.

	Note
	The `mon-put-data` command can currently publish only one data point per call.

Although you can publish data points with time stamps as granular as one-thousandth of a second, Amazon CloudWatch aggregates the data to a minimum granularity of one minute. For example, the PageViewCount metric from the previous examples contains three data points with time stamps just seconds apart. Amazon CloudWatch aggregates the three data points because they all have time stamps within a one-minute period.

Amazon CloudWatch uses one-minute boundaries when aggregating data points. For example, Amazon CloudWatch aggregates the data points from the previous example because all three data points fall within the one-minute period that begins at 2011-03-14T12:00:00.000Z and ends at 2011-03-14T12:00:59.999Z.

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

mon-get-stats PageViewCount -n "MyService" -s "Sum,Maximum,Minimum,Average,SampleCount" --start-time 2011-03-14T12:00:00.000Z --end-time 2011-03-14T12:01:00.000Z --headers

Amazon CloudWatch returns the following:

Time                 SampleCount  Average            Sum   Minimum  Maximum Unit
2011-03-14 12:00:00  3.0          3.6666666666666665 11.0  2.0      5.0     None

Publishing Statistic Sets

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

mon-put-data --metric-name PageViewCount --namespace "MyService" -s "Sum=11,Minimum=2,Maximum=5,SampleCount=3" --timestamp 2011-03-14T12:00:00.000Z

Publishing 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 an Amazon 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.

Document Conventions
Terms of Use

Did this page help you? Yes No Tell us about it...