Using MQL from the Monitoring API

This page describes how to provide Monitoring Query Language (MQL) queries to the Cloud Monitoring API.

This page doesn't cover creating the MQL queries. For a set of example queries, see Examples. MQL Refererence provides a comprehensive reference for the language.

For general information on MQL-based alerting policies, see Alerting policies with MQL.

Using MQL from the API

You can provide MQL queries at the following places in the Monitoring API:

Retrieving data with timeSeries.query

To retrieve time-series data from the API with a MQL query, use the timeSeries.query method.

The timeSeries.query method takes a minimal structure that looks like this in JSON):

{
  "query": string
}

For the value of the query field, specify a string in MQL:

{

  "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count
            | within 5m"
}

To experiment with the API, you can use the API Explorer tool on the timeSeries.query reference page. For an introduction to API Explorer tool, see API Explorer.

Another way to try the API is to put the query into a text file and then execute the query using curl. The following example passes the query in the file query.json to the timeSeries.query method:

curl -d @query.json -H "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" -X POST \
https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries:query

For more information on using curl, see Invoking curl.

If successful, the query returns a table containing the time series requested. The table is divided into two components:

  • The timeSeriesDescriptor describes the label keys, label values, and data points in the table. It doesn't contain any data; it simply describes the data.

  • The timeSeriesData contains the data described in the time-series descriptor. This data is presented as an array of pairs.

    • The first item in the pair, labelValues, records a set of values for the labels listed in the time-series descriptor.
    • The second, pointData, is an embedded array of value/timestamp pairs, which represent the data collected with the specified set of label values.

The response, slightly reformatted, looks like this:

