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,37 @@
+# 023 — Duration-type parameter
+
+## Summary
+
+Support a `Duration` parameter kind: its value is the time elapsed since the
+previous trigger of the *same* metric with the *same* labels/params, measured
+using whichever timestamp field the user has configured (ingestion time by
+default, or a param-derived timestamp).
+
+## Scope
+
+- New `MetricPrimitive`/param-kind variant for durations (e.g. milliseconds as an
+  `i64`, consistent with how `Timestamp` is already stored).
+- Derivation rule: for a metric match with a given label set, look up that same
+  label set's previous counter event ([022](022-metrics-counters-rethink.md)) and
+  compute `this_event_time - previous_event_time` using the configured time
+  source (ingestion timestamp, or a declared timestamp param per the README's
+  "deriving a timestamp different from the ingested timestamp" note).
+- First occurrence of a given label set has no previous event — define and
+  document the behavior (e.g. omit the duration value, or emit `null`/zero;
+  omitting is likely correct so it doesn't pollute histograms with a bogus zero).
+- Expose duration values the same way other derived/counter data is queried
+  (bucket lookup, PromQL, Metrics UI) so it composes with existing dashboards.
+
+## Acceptance criteria
+
+- Two log lines matching the same metric+labels, seconds apart, produce a
+  duration value equal to that elapsed time on the second occurrence.
+- The first occurrence of a given label set produces no duration value (not a
+  zero or garbage value).
+- Duration values are queryable via the same bucket/PromQL surface as other
+  metric data.
+
+## Depends on
+
+- [022 — Metrics rethink](022-metrics-counters-rethink.md) (durations are computed
+  between successive counter events of the same metric).