[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). |
1---2name: promql3description: 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.4---56# [H1][PROMQL]7>**Dictum:** *Query generation follows metric type, then pattern, then optimization.*89<br>1011Generate 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.1213**Tasks:**141. Gather goal, use case, metric context via **AskUserQuestion** (skip if provided).152. Identify metric names, types, labels -- confirm with user.163. Read relevant reference: `references/promql_functions.md`, `references/promql_patterns.md`, `references/best_practices.md`.174. Present plain-English plan; confirm via **AskUserQuestion**.185. Generate query citing applicable pattern.196. Validate against `references/validation.md` rules; fix and re-validate until all checks pass.207. Deliver: final query + explanation + usage context + customization notes.2122---23## [1][METRIC_IDENTIFICATION]24>**Dictum:** *Metric type determines function selection.*2526<br>2728| [INDEX] | [SUFFIX] | [TYPE] | [FUNCTIONS] |29| :-----: | ------------------------------- | ------------------ | ------------------------------------------------------------ |30| [1] | **`_total`** | Counter. | `rate()`, `irate()`, `increase()`. |31| [2] | **`_bucket`, `_sum`, `_count`** | Classic Histogram. | `histogram_quantile()`, `rate()`. |32| [3] | **(none, opaque)** | Native Histogram. | `histogram_quantile/count/sum/avg/fraction/stddev/stdvar()`. |33| [4] | **(unit suffix)** | Gauge. | direct, `*_over_time()`. |3435**Guidance:**36- Range >= 4x scrape interval. Label filters: exact `=`, negative `!=`, regex `=~`.37- Aggregation: `sum by (labels)` to keep, `sum without (labels)` to drop.38- Native histograms eliminate `le` label and `_bucket` suffix -- single opaque series per histogram.3940---41## [2][VERSION_MATRIX]42>**Dictum:** *Version awareness prevents deprecated patterns.*4344<br>4546| [INDEX] | [VERSION] | [RELEASE] | [KEY_CHANGES] |47| :-----: | ----------- | --------- | -------------------------------------------------------------------------------- |48| [1] | **3.0** | Nov 2024 | UTF-8 names, `holt_winters` renamed to `double_exponential_smoothing`, `info()`. |49| [2] | **3.5 LTS** | Jul 2025 | `mad_over_time`, `ts_of_min/max/last_over_time`, `sort_by_label` (experimental). |50| [3] | **3.6** | Sep 2025 | `step()`, duration expressions (`promql-duration-expr` flag). |51| [4] | **3.7** | Oct 2025 | `first_over_time`, anchored+smoothed rate (`promql-extended-range-selectors`). |52| [5] | **3.8** | Nov 2025 | Native histograms **stable** (`scrape_native_histograms` config). |53| [6] | **3.9** | Jan 2026 | `native-histogram` flag is **no-op**; `/api/v1/features` endpoint. |54| [7] | **3.10** | Feb 2026 | Maintenance release; stability fixes only. |5556**Guidance:**57- Activate native histograms: `scrape_native_histograms: true` in scrape config (not a feature flag).58- Three experimental gates remain: `promql-experimental-functions`, `promql-duration-expr`, `promql-extended-range-selectors`.5960---61## [3][NATIVE_HISTOGRAMS]62>**Dictum:** *Native histograms replace classic for all new instrumentation.*6364<br>6566No `_bucket` suffix or `le` label. Reduces series cardinality 10-100x. NHCB (3.4+): classic-to-native conversion via `convert_classic_histograms_to_nhcb: true`.6768| [INDEX] | [FUNCTION] | [PURPOSE] |69| :-----: | ------------------------------------------------- | ----------------------------- |70| [1] | **`histogram_quantile(phi, v)`** | Percentile (no `le` needed). |71| [2] | **`histogram_avg(v)`** | Average (replaces sum/count). |72| [3] | **`histogram_fraction(lo, hi, v)`** | Fraction between bounds. |73| [4] | **`histogram_stddev(v)` / `histogram_stdvar(v)`** | Estimated stddev / variance. |74| [5] | **`histogram_count(v)` / `histogram_sum(v)`** | Observation count / sum. |7576```promql77# Classic: histogram_quantile(0.95, sum by (job, le) (rate(metric_bucket[5m])))78# Native: histogram_quantile(0.95, sum by (job) (rate(metric[5m])))79```8081**Best-Practices:**82- Prefer `histogram_avg()` over manual `_sum/_count` division -- single function, single series.83- Use `histogram_fraction(0, 0.2, rate(m[5m]))` for latency SLOs -- precise without bucket interpolation.84- `rate()`, `increase()`, `delta()` on native histograms produce gauge histograms (3.9+).8586---87## [4][EXPERIMENTAL_FUNCTIONS]88>**Dictum:** *Experimental functions expand analysis under explicit feature flags.*8990<br>9192| [INDEX] | [FUNCTION] | [FLAG] | [SINCE] | [PURPOSE] |93| :-----: | ---------------------------------------------- | ------------------------------- | ------- | --------------------------------------- |94| [1] | **`info(v [, selector])`** | `promql-experimental-functions` | 3.0+ | Automatic metadata enrichment. |95| [2] | **`double_exponential_smoothing(v[r],sf,tf)`** | `promql-experimental-functions` | 3.0+ | Smoothed gauge (replaced holt_winters). |96| [3] | **`mad_over_time(v[r])`** | `promql-experimental-functions` | 3.5+ | MAD-based anomaly detection. |97| [4] | **`first_over_time(v[r])`** | `promql-experimental-functions` | 3.7+ | First (oldest) value in range. |98| [5] | **`limitk(k,v)` / `limit_ratio(r,v)`** | `promql-experimental-functions` | 3.0+ | Deterministic series sampling. |99| [6] | **`step()`** | `promql-duration-expr` | 3.6+ | Current evaluation step size. |100101**Guidance:**102- `info()` replaces manual `* on (...) group_left (...)` for metadata joins.103- `mad_over_time` enables z-score anomaly detection: `m > avg_over_time(m[1h]) + 3 * mad_over_time(m[1h])`.104- `limitk`/`limit_ratio` use deterministic hash-based sampling -- same series across evaluations.105106---107## [5][LOOKUP_STRATEGY]108>**Dictum:** *Lookup strategy prioritizes authoritative sources.*109110<br>111112**context7 MCP** (preferred): resolve "prometheus" -> get-library-docs with topic.113**WebSearch** fallback: `"Prometheus PromQL [topic] documentation examples"`.114115---116## [6][RESOURCES]117>**Dictum:** *Reference files provide detailed function, pattern, optimization, and validation guidance.*118119<br>120121| [INDEX] | [FILE] | [WHEN_TO_READ] |122| :-----: | ------------------------------------ | ---------------------------------------------------------- |123| [1] | **`references/promql_functions.md`** | Function behavior, metric types, decision tree. |124| [2] | **`references/promql_patterns.md`** | RED/USE/SLO/alerting/join/efficiency patterns. |125| [3] | **`references/best_practices.md`** | Optimization, quick reference, pre-deploy checklist. |126| [4] | **`references/validation.md`** | Validation rules, 33 anti-patterns, output format, limits. |127| [5] | **`examples/alerting_rules.yaml`** | Production alerting rule templates. |128| [6] | **`examples/recording_rules.yaml`** | Pre-computed metric rule templates (classic + native). |
bsamiee