ottyl/tickets/023-duration-param.md

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) 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 (durations are computed between successive counter events of the same metric).