Add histogram_quantile() PromQL query for percentiles

The PromQL layer only had a fixed-width histogram() (per-bucket
counts), with no way to ask for p50/p95/p99. Adds
histogram_quantile(p, metric[range]), interpolating over each
series's retained raw sample values (linear interpolation between
closest ranks) rather than building a separate pre-aggregated
bucketed-histogram representation — exact for the data actually kept.
An optional bracketed range narrows the computation to a trailing
window, mirroring rate()'s range selector.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TeyhRfMYjMditek6geDRoQ
This commit is contained in:
Hugh Kaznowski
2026-09-07 12:34:00 +01:00
co-authored by Claude Sonnet 5
parent 4a0fe92ce8
commit dbe2ea9961
5 changed files with 239 additions and 42 deletions
-41
View File
@@ -1,41 +0,0 @@
# 098 — No histogram_quantile()-style percentile query
## Summary
The PromQL layer's `histogram()` op buckets raw sample values by a
fixed width and returns per-bucket counts — it's unrelated to
Prometheus's classic histogram bucket/quantile model, and there's no
way to ask for p50/p95/p99 out of a metric today.
## Where
- `src/engine/promql.rs:9-16` — `AggOp::Histogram` is one of the six
supported ops.
- `src/engine/snapshot/mod.rs:1002` onward — `Histogram` evaluation:
buckets values by `bucket_width` into counts, grouped by
`by_labels`. This answers "how many samples fell in each bucket",
not "what value is the Nth percentile".
- No `histogram_quantile()` function or equivalent exists anywhere in
`promql.rs`'s parser (`parse_query`, `:261-324` recognizes only
`sum`, `avg`, `count`, `rate`, `histogram`, `gauge`).
- Depends on ticket 097 (gauge/counter semantics) for the broader
question of whether a metric needs a declared "this holds raw
observations for quantile purposes" flag, but quantile computation
itself doesn't strictly require that — it can operate on whatever
raw values are already stored in a metric's buckets.
## Scope
- Decide the quantile computation model: interpolate over the raw
stored sample values in a bucket/window (simplest, exact for the
data actually retained) vs. building a genuine bucketed-histogram
representation with configurable bucket boundaries (closer to
Prometheus's classic histograms, more work, needed only if retained
raw values are later dropped in favor of pre-aggregated buckets).
- Add a `histogram_quantile(p, metric[range])`-shaped PromQL construct
(or extend `histogram()` with a quantile argument) to
`promql.rs`'s parser and `AggOp`, plus an evaluator in
`snapshot/mod.rs` alongside the existing `Histogram` handling.
- Add dashboard/panel UI support for selecting a quantile once the
query-language side exists (`webapp/src/components/Dashboards.tsx`
or wherever panel query construction lives).