Docs, ticks, working app

2026-09-05 15:05:39 +01:00
parent 41362aa3d8
commit 51e577f01e
41 changed files with 1039 additions and 683 deletions
@@ -0,0 +1,53 @@
+# 022 — Metrics rethink: counters as the primitive, histograms/gauges derived
+
+## Summary
+
+The wishlist calls for rethinking the metrics model: everything a metric declares
+should fundamentally be a **counter** (an occurrence at a point in time, optionally
+labeled). Histograms and gauges are not separate declaration kinds — they're
+*derived views* computed from counter data (bucketing counter events into
+histogram buckets; reducing counter series into a gauge-style "current value").
+This changes how `MetricDeclaration`/`BucketValue` are modeled and how the
+already-shipped PromQL-style query support (`promql.rs`) evaluates
+`rate()`/`sum()`/histogram/gauge-shaped queries.
+
+## Scope
+
+- Re-express metric declarations as counter declarations: a match increments a
+  counter for the resolved label set at the matched timestamp. This is close to
+  today's `BucketValue{values: Vec<(Sequence, Timestamp, MetricPrimitive)>}` — audit
+  whether the existing bucket representation already is this, or whether captured
+  non-counter values (e.g. a captured `Number` used as a gauge reading today) need
+  to be reinterpreted as counter increments plus a separately-derived gauge.
+  Document the resulting semantics clearly since this is a model change to code
+  that already exists and has callers (`engine.rs`, `promql.rs`, `Metrics.tsx`,
+  `Dashboards.tsx`).
+- Histogram derivation: given a counter's events over a time range, bucket them
+  (fixed-width or user-specified boundaries) and expose bucket counts — likely as
+  a new PromQL-evaluable form (e.g. `histogram(metric_name[param])`) or a query
+  option, consumed the same way existing series are.
+- Gauge derivation: given a counter's events, derive a "last value" / "value at
+  time T" series from the most recent matching counter event — likely as another
+  derived query form (e.g. `gauge(metric_name[param])`), rather than a distinct
+  declaration/storage kind.
+- Update `promql.rs`'s evaluator to support these derived forms without breaking
+  existing raw counter queries.
+- Update `Metrics.tsx`'s declaration form/help text and `Dashboards.tsx`'s panel
+  config if the query surface changes.
+
+## Acceptance criteria
+
+- A declared metric behaves as a counter: each match is an increment/event, not an
+  arbitrary overwritten value.
+- A histogram-derived query against a counter with several distinct captured
+  values buckets them correctly across a seeded fixture.
+- A gauge-derived query against a counter returns the most-recent value at a given
+  point in the selected time range.
+- Existing raw counter queries (sum/rate over a plain counter, as today) continue
+  to work unchanged.
+
+## Depends on
+
+None — this is a rework of the already-shipped metric/bucket/PromQL code, not new
+foundational work. [023](023-duration-param.md), [025](025-default-dashboard-seed.md)
+build on the resulting model.