CloudWatch JSON queries

Reading time: 0 minute(s) (0 words)

CloudWatch Metrics Insight JSON Queries are JSON arrays that consist of a non-empty list of JSON items, where each item in the array encompasses of a separate query.

Each Metrics Insight JSON Query must include:

A unique id.
An expression (can be an SQL query or an operation on the auxiliary queries: refer to the examples below).
Other parameters, such as a period.

Here’s an example of a Metrics Insight JSON Query:

objectives:
  - countMetrics:
      good:
        cloudWatch:
          json: |
            [
                {
                    "Id": "e1",
                    "Expression": "SELECT AVG(CPUUtilization)FROM \"AWS/EC2\"",
                    "Period": 60
                }
            ]
          region: us-east-1
      incremental: false
      total:
        cloudWatch:
          json: |
            [
                {
                    "Id": "e2",
                    "Expression": "SELECT MAX(CPUUtilization)FROM \"AWS/EC2\"",
                    "Period": 60
                }
            ]
          region: us-east-1

Combining multiple queries

JSON queries are a powerful tool that entitles users to combine multiple time series, or even combine the results of the component queries.

The JSON query outlined in the below example consists of:

An auxiliary query "Id": "m1" that queries for a one time series.
An auxiliary query "Id": "m2" that queries for a different time series.

On top of that, the main query "Id": "e1" combines the results of the m1 and m2 queries. In the following example, the results of the query m1 are a numerator, while the results of the query m2 are a denominator, which is defined in the following query expression:

"Expression": "m1 / m2"

This means that number of correct HTTP requests from the query m1 (HTTPCode_Target_2XX_Count) are divided by the number of total requests in the m2 query (RequestCount). As a result, using such a query, we give input to our e1 indicator as a ratio of good to total HTTP requests:

rawMetric:
  cloudWatch:
    json: |-
      [
          {
              "Id": "e1",
              "Expression": "m1 / m2",
              "Period": 60
          },
          {
              "Id": "m1",
              "MetricStat": {
                  "Metric": {
                     "Namespace": "AWS/ApplicationELB",
                      "MetricName": "HTTPCode_Target_2XX_Count",
                      "Dimensions": [
                          {
                              "Name": "LoadBalancer",
                              "Value": "<LOAD_BALANCER_NAME>"
                          }
                      ]
                  },
                  "Period": 60,
                  "Stat": "Sum"
              },
              "ReturnData": false
          },
          {
              "Id": "m2",
              "MetricStat": {
                  "Metric": {
                      "Namespace": "AWS/ApplicationELB",
                      "MetricName": "RequestCount",
                      "Dimensions": [
                          {
                              "Name": "LoadBalancer",
                              "Value": "<LOAD_BALANCER_NAME>"
                          }
                      ]
                  },
                  "Period": 60,
                  "Stat": "Sum"
              },
              "ReturnData": false
          }
      ]
    region: eu-central-1

The only condition is for a single query in the array to have the ReturnData value set to true. true is the default value for the main query. See the section below for more details.

Another example demonstrates a 5xx error count query.

The JSON query consists of the two auxiliary queries as well:

e1 sets up a metric expression that calculates the maximum value of a metric, filling any missing data points with 0, over a 60-second period.
m1 specifies a metric statistic for the HTTP 5XX error count of a specific Application Load Balancer and Target Group in the AWS namespace AWS/ApplicationELB, also over a 60-second period.

This configuration example uses the JSON-based syntax to log data management, so it won't work with SQL queries.

[
  {
    "Id": "e1",
    "Expression": "MAX(FILL(METRICS(), 0))",
    "Period": 60
  },
  {
    "Id": "m1",
    "MetricStat": {
      "Metric": {
        "Namespace": "AWS/ApplicationELB",
        "MetricName": "HTTPCode_Target_5XX_Count",
        "Dimensions": [
          {
            "Name": "LoadBalancer",
            "Value": "<LOAD_BALANCER_NAME>"
          },
          {
            "Name": "TargetGroup",
            "Value": "<TARGET_GROUP_NAME>"
          }
        ]
      },
      "Period": 60,
      "Stat": "Sum"
    },
    "ReturnData": false
  }
]

Notes:

Use the FILL method for a JSON configuration with the MAX(FILL(METRICS(), 0)) expression to ensure that any missing data points are filled with a default value, in this case, 0. So, it preserves data continuity in the case of missing data, and maximum value calculation (MAX) will operate correctly.
<LOAD_BALANCER_NAME> and <TARGET_GROUP_NAME> are the names of resources you want to monitor.
The Stat field in the examples refers to metric data aggregations.
"ReturnData": false indicates that the metric data should not be returned.