78 lines
4.1 KiB
Markdown
78 lines
4.1 KiB
Markdown
# 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).
|