Using PromQL in Google Cloud

PromQL stands for Prometheus Query Language. This post is about using PromQL in Cloud Monitoring. PromQL provides an alternative to the Metrics Explorer menu-driven builder and Monitoring Query Language (MQL) interfaces for exploring metrics, creating charts and alerts. Google Cloud introduced support for PromQL at the same time as Managed Service for Prometheus. Later, support for PromQL was introduced in Monitoring alert management. Practically it means that you can use PromQL instead of Monitoring Query Language (or MQL) to query Cloud Monitoring metrics in the Metrics Explorer, in custom dashboard configurations, and in alert management.

PromQL with Cloud Console

Using the “Monitoring” menu in the Google Cloud console you can query metrics, create charts for your custom dashboards and define alert policies to receive notifications about monitored metrics and services. In each case you can write your query in PromQL.

When using Metrics Explorer or creating a chart you can enter a PromQL query by switching from the query-builder to the query editor by selecting the button whose name is either < > PromQL or < > MQL. Verify that PromQL is selected in the Language toggle which is located in the same toolbar that lets you format your query. Select it if it is not selected.

A very similar interface lets you use PromQL to define a query in the Policy configuration step. Just switch from Builder to Code editor and choose the PromQL radio button in the language selection to write the metric expression in PromQL.

PromQL with CLI and API

Outside of the Cloud console you can run PromQL queries using the gcloud CLI, the Google provider for Terraform, and Google APIs. You can call the Google Cloud APIs directly or use Cloud SDK client libraries that generate call primitives for you. The following tables show commands, configurations and calls for each activity:

Query metrics

This functionality is supported only in the projects.location.prometheus.api.v1 REST API. The API supports the following methods to query metrics using PromQL:

This API is also available using gRPC protocol. To call this API you will need to have the roles/monitoring.view or another with a similar set of permissions.

Create or update a dashboard chart

CLI and API do not support management of the single chart. To define a chart that uses PromQL query you will have to create or update the configuration of the custom dashboard that shows the chart. The configuration is defined as a JSON object following the Dashboard schema. The dashboard schema includes the layout field that describes one of possible dashboard layouts. Each of the layouts includes configuration of one or more Widget objects. The widget objects that show metric data have a complex structure. The query configuration for the widgets is defined in the TimeSeriesQuery object. Use the prometheusQuery field of the object to define the PromQL expression string.

For example, the path to the prometheusQuery in the XYChart widgets is dataSets[].timeSeriesQuery.prometheusQuery.

The gcloud CLI commands to create or update custom dashboards are gcloud monitoring dashboards create and gcloud monitoring dashboards update respectively. The dashboard configuration is passed as a JSON string or a path to the file storing JSON using --config or --config-from-file respective parameters. Consult with documentation regarding JSON format.

Provisioning custom dashboards in Terraform are implemented using the google_monitoring_dashboard Terraform resource. The resource uses the dashboard_json parameter to define the dashboard’s configuration.

The v1.projects.dashboards REST API supports create and patch methods to create and update the custom dashboard. These API methods are also available using gRPC protocol. To call the methods you will need to have the roles/monitoring.dashboardEditor or roles/monitoring.editor or another with the monitoring.dashboards.* permissions.

Create alert policy

Creating Monitoring alert policies in CLI is currently not supported. You can provision the alert policies in Terraform using the google_monitoring_alert_policy resource.

The v3.projects.alertPolicies REST API provides [create][alert_create] and [patch][alert_update] methods to create and update a Monitoring alert policy. Use the condition_prometheus_query_language field to define the alert’s condition using PromQL expression like in this example. Use the conditionPrometheusQueryLanguage field to define the PromQL expression in the method’s payload. See AlertPolicy documentation for more details. These API methods are also available using gRPC protocol. To call the methods you will need to have the roles/monitoring.alertPolicyEditor or roles/monitoring.editor or another with the monitoring.alertPolicies.* permissions.

Migrate from MQL to PromQL

Today you can query metrics in Cloud Monitoring in several ways. PromQL is a recommended method and support for MQL will be disallowed for new resources on July 22, 2025. You can use Prometheus documentation, PromQL examples, and this cheatsheet from PromLabs to become familiar with the language. When you use Cloud Monitoring metric names in PromQL you need to convert the name to be compatible with PromQL. Cloud Monitoring metric names include two components, a domain (such as compute.googleapis.com/) and a path (such as instance/disk/max_read_ops_count). And PromQL supports only two special characters : and _. To map a Cloud Monitoring metric name to PromQL, apply these simple rules:

1. Replace the first / with :.
2. Replace all other special characters (including . and other / characters) with _.

From the previous example:

Cloud Monitoring metric name: compute.googleapis.com/instance/disk/max_read_ops_count
PromQL metric names: compute_googleapis_com:instance_disk_max_read_ops_count

Cloud Monitoring distribution-valued metrics can be queried like Prometheus histograms, with _count, _sum, or _bucket suffix appended to the metric name:

Some metrics within Cloud Monitoring, including some system metrics and many of those generated by log-based metrics are associated with more than one resource type. The MQL query for such a metric uses a fetch command with filtering. If a metric is associated with more than one resource type, then you must specify the resource type in your PromQL query. There is a special label, monitored_resource, that you can use to select the resource type.
The following basic example shows a conversion of the query that fetches CPU utilization of VM instances in the “us-central1” region for the project “cymbal-shop”.

MQL query :

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| filter resource.zone =~ 'us-central1-*'
  && resource.project_id == 'cymbal-shop'

PromQL query:

compute_googleapis_com:instance_cpu_utilization{
  monitored_resource = "gce_instance",
  zone =~ "us-central1-*",
  project_id = "cymbal-shop"
}

For additional information including specifying a monitored resource type or using metric labels, consult the mapping documentation. Rewriting MQL queries and converting metric names can be tiresome and is prone to errors. You can prompt the AI-powered Gemini Cloud Assist to convert metric names or queries from MQL to PromQL format. Note that use of Cloud Assist may incur additional costs.