The PromQL Patterns Checklist Every SRE Should Know

Twelve PromQL patterns that cover 80% of production queries. The checklist with examples and what each catches.

Rate and increase

PromQL is Prometheus's query language. The expressive power is significant; the patterns for common queries are well-established. The patterns checklist captures the foundational queries every team should master; advanced queries build on these.

What rate and increase provide:

• rate() over a window for per-second rates.: rate(metric[5m]) produces the per-second rate of a counter over the last 5 minutes. The function is the foundation of most counter queries.
• Baseline pattern; everything else builds on it.: rate() is the building block. Histograms use it; quantiles use it; alerts use it. Mastering rate() is the foundation for PromQL fluency.
• increase() for total over a window.: increase(metric[5m]) produces the total increase of the counter over 5 minutes. Useful when the team wants total volume, not rate.
• Useful for counters.: increase() works correctly for counters. The function handles counter resets; the result is the total increase even if the counter restarted.
• Misleading for gauges.: increase() does not work meaningfully for gauges. Gauges go up and down; increase() is not the right primitive. Use delta() or other gauge-appropriate functions instead.

Rate and increase are the foundation. Most team queries start with these primitives.

Histogram quantiles

Histogram quantiles compute percentiles from histogram metrics. The pattern is essential for latency monitoring; understanding it produces correct queries.

• histogram_quantile(0.99, rate(metric_bucket[5m])).: The standard p99 query. The histogram_quantile function operates on the rate of the bucket counters; the result is the p99 latency.
• The standard p99 query.: The pattern is universal for Prometheus latency monitoring. Most teams' latency dashboards use this exact pattern.
• Watch for low-cardinality buckets that miss your tail.: Histograms have predefined buckets. If the buckets are too coarse, p99 may always land on a bucket boundary; the actual p99 is somewhere within the bucket but the query cannot tell you where.
• Re-bucket if p99 always rounds up.: When p99 always equals a bucket boundary, the histogram needs more buckets in that range. The application's histogram configuration is updated; the new buckets produce useful percentiles.
• Bucket choice depends on workload.: Different workloads have different latency distributions; bucket boundaries should be chosen for the workload. The default bucket sets are starting points; tuning is part of the discipline.

Histogram quantiles are essential for latency monitoring. The pattern is well-understood; the bucket configuration is the workload-specific tuning.

Predict and threshold

Prediction and threshold matching are higher-level patterns. They combine the foundational primitives into queries that drive alerts and capacity planning.

• predict_linear() for capacity forecasting.: predict_linear() projects a metric forward based on its recent rate. "Will the disk fill in 4 hours?" becomes a specific PromQL expression.
• "Will the disk fill in 4 hours?": The query: predict_linear(node_filesystem_free_bytes[1h], 4 * 3600) less than 0. The expression projects the current rate forward 4 hours; if the projection is below 0, the disk fills.
• Threshold matching with comparison operators.: PromQL supports comparison: metric over 80 returns the time series only when the metric exceeds 80. The pattern is foundational for alert rules.
• Foundational for alert rules.: Most alert rules use the comparison pattern. The metric is computed; compared to a threshold; the rule fires when the comparison is true.
• Combine with for clause.: Alert rules use "for" to require sustained breach. metric over 80 for 10m only fires when the breach is sustained 10 minutes. The combination produces stable alerts.

PromQL patterns checklist is one of those foundational skills that pays off across the team's observability lifetime. Nova AI Ops integrates with Prometheus and other PromQL backends, surfaces query patterns, and helps teams adopt the patterns that produce useful alerts and dashboards.