PromQL Linter and Explainer

Label matcher regexes are anchored, exactly as in relabel_config

`{job=~"api"}` matches the job called `api` and nothing else. It does not match `api-server`. Prometheus wraps every matcher regex as `^(?:...)$`, the same rule that makes relabeling surprising, and the symptom is the same: the query returns no series and everything looks correct. Write `.*api.*` for a substring match. If you meant an exact match, use `=` instead, which is faster because it can use the index directly.

{job=~"api"}        matches only "api"
{job=~".*api.*"}    matches "api-server"
{job="api"}         the same as the first, and faster
{job=~""}           matches series with NO job label at all

rate() goes inside the aggregation, never outside

Counter resets are per series. `sum(rate(x[5m]))` computes each series' rate, correcting its own resets, and then adds them. `rate(sum(x)[5m:])` adds the counters first, so a single process restarting drags the sum down and the reset correction cannot tell that from a real decrease. The second form parses, runs, and returns numbers that are wrong precisely when a deploy happens, which is when you are looking at the graph.

sum(rate(http_requests_total[5m]))      correct
sum by (job) (rate(http_requests_total[5m]))

rate(sum(http_requests_total)[5m:])     wrong, and it runs

A range needs to hold at least two samples, and really four

rate() computes a slope, so it needs two points inside the window or it returns nothing at all. At a 15 second scrape interval, `[15s]` holds one sample and the graph is empty, which sends people to check the exporter. Two or three samples is worse in a way: it computes, and then a single missed scrape empties the window, so the line flickers and reads as an intermittent target. Four times the scrape interval is the usual floor.

histogram_quantile needs a rate, and it needs le

Bucket series are cumulative counters that only increase since process start. `histogram_quantile(0.99, http_request_duration_seconds_bucket)` therefore describes every request the process has ever served: it barely moves, and during an incident it looks reassuringly stable. Wrap the buckets in a rate. The other half is that `le` is the bucket boundary and the function cannot work without it, so an aggregation must be `sum by (le)` and not `sum by (job)`.

histogram_quantile(0.99,
  sum by (le) (rate(http_request_duration_seconds_bucket[5m])))

A comparison filters rather than returning true or false

`up > 5` does not give you ones and zeros. It drops every series that does not satisfy the comparison. For an alert that is exactly right, because an empty result is no alert. On a graph it means a line vanishes rather than going to zero, which reads as missing data. The `bool` modifier gives you 1 and 0 instead.

What this cannot see

It has no metrics and no metadata, so it cannot know whether a name is a counter or a gauge. Where that matters it says so: a rate() over a name that does not end in `_total` is reported as a naming hint rather than as a verdict, because a gauge called `queue_depth_total` would defeat any rule built on the convention. It also does not evaluate anything, so it cannot tell you a query returns no data because the series does not exist. The scrape interval used for the range checks is 15 seconds, which is the Prometheus default; if yours differs, read those two findings against your own number.