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

It's a best practice to use the GetMetricData API instead of GetMetricStatistics because:

  • GetMetricData returns ordered results.
  • GetMetricData is cheaper. You can request more data points for a single metric using GetMetricData. For example, you must make 70 GetMetricStatistics calls to return the same number of data points as one GetMetricData call.
  • GetMetricData paginates results.
    Note: To return the next set of data points, you must iterate over the data using the NextToken (--next-token) provided in the response.

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:

  • 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.

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. Be sure to use put-metric-data with the input parameter --metric-data and your JSON file if you want to use a single API call to publish multiple metrics. 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

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

Back to the AWS Support Knowledge Center

Need help? Visit the AWS Support Center

Published: 2018-07-23

Updated: 2019-03-29