[H1][PROMQL-GENERATOR]
Dictum: Query generation follows metric type, then pattern, then optimization.
Generate PromQL for Prometheus 3.8-3.10 (native histograms stable, feature flag no-op since 3.9). Cross-references: promql-validator for validation, 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.
- Invoke promql-validator skill; 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, and optimization 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, anti-patterns, pre-deploy checklist. |
| [4] |
examples/alerting_rules.yaml |
Production alerting rule templates. |
| [5] |
examples/recording_rules.yaml |
Pre-computed metric rule templates (classic + native). |
1---2name: promql-generator3description: Generates PromQL queries with RED/USE/SLO patterns, native histograms, recording rules, and alerting expressions. Use when creating new queries from requirements; excludes validation (use promql-validator).4---5
6# [H1][PROMQL-GENERATOR]
7>**Dictum:** *Query generation follows metric type, then pattern, then optimization.*
8
9<br>
10
11Generate PromQL for Prometheus 3.8-3.10 (native histograms stable, feature flag no-op since 3.9). Cross-references: **promql-validator** for validation, **observability-stack** for deployment.
12
13**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. Invoke **promql-validator** skill; fix and re-validate until all checks pass.
207. Deliver: final query + explanation + usage context + customization notes.
21
22---
23## [1][METRIC_IDENTIFICATION]
24>**Dictum:** *Metric type determines function selection.*
25
26<br>
27
28| [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()`. |
34
35**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.
39
40---
41## [2][VERSION_MATRIX]
42>**Dictum:** *Version awareness prevents deprecated patterns.*
43
44<br>
45
46| [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. |
55
56**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`.
59
60---
61## [3][NATIVE_HISTOGRAMS]
62>**Dictum:** *Native histograms replace classic for all new instrumentation.*
63
64<br>
65
66No `_bucket` suffix or `le` label. Reduces series cardinality 10-100x. NHCB (3.4+): classic-to-native conversion via `convert_classic_histograms_to_nhcb: true`.
67
68| [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. |
75
76```promql
77# 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```
80
81**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+).
85
86---
87## [4][EXPERIMENTAL_FUNCTIONS]
88>**Dictum:** *Experimental functions expand analysis under explicit feature flags.*
89
90<br>
91
92| [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. |
100
101**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.
105
106---
107## [5][LOOKUP_STRATEGY]
108>**Dictum:** *Lookup strategy prioritizes authoritative sources.*
109
110<br>
111
112**context7 MCP** (preferred): resolve "prometheus" -> get-library-docs with topic.
113**WebSearch** fallback: `"Prometheus PromQL [topic] documentation examples"`.
114
115---
116## [6][RESOURCES]
117>**Dictum:** *Reference files provide detailed function, pattern, and optimization guidance.*
118
119<br>
120
121| [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, anti-patterns, pre-deploy checklist. |
126| [4] | **`examples/alerting_rules.yaml`** | Production alerting rule templates. |
127| [5] | **`examples/recording_rules.yaml`** | Pre-computed metric rule templates (classic + native). |
majiayu000