PromQL Explainer · Observability
Understand any PromQL query.
Paste a PromQL query and get a plain-English breakdown of every clause — selectors, ranges, rate, aggregations and comparisons — free, entirely in your browser, no signup required.
PromQL Explainer playground
Tip: press Esc to release focus.
Load an example or paste your own PromQL query, then explain it to see a plain-English summary and a token-by-token breakdown here.
The Gap
PromQL is write-once, read-never.
A PromQL alert is easy to write and hard to re-read. Six months later — or in a teammate’s pull request — a line like sum by (job) (rate(...[5m])) / sum by (job) (rate(...[5m])) > 0.05 takes real effort to decode: which window, which labels, what threshold, and why a ratio at all?
The explainer turns that work into a glance. It parses the expression and narrates each clause — the selector and its matchers, the range, the rate, the sum by grouping, and the final comparison — so a reviewer, an on-call engineer, or anyone trying to understand a Prometheus alert rule expression can read intent without rebuilding the query in their head.
New to the syntax? Skim the syntax we decode or try the live playground above.
The Pipeline
How it works.
Four deterministic steps run end-to-end on every press of Explain — all inside your browser tab, every time.
-
Parse the query.
Your PromQL expression is parsed into a syntax tree — selectors, ranges, function calls, aggregations and binary operators — the same shape Prometheus reads.
-
Name each clause.
Every node is labelled by role: the metric and its label matchers, any range vector and offset, the wrapping rate or aggregation, and the comparison.
-
Translate to English.
Each named clause is rendered into a short, readable sentence describing what it selects, computes or asserts — no jargon left undefined.
-
Show the breakdown.
The annotated clauses are stitched into one plain-English summary plus a per-part list, so you can read the query top-down or part-by-part.
The Syntax
What it decodes.
The explainer reads standard PromQL. If you have written a Prometheus alert or dashboard query before, these examples will feel familiar — paste either into the playground to see the full breakdown.
An alerting ratio
A classic error-rate alert: an =~ regex matcher on status, a 5m range, a rate, two sum by (job) aggregations divided into a ratio, and a > 0.05 threshold. The explainer names every one.
sum by (job) (
rate(http_requests_total{status=~"5.."}[5m])
)
/
sum by (job) (
rate(http_requests_total[5m])
) > 0.05A latency quantile
A p99 latency query: histogram_quantile over a sum by (le) of bucket rates. The explainer calls out the 0.99 quantile, the le grouping that makes the histogram work, and the range window.
histogram_quantile(
0.99,
sum by (le) (
rate(http_request_duration_seconds_bucket[5m])
)
)For the formal grammar, see the Prometheus querying basics and functions reference.
A Note On Scope
The explainer describes what a query means, not what it returns: it never connects to a Prometheus server and evaluates no data. It covers the common alerting and dashboard patterns — selectors and matchers, ranges and offsets, rate / increase, the aggregation operators, histogram_quantile and friends, and binary comparisons. Deeply nested subqueries may be summarised rather than fully decomposed. Treat the output as a faithful reading of the expression, not a substitute for the official docs.
FAQ
Questions, answered.
Tap a question to expand the answer.
What is the PromQL Explainer?
The PromQL Explainer is a free, browser-based tool that takes a Prometheus PromQL query and breaks it down into a plain-English explanation. It walks each part of the expression — the metric selector and its label matchers, any range or offset, the rate or aggregation wrapping it, and the threshold comparison at the end — so you can read what a query actually does without parsing it in your head.
Does my query ever leave my browser?
No. The explainer runs 100% client-side. Your query is parsed and explained inside your browser tab — nothing is uploaded to a server, and there is no account or signup. You can safely paste queries that reference internal metric or label names.
Which PromQL features does it understand?
The explainer covers the patterns you meet most in alerting and dashboards: instant and range vector selectors with label matchers (=, !=, =~, !~), range durations and offsets, rate / irate / increase, the aggregation operators (sum, avg, max, min, count and friends) with by / without grouping, common functions like histogram_quantile and clamp, and binary comparisons against a threshold. Exotic or deeply nested subqueries may be summarised rather than fully decomposed.
How is this different from running the query in Prometheus?
Prometheus tells you the result of a query; the explainer tells you the meaning of it. It does not connect to a Prometheus server or return time-series data — it reads the expression itself and describes intent. That makes it useful for reviewing a teammate's alert rule, learning PromQL, or sanity-checking a query before you ship it.
Can I use it to learn PromQL?
Yes. Because every clause is named and described, the explainer doubles as a teaching aid: paste an example from a runbook or dashboard and read back exactly which selector, range, aggregation and comparison it is built from. Pair it with the official Prometheus querying docs for the formal grammar.
Is the PromQL Explainer affiliated with Prometheus?
No. It is an independent, community tool and is not affiliated with or endorsed by the Prometheus project or the Cloud Native Computing Foundation. Prometheus is a trademark of The Linux Foundation. The tool models PromQL syntax for familiarity and uses the vendor name only to describe what it explains.
What does the rate() function mean in a PromQL query?
rate() computes the per-second average rate of increase of a counter over the range window — for example, rate(http_requests_total[5m]) averages the increase per second across the full five minutes. It smooths out spikes and is the standard choice for counter metrics and alerting rules. The explainer identifies rate() and names the range duration so you can read the window at a glance.
What is the difference between rate() and irate() in PromQL?
rate() averages the per-second increase across the entire range vector, producing stable values that suit alerts and slow-moving counters. irate() uses only the last two samples in the window, making it more responsive but noisier — best reserved for graphing fast-moving counters where you want to see short spikes. The explainer labels whichever one appears in your query and describes its behaviour.
What does [5m] mean in a PromQL query?
Square brackets with a duration define a range vector — they tell PromQL to return all samples for each matching series over that lookback window. [5m] means the last five minutes of data. Functions such as rate(), increase(), and avg_over_time() require a range vector as input, so the brackets are what makes those functions work.
How do I read PromQL label matchers like {job="api", status!="200"}?
Curly braces hold a comma-separated list of label matchers that filter which time series are selected. The = operator matches an exact value, != excludes it, =~ matches by regular expression, and !~ excludes by regular expression. So {job="api", status!="200"} selects series from the api job while dropping any with an HTTP 200 status. The explainer names each matcher and its operator in plain English.
More free, private observability tools.
The PromQL Explainer is part of the OpsCanopy observability cluster — translate queries with the LogQL ↔ PromQL Helper, or unit-test your Loki rules with AlertLint. Each runs entirely in your browser and never touches a server.
More in Observability
New to Kubernetes? Read the Kubernetes guide →
29 free tools, every one offline-capable — opscanopy.com works with no signup and nothing uploaded.
Same Prometheus pipeline: once a PromQL expression fires an alert, route it with the Alertmanager Route Tester over labels shaped by the Prometheus Relabel Tester. Working in Loki too? Pair this with AlertLint, or browse the full tools directory.
Not affiliated with or endorsed by the Prometheus project or the Cloud Native Computing Foundation. Prometheus is a trademark of The Linux Foundation.