Use the code editor for MQL

Announcement: Starting on October 22, 2024, Monitoring Query Language (MQL) will no longer be a recommended query language for Cloud Monitoring. Certain usability features will be disabled, but you can still run MQL queries in Metrics Explorer, and dashboards and alerting policies that use MQL will continue to work. For more information, see the deprecation notice for MQL.

This section describes the features of the code editor for Monitoring Query Language (MQL). The editor is available in the Google Cloud console and provides suggestions, error detection, and other support for creating valid MQL queries.

This page doesn't cover the MQL language; for a set of examples and for more information about the language, see Examples and About the MQL language. MQL Reference provides a comprehensive reference for the language.

Accessing the code editor

To access the code editor when using the Metrics Explorer, do the following:

1. In the Google Cloud console, go to the  Metrics explorer page:

   Go to Metrics explorer

   If you use the search bar to find this page, then select the result whose subheading is Monitoring.

2. In the toolbar of the query-builder pane, select the button whose name is either  MQL or  PromQL.
3. Verify that MQL is selected in the Language toggle. The language toggle is in the same toolbar that lets you format your query.

You use similar steps to access the code editor when you create a chart on a dashboard.

Using the code editor

To use the code editor, type your query into the query editor and click Run Query:

Autocompletion

As you type your query, the editor displays a list of syntactically valid completions. You can manually bring up the autocompletion menu by pressing Control+Space, and you can dismiss it by pressing Escape.

To navigate the list of options, use the arrow keys. Pressing Enter inserts the selected choice.

To insert the prefix common to all available choices, press Tab.

Error messages

Error messages appear at the bottom of the editor pane.

If there are errors in the query that interfere with autocompletion suggestions, error messages appear as you type. Otherwise, error messages appear when you run the query.

Code folding

The editor provides code folding—the ability to collapse segments of your queries—so you can temporarily hide them from view.

The editor indicates foldable segments of your query with carets next to the line numbers, as shown in the following screenshot:

Find and replace

The editor supports a find-and-replace feature. To find, and optionally replace, terms in your query, press Control+F (or Command+F on Mac). The following screenshot shows the feature:

Editor controls

The editor has two controls that determine how it interacts with your query.

By default, your query is executed only when you click Run Query. You can set up the code editor to automatically execute your query as you type, but this option is disabled by default.

To enable the auto-run option, use the Auto-run toggle. When this option is enabled, the editor works as follows:

• The Run Query button isn't displayed.
• Errors messages appear continuously as you type.

• If your cursor is at the end of a query that is incomplete but has no errors, the editor shows a yellow triangle in the control bar. If there is room, the text Incomplete query also appears.

  The code editor does not attempt to evaluate incomplete queries.

There is also a grab-bar between the code editor and the chart region. Use this bar to change the relative sizes of the two regions.

Save charts

From Metrics Explorer

From the code editor in Metrics Explorer, you have the option to save your chart to a dashboard. To save your chart, do the following:

1. If you don't have the auto-execute option enabled, run your query by clicking Run Query before saving the chart. If you don't run your query first, the code editor saves the last query you ran.

2. Click Save Chart. A dialog box tells you that saving the chart replaces the query with a strict form. For more information, see Strict-form queries.

3. To continue saving the chart:

   1. Give the chart a descriptive title.
   2. Select the dashboard for the new chart.
   3. Click Save on the dialog.

From a dashboard

To save a chart that you are adding to a dashboard, do the following:

1. Give the chart a descriptive title.

2. If you don't have the auto-execute option enabled, run your query by clicking Run Query before saving the chart. If you don't run your query first, the code editor saves the last query you ran.

3. Click Save. A dialog box tells you that saving the chart replaces the query with a strict form. For more information, see Strict-form queries.

4. Click Save on the dialog to save your chart and return to the dashboard.

Exit the code editor

To exit the code editor without saving a chart or condition, click Return to query selector widget. Any query text in the editor is discarded, but you are given the option to save it to the clipboard.

View queries in strict form

To view a query in strict form when using the code editor, click More options and select See strict form.

For more information, see Strict-form queries.

Time ranges, charts, and the code editor

Except for MQL queries used in conditions for alerting policies, MQL queries in the code editor must include a time range. The time range specifies the subset of data to return as part of the query. The time range can be expressed implicitly by using the chart's time-range selector or explicitly in your MQL query text.

By default, the time-range selector is set to one hour.

To change the time range of a chart, use the time-range selector. For example, if you want to view the data for the past week, then select Last 1 week from the time-range selector. You can also specify a start and end time, or specify a time to view around.

For information about creating alerting policies with the code editor, see Creating MQL alerting policies.

Using chart settings for time selection

You can set the time period for a query by using the chart's time selector. This selector is the default way to set the time period. To change the time period, select a different time option on the chart. If you select, for example, one week, then your query returns the data from now to a week ago.

When you use this default mechanism, you don't have to specify an explicit time range in the text of your query. The value on the chart is used implicitly.

