ottyl/tickets/055-ottyl-reserved-params-in-dashboards.md

055 — Make ottyl_* reserved params usable in dashboard (PromQL) queries, not just filters

Summary

Three reserved params exist, all hardcoded in the filter compiler: ottyl_seq (ingest sequence number), ottyl_ts (ingest timestamp, supports relative/absolute values), and ottyl_fmt (auto-detected json/logfmt/none) — defined at src/engine.rs:773-775, 795, 806, 824, grammar comments at src/filter_parser.pest:7-9, docs at webapp/src/components/Docs.tsx:105-106, 375 ("reserved metric names present on every log line, so they're always filterable without declaring anything"). Alert conditions restrict to the same three plus regex()/json[field] (src/alerts.rs:3, 199-225).

These already work end-to-end for the filter/query bar syntax used by GET /api/logs, GET /api/timeline, and alert conditions — that part of "accessible parameters for queries" is true today. What's missing is dashboards: PromQL-style panel queries (src/promql.rs, evaluate_promql in src/engine.rs:1562-1601) have no special case for ottyl_* anywhere. A PromQL query resolves metric_name via bucket_values(index, &parsed.metric_name) (src/engine.rs, called from evaluate_promql), which only returns data for names backed by a DataValue::MetricDeclaration and bucket entries created through POST /api/metrics. ottyl_* values are computed line-locally at filter-compile time and never written into declared- metric buckets, so sum(ottyl_seq) or similar in a dashboard panel would silently return an empty series rather than real data.

Separately, ottyl_* never appear in GET /api/params (src/api.rs:281-287 → EngineQuery::ParamDeclarations → param_declarations_range, src/engine.rs:1340-1355), since that only lists explicit ParamDeclaration index entries and ottyl_* never create one. FilterBar.tsx (webapp/src/components/FilterBar.tsx:36-41) has no autocomplete/suggestion list at all today (plain text input), so there's nothing currently excluding them from UI suggestions either — but if param suggestions are ever added, this gap should be kept in mind.

Scope

• Add a special case in evaluate_promql/src/promql.rs (analogous to the filter compiler's handling at src/engine.rs:773-775) that synthesizes a virtual bucket series for ottyl_seq/ottyl_ts/ ottyl_fmt metric names from the ingested-log index, instead of requiring a MetricDeclaration. Decide and document in the PR how ottyl_fmt's categorical string values map onto a numeric time series (e.g. count-by-value, or reject it from PromQL numeric aggregation with a clear error, since ottyl_seq/ottyl_ts are naturally numeric but ottyl_fmt is not).
• Decide whether ottyl_* should appear in GET /api/params (or a parallel listing) so dashboard panel builders in the webapp can discover them without prior knowledge of the reserved names; if yes, extend param_declarations_range or add a small hardcoded merge at the API layer rather than forcing them into the index as real ParamDeclaration entries (they aren't user-declared and shouldn't be deletable via ticket 051's/052's params-removal paths).
• Update README.md/Docs.tsx to state whether ottyl_* is usable in dashboard queries, once implemented (or explicitly document it as filter-only, if the numeric/categorical mismatch above makes broad PromQL support impractical for ottyl_fmt).

Acceptance criteria

• A dashboard panel using a PromQL query over ottyl_seq or ottyl_ts (e.g. count(ottyl_seq) or a rate over ottyl_ts) returns real data from ingested logs, verified with a seeded fixture.
• The behavior for ottyl_fmt in a PromQL query is either implemented (with a stated value-to-series mapping) or explicitly rejected with a clear, documented error — not a silent empty result.
• GET /api/params behavior for ottyl_* is decided and documented; if included, they're clearly marked as reserved/non-deletable rather than indistinguishable from user-declared params.

Depends on

None (independent of the params-removal tickets, but note the non-deletable requirement above if ottyl_* end up listed alongside regular params).