Alerting policies with PromQL

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This page explains different methods of creating alerting policies with a PromQL query.

PromQL alerting provides an open source alternative to using Monitoring Query Language (MQL) queries to configure your alerting policy conditions. It also allows for fully Google Cloud CLI-based alert execution, which removes dependencies on external alerting infrastructure.

You can use PromQL queries to create complex conditions with features such as ratios, dynamic thresholds, and combined metrics.

If you use Prometheus in environments outside Google Cloud, or if you use alerting in Managed Service for Prometheus, then you can migrate your Prometheus alerting rules to alerting policies with a PromQL query. This way, you can manage all of your alerting policies in Cloud Monitoring.

For general information on using PromQL in Monitoring, see PromQL in Cloud Monitoring. For general information on Monitoring alerting policies, see Behavior of metric-based alerting policies.

Overview

During the Public Preview, you can create alerting policies with a PromQL condition in two ways:

• Migrate your Prometheus alerting rules and notification channels to Monitoring by using the Google Cloud CLI.

• Create an alerting policy with a PromQL query in the condition by using the gcloud CLI or the AlertPolicy construct in the Monitoring API.

After you create a PromQL alerting policy, you can view, edit, and delete it in the Cloud Monitoring API and the gcloud CLI. You can disable, snooze, and delete it in the Google Cloud console.

Incidents created by alerting policies with a PromQL query appear in the Google Cloud console with your other incidents. You can interact with these incidents in the Google Cloud console.

Your PromQL alerting policy conditions can reference any metric in Cloud Monitoring, including Google Cloud system metrics, custom and log-based metrics, and Prometheus metrics. If your Prometheus alerting rule references a custom metric, then you must have an equivalent custom metric descriptor in Cloud Monitoring. You must translate the names of non-Prometheus metrics to PromQL metric syntax. For more information, see Mapping Monitoring metrics to PromQL.

Migrate Prometheus alerting rules and receivers to Cloud Monitoring

In the gcloud CLI, you can migrate your existing alert rules and receivers to create Cloud Monitoring alerting policies and notification channels. The gcloud CLI can perform the following types of migration:

• If you provide a Prometheus configuration file with an alerting rule, then the gcloud CLI creates an alerting policy with a PromQL query.

  You can provide multiple Prometheus configuration files at the same time to create multiple alerting policies with a PromQL query.

• If you provide a Prometheus Alertmanager file with at least one receiver, then the gcloud CLI converts each receiver to an equivalent notification channel in Monitoring.

  Note: You can migrate an AlertManager receiver only when Cloud Monitoring supports the same type of notification channel. For example, Cloud Monitoring doesn't support Jira receivers, so they can't be migrated from a Prometheus AlertManager file. If you try to migrate an incompatible receiver, then the gcloud CLI ignores the receiver. If you want to use a receiver that Cloud Monitoring doesn't support, then create a notification channel that uses Webhook for private endpoints or Pub/Sub for private endpoints.

• If you provide a Prometheus Alertmanager file and a Prometheus configuration file at the same time, then the gcloud CLI creates the alerting policy and notification channel, and then associates the new notification channel with the new alerting policy.

  If you provide multiple configuration files with alert rules, then gcloud CLI assigns every notification channel from the Alertmanager file to each new alerting policy.

If your Prometheus alerting rule references a custom metric, then the gcloud CLI requires an equivalent metric descriptor to create the alerting policy.

Prometheus configuration files and Prometheus Alertmanager files must be formatted as valid Prometheus rule files in either YAML or JSON.

Field Mapping

The gcloud CLI maps fields between a Prometheus alert rule and a Monitoring alerting policy as follows:

Prometheus alert rule	Monitoring alerting policy
alert	conditionPrometheusQueryLanguage.alertRule
expr	conditionPrometheusQueryLanguage.query
for	conditionPrometheusQueryLanguage.duration
labels	conditionPrometheusQueryLanguage.labels
annotations: "summary"	documentation.subject
annotations: "description"	documentation.content

Restrictions

Cloud Monitoring doesn't support alerting policy PromQL queries with lookback windows greater than 25 hours.

What's next

For information about how to migrate PromQL alerting rules to alerting policies with a PromQL query, see Migrate alerting rules and receivers from Prometheus.

For information about how to create alerting policies with PromQL conditions directly in Monitoring, see Create alerting policies with a PromQL query.