Using within for time selection

You can specify the time range for the query explicitly in the query by using the within operation. This operation determines the range of returned data. If your query includes a within operation, then the time-selection options on the chart are disabled, and the time range specified in the query is used.

If you remove an explicit within operation from your query, the chart options are automatically re-enabled, ensuring that your query always includes a time period.

You must use explicit time selection if you want to use the API method timeSeries.query to issue the query. For more information, see Using MQL from the Monitoring API.

Time settings and saved charts

If you use MQL to create a chart and then save the chart to a dashboard, two things happen to your query:

1. The query you provided in the editor is converted into a canonical, or strict, form. The conversion doesn't change the meaning of your query, but it makes explicit things that are assumed in the query, like full column names or alignment operations. For more information, see Strict-form queries.

2. The time-range selection in your query is removed. Charts on dashboards share a time selector, and changes to that selector apply to all charts on the dashboard. Therefore, the time-range selector from the original query is no longer needed.

For information on managing dashboards and editing charts, see Manage custom dashboards.

Query, alignment, and display periods

MQL has a number of potentially confusing operations that specify time periods. The following operations are related to the range of a query:

• within: specifies the query-output window. This operation determines how much data is returned. If, for example, you specify within 1h, then the query produces only points whose timestamps are within the last hour, which is why this operation overrides the chart's time-selector options.

• The following operations relate to the alignment period of their output tables. Both require an aligned table as input, or they supply a default:

  • every: specifies the period for aligned table output.

  • window: specifies the window for alignment operations.

  In both cases, if an align operation is provided with an explicit alignment window, it must match the period specified for the window operation, if provided. For the delta alignment function, the alignment window and period must be the same; if an explicit alignment window is given, then the every operation, if given, must agree. In all cases, the alignment window must be at least as large as the alignment period or input data will be ignored.

MQL also has a graph_period operation, which specifies the period of output points for charts. This operation is useful in queries given to the API whose output is being charted by third-party software. The Monitoring charting software ignores the graph_period operation in queries, setting the period of points according to the width in time of the output chart.

In Monitoring charts, the graph period is set based on the value of the chart's time-range selector and the maximum number of points that a chart can display. For example, if you select one week, the graph period might be one hour. For charts on dashboards, to view the graph period, click Query stats.

The relationship between the query alignment period and the graph period can change the way a chart looks. This relationship is described in the following section.

Min/max bands

When the query alignment period is close to the graph period, the chart represents each graphed time series with a single line. If the query alignment period is less than half of the graph period of the chart, the chart includes a shaded region around each line. This region, called a min/max band, shows the range of values that produced the mean value.

For example, assume the following MQL query:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by [zone], mean(val())
| every 1h

This query returns the mean CPU utilization of VMs by zone, with a one-hour alignment period.

If the chart's time selector is set to one week, then the graph period is one hour, which is indicated on a chip. For the example query, the graph period and alignment period are equal. Running the query produces a chart that looks like the following:

For example, if you change the alignment period passed to the every operation from 1h to 1m in the previous query, then the query produces a chart that includes the min/max bands:

The chart lines are graphed with a graph period of one hour, based on the one-week selection for the chart, so the lines are the same as those in the previous example. But the query produces a point every minute, so the min/max bands show the range of one-minute values from the query that fall into each one-hour graph point.

If the every operation is omitted, the default query alignment period is either the value of the alignment window or, if the alignment window is not specified, one minute.

MQL-based alerting policies

You can also use MQL and the code editor to create queries for use in alerting policies.

To create a MQL-based alerting policy from the Google Cloud console, you follow the usual steps for creating the policy, described in Managing alerting policies, but when you create the condition for the alerting policy, you use the code editor instead of the form-based metric selector.

For more information, see Creating MQL alerting policies.

Query conversion

You can use the metric selector for charts or in Metrics Explorer to create a query, and then convert that query to MQL. The corresponding MQL query is shown in the editor.

To convert a menu-built query into MQL, when using the Metrics Explorer, do the following:

1. In the toolbar of the query-builder pane, select the button whose name is either  MQL or  PromQL.
2. Verify that MQL is selected in the Language toggle. The language toggle is in the same toolbar that lets you format your query.

To convert a form-based query into MQL, when viewing a chart on a dashboard, click MQL.

Consider a very simple request, such as "Get the CPU usage from my Compute Engine VM instances." This query involves the gce_instance monitored-resource type and the compute.googleapis.com/instance/cpu/usage_time metric type.

The following screenshot shows this query in the form-based metrics selector:

The metric and monitored-resource types were entered manually. All other fields have their default values.

The following screenshot shows the result of converting the form-based selection into a MQL query:

The MQL query fetches the time series for the specified metric and resource types and performs rate alignment on 1 minute intervals. The converted query is in strict format.

Note: You can't convert the MQL representation back to settings in the form-based metrics selector. MQL supports queries that you can't build with the metrics selector. When you exit the code editor, your query text is discarded if you don't save it.