| name | promql |
| description | Generates and validates PromQL queries with RED/USE/SLO patterns, native histograms, recording rules, and alerting expressions. Use when creating, reviewing, or validating PromQL queries, recording rules, or alerting expressions. |
[H1][PROMQL]
Dictum: Query generation follows metric type, then pattern, then optimization.
Generate and validate PromQL for Prometheus 3.8-3.10 (native histograms stable, feature flag no-op since 3.9). Cross-references: observability-stack for deployment.
Tasks:
- Gather goal, use case, metric context via AskUserQuestion (skip if provided).
- Identify metric names, types, labels -- confirm with user.
- Read relevant reference:
references/promql_functions.md, references/promql_patterns.md, references/best_practices.md.
- Present plain-English plan; confirm via AskUserQuestion.
- Generate query citing applicable pattern.
- Validate against
references/validation.md rules; fix and re-validate until all checks pass.
- Deliver: final query + explanation + usage context + customization notes.
[1][METRIC_IDENTIFICATION]
Dictum: Metric type determines function selection.
| [INDEX] | [SUFFIX] | [TYPE] | [FUNCTIONS] |
|---|
| [1] | _total | Counter. | rate(), irate(), increase(). |
| [2] | _bucket, _sum, _count | Classic Histogram. | histogram_quantile(), rate(). |
| [3] | (none, opaque) | Native Histogram. | histogram_quantile/count/sum/avg/fraction/stddev/stdvar(). |
| [4] | (unit suffix) | Gauge. | direct, *_over_time(). |
Guidance:
- Range >= 4x scrape interval. Label filters: exact
=, negative !=, regex =~.
- Aggregation:
sum by (labels) to keep, sum without (labels) to drop.
- Native histograms eliminate
le label and _bucket suffix -- single opaque series per histogram.
[2][VERSION_MATRIX]
Dictum: Version awareness prevents deprecated patterns.
| [INDEX] | [VERSION] | [RELEASE] | [KEY_CHANGES] |
|---|
| [1] | 3.0 | Nov 2024 | UTF-8 names, holt_winters renamed to double_exponential_smoothing, info(). |
| [2] | 3.5 LTS | Jul 2025 | mad_over_time, ts_of_min/max/last_over_time, sort_by_label (experimental). |
| [3] | 3.6 | Sep 2025 | step(), duration expressions (promql-duration-expr flag). |
| [4] | 3.7 | Oct 2025 | first_over_time, anchored+smoothed rate (promql-extended-range-selectors). |
| [5] | 3.8 | Nov 2025 | Native histograms stable (scrape_native_histograms config). |
| [6] | 3.9 | Jan 2026 | native-histogram flag is no-op; /api/v1/features endpoint. |
| [7] | 3.10 | Feb 2026 | Maintenance release; stability fixes only. |
Guidance:
- Activate native histograms:
scrape_native_histograms: true in scrape config (not a feature flag).
- Three experimental gates remain:
promql-experimental-functions, promql-duration-expr, promql-extended-range-selectors.
[3][NATIVE_HISTOGRAMS]
Dictum: Native histograms replace classic for all new instrumentation.
No _bucket suffix or le label. Reduces series cardinality 10-100x. NHCB (3.4+): classic-to-native conversion via convert_classic_histograms_to_nhcb: true.
| [INDEX] | [FUNCTION] | [PURPOSE] |
|---|
| [1] | histogram_quantile(phi, v) | Percentile (no le needed). |
| [2] | histogram_avg(v) | Average (replaces sum/count). |
| [3] | histogram_fraction(lo, hi, v) | Fraction between bounds. |
| [4] | histogram_stddev(v) / histogram_stdvar(v) | Estimated stddev / variance. |
| [5] | histogram_count(v) / histogram_sum(v) | Observation count / sum. |
# Classic: histogram_quantile(0.95, sum by (job, le) (rate(metric_bucket[5m])))
# Native: histogram_quantile(0.95, sum by (job) (rate(metric[5m])))
Best-Practices:
- Prefer
histogram_avg() over manual _sum/_count division -- single function, single series.
- Use
histogram_fraction(0, 0.2, rate(m[5m])) for latency SLOs -- precise without bucket interpolation.
rate(), increase(), delta() on native histograms produce gauge histograms (3.9+).
[4][EXPERIMENTAL_FUNCTIONS]
Dictum: Experimental functions expand analysis under explicit feature flags.
| [INDEX] | [FUNCTION] | [FLAG] | [SINCE] | [PURPOSE] |
|---|
| [1] | info(v [, selector]) | promql-experimental-functions | 3.0+ | Automatic metadata enrichment. |
| [2] | double_exponential_smoothing(v[r],sf,tf) | promql-experimental-functions | 3.0+ | Smoothed gauge (replaced holt_winters). |
| [3] | mad_over_time(v[r]) | promql-experimental-functions | 3.5+ | MAD-based anomaly detection. |
| [4] | first_over_time(v[r]) | promql-experimental-functions | 3.7+ | First (oldest) value in range. |
| [5] | limitk(k,v) / limit_ratio(r,v) | promql-experimental-functions | 3.0+ | Deterministic series sampling. |
| [6] | step() | promql-duration-expr | 3.6+ | Current evaluation step size. |
Guidance:
info() replaces manual * on (...) group_left (...) for metadata joins.mad_over_time enables z-score anomaly detection: m > avg_over_time(m[1h]) + 3 * mad_over_time(m[1h]).limitk/limit_ratio use deterministic hash-based sampling -- same series across evaluations.
[5][LOOKUP_STRATEGY]
Dictum: Lookup strategy prioritizes authoritative sources.
context7 MCP (preferred): resolve "prometheus" -> get-library-docs with topic.
WebSearch fallback: "Prometheus PromQL [topic] documentation examples".
[6][RESOURCES]
Dictum: Reference files provide detailed function, pattern, optimization, and validation guidance.
| [INDEX] | [FILE] | [WHEN_TO_READ] |
|---|
| [1] | references/promql_functions.md | Function behavior, metric types, decision tree. |
| [2] | references/promql_patterns.md | RED/USE/SLO/alerting/join/efficiency patterns. |
| [3] | references/best_practices.md | Optimization, quick reference, pre-deploy checklist. |
| [4] | references/validation.md | Validation rules, 33 anti-patterns, output format, limits. |
| [5] | examples/alerting_rules.yaml | Production alerting rule templates. |
| [6] | examples/recording_rules.yaml | Pre-computed metric rule templates (classic + native). |
