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

The GetMetricData API is recommended instead of GetMetricStatistics API for the following reasons:

  • GetMetricData gives ordered results.
  • GetMetricData is cheaper. You can ask for more data points for a single metric by using GetMetricData rather than by using GetMetricStatistics. To get the same number of data points, you must perform 70 GetMetricStatistics calls.

Note: GetMetricData paginates results. You must iterate over the data using the next-token provided in the response to get the next set of data points.

Features of the GetMetricData API

The GetMetricData API supports the following features:

  • Retrieval of 100,800 data points per call. (The GetMetricStatistics limit is 1440 data points per call.)
  • Retrieval of metric data points for multiple metrics in a single call, up to 100 different metrics
  • Metric math

The limits for the GetMetricData API are as follows:

  • 50 transactions per second (TPS)
  • 180,000 data points per second (DPS), if the StartTime used 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.

Call GetMetricData

The following is an example of calling GetMetricData through the AWS Command Line Interface (AWS CLI).

First, sample metric data is published as custom metrics.

Note: You need only one put-metric-data execution with the parameter --metric-data and JSON. However, this example uses multiple put-metric-data executions for simplicity.

$ 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

The input parameter for the GetMetricData API call is metric-data-queries.json. There are three metrics: Invocations, Errors, and ErrorRate. Invocations and Errors are custom metrics. ErrorRate (which is not a custom metric) is calculated by the metric math of the other two metrics.

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

The following is example output after running the command aws cloudwatch get-metric-data with the input parameters.

Note: The 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 page help you? Yes | No

Back to the AWS Support Knowledge Center

Need help? Visit the AWS Support Center

Published: 2018-07-23