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
      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)
.div(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
      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.

Matching the resource.project_id column

Every resource type includes the label resource.project_id. This label designates the project that owns the resource and the data about that resource.

The resource.project_id label has the project number in text form as its value, but MQL converts that value to the project name in certain situations. For example, a project with name "monitoring-demo" might have project number "530310927541". The value of the resource.project_id label for any resource owned by this project is "530310927541", but in certain cases, MQL treats it as if the value were "monitoring-demo".

In the following cases, MQL treats the resource.project_id label as having the project name available as well as the project number:

  • The legend for a chart displays the project name rather than the project number for the value of the resource.project_id label.

  • Equality comparisons of the value of the resource.project_id to a string literal, recognize both the project number and the project name. For example, both the following returns true for resources owned by this project:

    • resource.project_id == "monitoring-demo"
    • resource.project_id == "530310927541"

    This works for the == and != operators and for their function forms eq() and ne().

  • A regular expression match on the resource.project_id label will work properly against either the project number or project name. For example, both the following returns true for resources owned by this project:

    • resource.project_id =~ "monitoring-.*"
    • resource.project_id =~ ".*27541"

    This works for the =~ and !~ operators and for the function form re_full_match.

Note that the actual column value is the number and the numeric value is used for all other operations. For example, concatenate("project-", resource.project_id) results in the value "project-530310927541" and not "project-monitoring-demo".