PromQL Query Standards

This rule applies to files matching the patterns above.

# PromQL Query Standards

## Rule
All PromQL queries in Grafana dashboards and alerts MUST follow these patterns for correctness, performance, and consistency.

## Requirements

### Always Use rate() on Counters
```promql
# GOOD: rate converts counter to per-second rate
rate(http_requests_total[5m])

# BAD: raw counter (ever-increasing line)
http_requests_total
```

### Filter Labels Early
```promql
# GOOD: filter before aggregation
sum by (status_code) (rate(http_requests_total{service="api", environment="production"}[5m]))

# BAD: filter after aggregation (wastes resources)
sum by (status_code) (rate(http_requests_total[5m]))  # Then filter in Grafana UI
```

### Use Consistent Range Vectors
| Context | Range | Reason |
|---------|-------|--------|
| Dashboard panels | [5m] | Smooth, readable graphs |
| Alert rules | [1m] or [2m] | Faster detection |
| Recording rules | [5m] | Consistent with dashboards |

### Histogram Quantile Pattern
```promql
# CORRECT: rate inside histogram_quantile, sum by (le)
histogram_quantile(0.95,
  sum by (le) (rate(http_request_duration_seconds_bucket[5m]))
)

# INCORRECT: missing rate (wrong values)
histogram_quantile(0.95,
  sum by (le) (http_request_duration_seconds_bucket)
)
```

### Recording Rules for Complex Queries
```yaml
# When a query is used in multiple dashboards/alerts, create a recording rule
groups:
  - name: service-sli
    interval: 30s
    rules:
      - record: service:http_error_rate:ratio_rate5m
        expr: |
          sum by (service) (rate(http_requests_total{status_code=~"5.."}[5m]))
          /
          sum by (service) (rate(http_requests_total[5m]))
```

## Examples

### Good
- rate() on all counters with appropriate range vectors
- Labels filtered in the query, not the UI
- histogram_quantile with rate() and sum by (le)
- Recording rules for frequently used complex queries

### Bad
- Raw counters displayed without rate()
- irate() in dashboard panels (too volatile)
- Missing sum by (le) in histogram quantiles
- Same complex query copy-pasted across 10 dashboards

## Enforcement
Review PromQL in dashboard JSON PRs.
Use recording rules to simplify and standardize common queries.