PCA: PromQL

PromQL

This domain is the most query-heavy: instant versus range vectors, selectors, functions, aggregation, binary operators, and histogram math. You must read a query and predict its result type, its labels, or its failure.

Core rules

• A selector like http_requests_total{job="api"} returns an instant vector; adding [5m] returns a range vector. Range vectors are required by rate(), increase(), and irate().
• Matchers are =, !=, =~, and !~; regex matchers are fully anchored. Use the metric name or __name__, not conflicting versions of both.
• Aggregations such as sum, avg, min, max, count, and topk group with by or without. Binary operators match on labels; use on/ignoring and group_left/group_right when necessary.
• rate() extrapolates a counter over the range and handles resets; irate() uses the last two samples and is jumpy. Never apply rate() to a gauge.
• histogram_quantile() needs the le label and bucket counters; summaries expose precomputed quantiles that cannot be aggregated across instances.

Worked example

sum by (code) (rate(http_requests_total{job="api"}[5m])) returns per-status-code requests per second. rate() converts the counter to a per-second slope, then sum by (code) adds across instances while preserving code. If the range contains only one sample, rate() returns no data, so a 5m range must be longer than the scrape interval. Reasoning: the range must contain at least two samples for a slope to exist.

Traps

Using a range shorter than two scrapes; aggregating away le before histogram_quantile; dividing by zero without a guard; confusing increase() with a raw delta; expecting offset and @ to mean the same thing.