Name and query on Grafana Labs

What is an alert rule

Mon, 10 Aug 2026 13:40:40 -0500

What is an alert rule

An alert rule tells Grafana what data to watch. It defines a threshold for when something becomes a problem, and it defines what to do when something goes wrong and an alert is triggered. You create an alert by completing the New alert rule page in the UI, where you fill out the following sections:

Section	What you set up
Alert rule name	A descriptive name so your team knows what fired
Query and condition	Which data to watch and what “too high” or “too low” means
Folder and labels	Where to store the rule and how to tag it
Evaluation behavior	How often Grafana checks and how long to wait before alerting
Notifications	Where to send the notification when something goes wrong

Why the name matters

The alert rule name shows up in every notification your team receives. A vague name like “Alert 1” tells the responder nothing about what’s wrong. Your alert rule name is the first piece of critical information a responder will see, so a clear naming structure for your alerts helps responders act faster.

Choose names that describe what you’re monitoring and where, for example:

“QuickPizza server errors”
“Payment service error rate above 5%”
“Database connection pool exhausted”

Queries

Mon, 10 Aug 2026 13:40:40 -0500

Queries

Queries tell the alert where to look for data, what metric to choose, and what time series to look at specifically.

Grafana Alerting can query many data sources, not only metrics. You can also alert on logs and other signals when the data source supports alerting. This journey focuses on metrics.

Two ways to write a query

The Prometheus query editor has two options:

Builder method: Lets you construct the query visually by picking the metric and operations from menus
Code method: For writing PromQL by hand, which is more powerful but harder if you’re new to the language

This journey starts with Builder because it’s the simplest way to build a query without learning PromQL. Everything Builder does maps to PromQL behind the scenes, so when you flip to the Code tab, you can see the generated PromQL query.

Overview of query components

You want to alert when the QuickPizza app returns server errors (HTTP 5xx responses). Your query will use these pieces:

The tutorial Prometheus data source:
- Data source: grafanacloud-play-prom
A counter that tracks HTTP requests. Each time QuickPizza handles a request, this number grows, and each series carries a response status label:
- Metric: quickpizza_server_http_requests_total
A label filter that matches every 5xx status code in one expression:
- Label filter: status =~ "5.."
A way to count new errors over the last five minutes (counters only go up, so you need a range function), and optionally a sum so the alert uses one total across services:
- Operation: Increase (over 5m), then optionally Sum

With the Builder method, that becomes a query equivalent to sum(increase(quickpizza_server_http_requests_total{status=~"5.."}[5m])).

The exact metric and labels depend on your data source. In the hands-on path, you build this query for the QuickPizza app. The steps you follow, including picking a data source, choosing a metric, filtering, transforming, and previewing, are the same steps you’ll use on your own Prometheus-compatible metrics later.

Always preview

Always preview your query before moving on. The preview is your proof the alert is watching real data.

For QuickPizza, the preview shows how many 5xx responses arrived in the last five minutes. If you skip previewing and the query is empty or wrong, the rule still saves, but it never fires on the condition you care about. You could walk away thinking the service is covered, and then during a real incident the alert you built stays silent.

Alert condition

Mon, 10 Aug 2026 13:40:40 -0500

Alert condition

The alert condition defines when an alert moves toward firing. A threshold is the value the condition compares against.

The condition watches a value over time. If the value stays at or below the threshold, the alert stays normal. When it rises above the threshold and stays there through the pending period you configure later, the alert fires.

For this journey’s QuickPizza server-errors example, the value is how many new 5xx responses arrived in the last five minutes. Alert when that count is above 0 so any server errors in the window can trigger the rule. The alert condition has two parts:

Is above is the operator.
0 is the threshold.

Important: verify after setting

Always click Preview alert rule condition to verify which instances would fire. If you change the operator from Is above to Is below, double-check that the threshold value still makes sense.