About the MQL language

This page provides general information about Monitoring Query Language (MQL). This information applies whether you use MQL from the Google Cloud Console or from the Cloud Monitoring API.

This page assumes general familiarity with the MQL language, as described in Examples.

Strict and concise queries

Monitoring Query Language queries can be expressed in a strict form or in a concise form. Concise queries take advantage of shorthand notations and the fact that the language permits some query components to be omitted when they can be deduced or defaulted. For this reason, you might encounter equivalent queries that look quite different from each other.

If you enter a concise query in the Query Editor and then save the chart, the query is converted to the strict form.

This section describes some of these shortcuts and other variations.

For a full list, see Table operation shortcuts.

Shortcuts for operations

The fetch, group_by, and filter operations can be made more concise by omitting the operation name.

The following fetch requests are equivalent:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization

The following group_by operations are equivalent:

group_by [zone], mean(val())
         [zone], mean(val())

You can omit the word filter if you parenthesize the filter test. For example, the following two filter operations are the equivalent:

filter instance_name =~ 'apache.*'
       (instance_name =~ 'apache.*')

Shortcuts for functions

If you're going to apply a function to the value of an input point, for example, as in function(val()), you can use the notation .function. The leading dot means, “Call the following function, supplying the input-point value (or values) as the first argument(s) to the function.”

For example, you can replace the function mean(val()) with .mean. The following are equivalent:

group_by [zone], mean(val())
group_by [zone], .mean

and, applying the group_by shortcut:

[zone], .mean

For the common case of a table of time series with one value in each point, .mean means, “Take the mean of the value of all the points being aggregated.” Similarly, .div(3) means, “Divide the point's value by 3.” The following are equivalent:

div(val(), 3)
val() / 3

Variations on a fetch

The fetch operation returns time-series data for a combination of monitored-resource and metric types. There are also resource and metric operations. Each resource operation must eventually be followed by a metric operation. The following queries are equivalent:

resource gce_instance | metric compute.googleapis.com/instance/cpu/utilization
fetch    gce_instance | metric compute.googleapis.com/instance/cpu/utilization
         gce_instance | metric compute.googleapis.com/instance/cpu/utilization

This resource | metric form is very common, so the following concise forms are also supported, and equivalent to the previous examples:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization

However, the resource operation doesn't have to be followed directly by a metric operation. You can pipe the resource output directly to a filter operation, and then pipe that output to a metric operation. For example:

fetch gce_instance
| filter zone = "us-central1-a"
| metric compute.googleapis.com/instance/cpu/utilization.

This form is very useful if you want to work with two different metric types collected from the same group of monitored resources as a sequence of operations. For more information, see fetch. For another example that uses sequences, see Combining selections with union.

Example: concise-to-strict conversion

When you enter a query using the Query Editor and then save the chart to a dashboard, the query is converted to the strict form.

The following query appears in Combining selections with union:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
     top 1, max(val())
     bottom 1, min(val())
| union

If you enter this query into the Query Editor and then save the chart, the query is converted to the following:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
     t_0: top 1, max(value.utilization)
     t_1: bottom 1, min(value.utilization)
| union

You can retrieve this version of the query from the JSON representation of the chart after you save it to the dashboard:

  1. Go to the dashboard and click on the chart.
  2. From the options menu, select either of the following:

    • Edit
    • Open in Metrics Explorer.

    The Query Editor shows the query in strict form.