promql

PromQL Query Patterns

Docs: https://prometheus.io/docs/prometheus/latest/querying/basics/

PromQL returns either an instant vector, a range vector, or a scalar.

Golden rule: rate() / increase() require a range vector ≥ 4× the scrape interval. 60s scrape → use [5m] minimum.

Prerequisites

• A Prometheus / Mimir / Grafana Cloud endpoint to query (/api/v1/query or via Grafana Explore)
• The PromQL pattern library in references/patterns.md

Common Workflows

1. Write + validate a query

# 0. Point at your Prometheus/Mimir. For Grafana Cloud, use the metrics endpoint
#    and add basic auth (-u "<metrics_user>:<token>") to each curl below.
PROM=http://localhost:9090   # or https://prometheus-prod-XX.grafana.net/api/prom
 

2. Common patterns to copy

Per-status request rate (aggregate AFTER rate):

p95 latency (must keep le in the inner aggregation):

Error rate with divide-by-zero guard:

Full library (recording rules, SLO burn-rate, offsets, cardinality hunt, native histograms): references/patterns.md.

3. Convert a slow dashboard query into a recording rule

Common bugs

• histogram_quantile returns NaN → forgot by (le) in the inner aggregation
• "No data" → check the metric exists (/api/v1/series) and the window ≥ 4× scrape interval
• Wrong rate magnitude → counter was aggregated before rate() (always rate() first)
• Query timeout → series count too high; use topk(...) + a recording rule + drop high-cardinality labels (see references/patterns.md)

Resources

• PromQL basics
• Operators
• Functions
• Grafana Mimir