Use the code editor for PromQL

This page describes how to use the code editor for PromQL. The editor is available in the Google Cloud console and provides suggestions and other tools for creating valid PromQL queries.

This page doesn't cover the PromQL language; for information about PromQL, we recommend consulting open source documentation. The following resources can help you get started:

Access the code editor

You access PromQL from the following pages in the Google Cloud console:

  • Metrics Explorer
  • Add widget when creating dashboards

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

  1. In the navigation panel of the Google Cloud console, select Monitoring, and then select  Metrics explorer:

    Go to Metrics explorer

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

Use the code editor

To use the code editor, type your query into the text field 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.

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:

code editor supports a find-and-replace 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 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, then the editor shows a yellow triangle in the control bar. If there is room, the text Incomplete query also appears.

    The 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

How you save a chart depends on the context in which you created the chart:

  • From Metrics Explorer.
  • As part of creating or editing a custom dashboard.

Save charts from Metrics Explorer

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

  1. In the navigation panel of the Google Cloud console, select Monitoring, and then select  Metrics explorer:

    Go to Metrics explorer

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

  5. If you do not have the auto-run option for the code editor enabled, then run your query by clicking Run Query before saving the chart. By default, custom dashboards periodically save your changes. When you don't run your query first, the code editor saves the last query you ran.

  6. Click Save Chart.

  7. To continue saving the chart:

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

Save charts on a custom dashboard

To save a new chart to your dashboard, do the following:

  1. Give the chart a descriptive title.

  2. If you do not have the auto-run option for the code editor enabled, then run your query by clicking Run Query before saving the chart. By default, custom dashboards periodically save your changes. When you don't run your query first, the code editor saves the last query you ran.

  3. If you don't have autosave enabled for your dashboard, then click Save.

The Google Cloud console supports page-level filters for custom dashboards. These filters are supported for PromQL charts on your custom dashboards.

Exit the code editor

To exit the code editor without saving your query, click one of the other selector tabs. Any query text in the editor is discarded, but you are given the option to save it to the clipboard.