Should I use GetMetricData or GetMetricStatistics for CloudWatch metrics?

Last updated: 2019-10-24

I want to retrieve data points from my Amazon CloudWatch metrics. Which API should I use, GetMetricData or GetMetricStatistics?

Short Description

It's a best practice to use the GetMetricData API instead of GetMetricStatistics, because you can retrieve data faster at scale with GetMetricDataGetMetricData also supports metric math, and it returns ordered, paginated results.

  Metrics per call Data points per call Supports metric math Returns ordered and paginated results
GetMetricData 100 100,800 Yes Yes*
GetMetricStatistics 1 1,440 No No

*To return the next set of data points, you must iterate over the data using the NextToken (--next-token) provided in the response.

The limits for the GetMetricData API are:

  • 50 transactions per second (TPS).
  • 180,000 data points per second (DPS), if the StartTime in the API request is less than or equal to three hours from the current time.
  • 90,000 DPS, if the StartTime is more than three hours from the current time.

Resolution

Before you begin, be sure to install the latest version of the AWS Command Line Interface (AWS CLI).

Use the following example call as a reference for making your own GetMetricData API calls in the AWS CLI.

1.    Create an input parameter for your GetMetricData API call (metric-data-queries.json). The input parameter has two custom metrics (Invocations and Errors) and one metric (ErrorRate) calculated by the metric math of the other two metrics (ErrorRate).

$ cat metric-data-queries.json
[
    {
        "Id": "e1",
        "Expression": "m1 / m2",
        "Label": "ErrorRate"
    },
    {
        "Id": "m1",
        "MetricStat": {
            "Metric": {
                "Namespace": "MyApplication",
                "MetricName": "Errors",
                "Dimensions": [
                    {
                        "Name": "FunctionName",
                        "Value": "MyFunc"
                    }
                ]
            },
            "Period": 300,
            "Stat": "Sum",
            "Unit": "Count"
        },
        "ReturnData": false
    },
    {
        "Id": "m2",
        "MetricStat": {
            "Metric": {
                "Namespace": "MyApplication",
                "MetricName": "Invocations",
                "Dimensions": [
                    {
                        "Name": "FunctionName",
                        "Value": "MyFunc"
                    }
                ]
            },
            "Period": 300,
            "Stat": "Sum",
            "Unit": "Count"
        },
        "ReturnData": false
    }
]

2.     Publish sample metric data as custom metrics using PutMetricData. For example:

$ aws cloudwatch put-metric-data --namespace MyApplication --metric-name Invocations --dimensions FunctionName=MyFunc --value 10 --unit Count --timestamp 2018-06-19T04:00:00Z
$ aws cloudwatch put-metric-data --namespace MyApplication --metric-name Invocations --dimensions FunctionName=MyFunc --value 10 --unit Count --timestamp 2018-06-19T04:05:00Z
$ aws cloudwatch put-metric-data --namespace MyApplication --metric-name Invocations --dimensions FunctionName=MyFunc --value 10 --unit Count --timestamp 2018-06-19T04:10:00Z
$ aws cloudwatch put-metric-data --namespace MyApplication --metric-name Invocations --dimensions FunctionName=MyFunc --value 10 --unit Count --timestamp 2018-06-19T04:15:00Z
$ aws cloudwatch put-metric-data --namespace MyApplication --metric-name Invocations --dimensions FunctionName=MyFunc --value 10 --unit Count --timestamp 2018-06-19T04:20:00Z
$ aws cloudwatch put-metric-data --namespace MyApplication --metric-name Errors --dimensions FunctionName=MyFunc --value 3 --unit Count --timestamp 2018-06-19T04:00:00Z
$ aws cloudwatch put-metric-data --namespace MyApplication --metric-name Errors --dimensions FunctionName=MyFunc --value 6 --unit Count --timestamp 2018-06-19T04:05:00Z
$ aws cloudwatch put-metric-data --namespace MyApplication --metric-name Errors --dimensions FunctionName=MyFunc --value 2 --unit Count --timestamp 2018-06-19T04:10:00Z
$ aws cloudwatch put-metric-data --namespace MyApplication --metric-name Errors --dimensions FunctionName=MyFunc --value 9 --unit Count --timestamp 2018-06-19T04:15:00Z
$ aws cloudwatch put-metric-data --namespace MyApplication --metric-name Errors --dimensions FunctionName=MyFunc --value 1 --unit Count --timestamp 2018-06-19T04:20:00Z

Note: You can also publish up to 20 metrics using a single PutMetricData API call under the same namespace. To do so, use the --metric-data option in the PutMetricData call.

3.    Run the command aws cloudwatch get-metric-data with your input parameters.

4.    Review the output. In this example, five data points are calculated using metric math and returned as a time-ordered result. m1 and m2 are not included in the response, because ReturnData is set to false.

$ aws cloudwatch get-metric-data --metric-data-queries file://./metric-data-queries.json --start-time 2018-06-19T04:00:00Z --end-time 2018-06-19T04:30:00Z
{
    "MetricDataResults": [
        {
            "Timestamps": [
                "2018-06-19T04:20:00Z",
                "2018-06-19T04:15:00Z",
                "2018-06-19T04:10:00Z",
                "2018-06-19T04:05:00Z",
                "2018-06-19T04:00:00Z"
            ],
            "StatusCode": "Complete",
            "Values": [
                0.1,
                0.9,
                0.2,
                0.6,
                0.3
            ],
            "Id": "e1",
            "Label": "ErrorRate"
        }
    ]
}

Did this article help you?

Anything we could improve?


Need more help?