Should I use GetMetricData or GetMetricStatistics for CloudWatch metrics?

Short description

It's a best practice to use the GetMetricData API instead of GetMetricStatistics, because you can retrieve data faster at scale with GetMetricData. GetMetricData also supports metric math, and it returns ordered, paginated results. This difference in functionality is reflected in the cost of each service. GetMetricStatistics is included in the free tier of CloudWatch, for up to 1 million API requests, while GetMetricData is not. Refer to the chart below and the CloudWatch pricing chart to see which API is more appropriate for you.

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

The service quotas 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.
• 396,000 DPS, if the StartTime is more than three hours from the current time.

Resolution

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.

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"
        }
    ]
}

Related information

get-metric-data AWS CLI reference

get-metric-statistics AWS CLI reference