[{
  "timeSeriesTable": {
    "timeSeriesDescriptor": {
      "labelDescriptors": [
        { "key": "resource.project_id" },
        { "key": "resource.zone" },
        { "key": "resource.instance_id" },
        { "key": "metric.instance_name" }
      ],
      "valueDescriptors": [
        {
          "key": "value.utilization",
          "valueType": "DOUBLE",
          "metricKind": "GAUGE"
        }
      ],
      "pointDescriptors": [
        {
          "key": "value.utilization",
          "valueType": "DOUBLE",
          "metricKind": "GAUGE"
        }
      ]
    },
    "timeSeriesData": [
      {
        "labelValues": [
          { "stringValue": "632526624816" },
          { "stringValue": "us-central1-a" },
          { "stringValue": "5106847938297466291" },
          { "stringValue": "gke-kuber-cluster-default-pool-6fe301a0-n8r9" }
        ],
        "pointData": [
          {
            "values": [
              {
                "doubleValue": 0.063896992710942874
              }
            ],
            "timeInterval": {
              "startTime": "1969-12-31T23:59:59.999999Z",
              "endTime": "2020-03-02T20:17:00Z"
            }
          },
          { ... additional value/timestamp pairs ...}
        ]
      },
      { ... additional labelValue/pointData pairs ...},
    ]
  }

Building charts

You can use the dashboards.create method to programmatically create dashboards and the charts they contain.

The only difference between creating MQL-based charts and other charts is the type of TimeSeriesQuery query you use to populate the chart's data set.

Constructing an MQL-based chart

For MQL queries, use the query as the value of the timeSeriesQueryLanguage string field in the chart's DataSet array.

The following is a simple dashboard definition that includes MQL:

{
  "displayName": "Dashboard for MQL chart (API)",
  "gridLayout": {
    "widgets": [
      {
        "title": "Min/Max Compute Engine CPU utilization",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | within(1h) | { top 1, max(val()) ; bottom 1, min(val()) } | union"
              },
              "plotType": "LINE",
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

This creates a dashboard titled "Dashboard for MQL chart (API)" in your project. The dashboard contains a chart called "Min/Max Compute Engine CPU Utilization", which shows two lines, one for the highest values and one for the lowest.

Chart shows the time series with the highest and lowest
values.

For more information on this example query, see Combining selections with union.

Creating a chart

You can put the dashboard JSON into a file and then pass the file to gcloud beta monitoring dashboards create or use curl to post it to https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards. For more examples, see Creating a dashboard. For more information on using curl, see Invoking curl.

For general information on creating charts and dashboards, see Managing dashboards by API. For reference material, see Dashboards.

Creating conditions for alerting policies

You use the alertPolicies.create method to programmatically create alerting policies.

The only difference between creating MQL-based alerting policies and other alerting policies is the type of Condition you use. Otherwise, you create these policies like any other alerting policy.

The MQL query used in an alert condition must be in strict form. You can write the strict-form query manually, but it's easier to use the Query Editor and click Add as if to save the condition. The strict-form query is provided for confirmation. You can copy that version of the query for use with the API. Then click Cancel to abandon the condition in the UI.

For more information, see Strict-form queries.

The following shows a simple, non-strict MQL query for an alert-policy condition that tests for Compute Engine CPU utilization exceeding 15 percent:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| window 5m
| condition val() > 0.15 '10^2.%'

The following shows the strict form of the query:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| align mean_aligner()
| window 5m
| condition value.utilization > .15 '10^2.%'

For more information on the MQL condition alert operation, see Alerting policies with MQL.

Constructing the alerting policy

To build an alerting policy based on an MQL query, use the AlertPolicy condition type MonitoringQueryLanguageCondition. The MonitoringQueryLanguageCondition has the following structure:

{
  "query":    string,
  "duration": string,
  "trigger":  {
    object (Trigger)
  }
}

The value of the query field is a MQL alerting-query string.

The duration field specifies the length of time during which each evaluation of the query must generate a true value before the alerting policy is triggered. For more information, see Alerting behavior. The value must be a number of minutes, expressed in seconds; for example, 600s for a 10-minute duration.

The trigger field specifies how many time series must satisfy the condition during the duration period. The default value is 1. For more in information, see Trigger.

For the example alerting query, with a 10-minute duration and a trigger count of 1, the structure looks like the following:

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | align mean_aligner() | window 5m | condition value.utilization > 0.15 '10^2.%'",
  "duration": "600s",
  "trigger" : {
     "count": 1
  }
}

Use this structure as the value of a conditionMonitoringQueryLanguage field in a condition, which is in turn embedded in an alerting-policy structure. For more information on these structures, see AlertPolicy.

The following shows a complete minimal policy with a MonitoringQueryLanguageCondition condition in JSON:

{
  "displayName":"Alert if CPU utilization exceeds 15% for 10 mins (MQL, API)",
  "combiner":"OR",
  "conditions":[
    {
      "displayName":"MQL-based utilization condition, API",

      "conditionMonitoringQueryLanguage":
      {
        "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | align mean_aligner() | window 5m | condition value.utilization > 0.15 '10^2.%'",
        "duration": "600s",
        "trigger" : {
           "count": 1
        },
     },
   }
  ],
}

Creating an alerting policy

To create the policy, you can put the alerting-policy JSON into a file and then pass the file to gcloud alpha monitoring policies create or use curl to post it to https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies.

For more information about the Monitoring API for alerting policies, see Managing alerting policies by API.

For more information on using curl, see Invoking curl.

Invoking curl

Each curl invocation includes a set of arguments, followed by the URL of an API resource. The common arguments include a Google Cloud project ID and an authentication token. These values are represented here by the PROJECT_ID and TOKEN environment variables.

You might also have to specify other arguments, for example, to specify the type of the HTTP request (for example, -X DELETE). The default request is GET, so the examples don't specify it.

Each curl invocation has this general structure:

curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

To use curl, you must specify your project ID and an access token. To reduce typing and errors, you can put these into environment variables as pass them to curl that way.

To set these variables, do the following:

  1. Create an environment variable to hold the ID of your Cloud Monitoring Workspace. These steps call the variable PROJECT_ID:

    PROJECT_ID=a-sample-project
    
  2. Authenticate to the Cloud SDK:

    gcloud auth login
    
  3. Optional. To avoid having to specify your project ID with each gcloud command, set your project ID as the default by using Cloud SDK:

    gcloud config set project ${PROJECT_ID}
    
  4. Create an authorization token and capture it in an environment variable. These steps call the variable TOKEN:

    TOKEN=`gcloud auth print-access-token`
    

    You have to periodically refresh the access token. If commands that worked suddenly report that you are unauthenticated, reissue this command.

  5. To verify that you got an access token, echo the TOKEN variable:

    echo ${TOKEN}
    ya29.GluiBj8o....