Is it better to use GetMetricData or GetMetricStatistics for CloudWatch metrics?

Short description

Because GetMetricData retrieves data faster at scale, it's a best practice to use the GetMetricData API instead of GetMetricStatistics. Also, GetMetricData supports metric math and returns ordered, paginated results. You're not charged to use GetMetricStatistics in CloudWatch for up to 1 million API requests. However, you're charged to use GetMetricData in CloudWatch.

The following are the service quotas for the GetMetricData API:

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

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you use the most recent AWS CLI version.

To call the GetMetricData API in the AWS CLI, complete the following steps:

1. Create an input parameter for your GetMetricData API call.
   Example call:

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

   Note: In the preceding call, the input parameter has Invocations and Errors custom metrics. The ErrorRate metric is calculated by the metric math of the other two metrics.

2. To publish sample metric data as custom metrics, use PutMetricData.
   Example call:

   $ 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: To publish up to 20 metrices, use a single PutMetricData API call under the same namespace. To run a single PutMetricData API call under the same namespace, use the --metric-data option in the PutMetricData call.

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

   $ 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

4. Review the output.
   Example output:

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

   Note: In the preceding example output, five data points are calculated with metric math and returned as a time-ordered result. Because ReturnData is set to false, m1 and m2 aren't included in the response.

Related information

get-metric-statistics