Skip to content

feat(query): why/show agent query layer - #28

Closed
kitlangton wants to merge 16 commits into
rust/enginefrom
rust/query
Closed

kitlangton wants to merge 16 commits into
rust/enginefrom
rust/query

Conversation

@kitlangton

Copy link
Copy Markdown
Owner

What it does

Adds motel-query, the agent-facing read layer over the storage engine from #27. It answers two questions with plain-text reports that end in next: lines (the exact commands to run next):

  • why [service] [--since …]: what went wrong. Ranked findings: crashes, new or spiking error groups, failed runs and tests, slow spans against their own baseline.
  • show <id>: everything about one thing. Accepts a trace id, span id, session or request id, error group g:<hash>, event e:…, or run run:<n>|last.

Plus sql / schema as the escape hatch. The full contract is in docs/agent-api.md. Nothing is wired into a binary yet; the CLI, HTTP and MCP surfaces come in a later PR. Stacked on #27.

How it works

  1. Error groups fingerprint the first message line (numbers, hex ids, UUIDs, paths, quoted strings masked; :line:col dropped). One input rule is used by every surface, so a g: id printed by why or show always resolves.
  2. NEW means the group never appeared in the prior 7 days. If the baseline scan is cut short by its cap or deadline, the finding says NEW? and JSON sets baseline_complete: false.
  3. Crashes and failed runs are read from the evidence file first, so a service flooding error logs can't push them out of the answer.
  4. Reads pick day files by recorded event-time range and merge newest first, correct for late events. Every list has row, byte and time caps; when one is hit, searched: says so instead of reporting "nothing found".
  5. sql runs over a read-only events view across the attached files. Host, version and pid are columns on events; the per-file resources table is not exposed, because joining it across files multiplies rows.

Risk

  • New crate plus a small read-only addition to motel-store (Reader::query_file, column helpers, the sql view columns). No writer changes. The TypeScript package is untouched.
  • Error-group fingerprints are heuristic. Ids that the masking misses split a group; distinct groups are capped at 5,000 per call and the remainder is counted.

Proof

  • cargo test -p motel-query: 20 unit, 5 golden-output and 23 integration tests. They include regressions for each review finding: crashes surviving the error-scan cap, show <span> with no trace, group ids agreeing across why/show <trace>/show <event> (object-valued exception.message, blank and 600-char bodies), run fallbacks, centred event context, newest samples across files, deadline reporting, and shell-safe next: lines.
  • cargo test -p motel-store and cargo clippy --workspace --all-targets -- -D warnings: clean.
  • Latency, 1M rows over 8 days, 50 iterations each (cargo run --release -p motel-query --example bench_query, on a Mac mini):
p50 p95
why (24 h, all services) 88 ms 90 ms
why api 20 ms 21 ms
why --since 7d 90 ms 101 ms
show <trace> 1.3 ms 1.6 ms

Add Reader::query_file (trusted read-only SQL on one catalog file with the
progress deadline), EVENT_COLUMNS + event_row_from_sql, Reader::now_ns,
is_direct, default_deadline, and Reader::sql_table, which keeps the
statement's column order. Reader::sql is now built on sql_table.
Parses --since forms (durations, HH:MM, RFC 3339, dates, git refs, run:last),
formats times and durations for agent text, classifies show ids, and computes
error-group fingerprints with g: ids.
Ranks crashes, NEW error groups, failed runs, then recurring groups. NEW means
absent from the 7 days before the window start, checked with a bounded ix_err
scan per service. Empty default windows walk back to 14 days; empty answers say
whether the store is empty, the service is unknown (with near names) or quiet.
…sions

Picks the view from the id's shape: trace tree with interleaved logs, a span
focused in its trace, an event with ±30 s context (a crash adds top frames and
same-pid breadcrumbs), an error group with samples and traces, a run with failed
tests and slow spans against their 7-day p50, or a session/request timeline.
Output is capped at 200 lines unless full.
Wraps the store's sandboxed SQL with aligned text output and appends the
schema reference to every SQL error. schema lists columns with meanings, kinds,
services seen in 7 days, the attr() helper and five example queries.
The fixture writes day by day under a manual clock: a crash with breadcrumbs,
a NEW group after a fake commit, a recurring group, a failed run with slow spans
and failed tests, late arrivals and a session spanning three traces.
Writes N rows over D day files under a manual clock in the motel-bench fixture
shape, with ~200 recurring error groups and a few that first appear on the last
day, then reports first-call, p50, p95 and max for why and show <trace>.
…ad of a cross-file resources view

Resource ids are per file, so a union of every file's resources table multiplied
joins across days. Each events branch now joins its own file's resources, and a
temp view shadows resources with an error that points at the new columns.
Group ids came from different messages in SQL and Rust (JSONB attrs, blank bodies,
long bodies), so ids from show did not resolve. group_message is now the single
rule: the first 512 body characters unless blank, else the first present message
attribute rendered as JSON text. Paths also drop :line:col before masking.
Durations past 3,650 days no longer overflow. A value that is both a duration and a
7+ hex-digit abbreviated hash (0000100d) resolves as a git ref when it resolves in
the caller's repo, else as the duration.
…in schema

motel sql suggestions are double-quoted only when nothing in them is special to the
shell, else single-quoted with '\'' escaping. schema lists host, version and pid
as events columns, explains there is no resources table, and its pid example uses
those columns.
…t short

- Error scans merge per-service ix_err ranges newest first instead of sorting, skip
  crash/run/test kinds in SQL, and take their bounds as one ErrScan.
- Crashes and runs are read from evidence on their own (evidence_errors).
- The SQL message projection matches fingerprint::group_message.
- Lists are bounded by rows and bytes (collect_rows_bounded); attrs stay raw JSON.
- newest_rows applies the cross-file merge rule for events_between, by_key and p50.
- A read stopped by the call deadline sets searched.truncated and adds a note.
- Probes for a service's or the store's last event no longer count as searched days.
… window

Crashes and failed runs no longer depend on the error scan cap. The baseline is one
shared, budgeted scan; when it stops early, unconfirmed groups read NEW? and the
answer sets baseline_complete=false. Distinct groups are capped at 5,000 (the rest
counted), findings are built only for the first --limit, and --since later than
--until is BadTime.
- A span whose trace is empty or missing is shown alone, with a note.
- run views drop the root span that mirrors the run and fall back from the trace to
  the session's spans, then to every span during the run.
- Event context is the 30 nearest events on each side, centered on the event.
- Crashes, runs and failed tests have no g: id; group samples and traces are the
  newest across every file.
Covers group ids agreeing across why/show, crashes and runs past the error cap,
incomplete baselines, group caps, a spent deadline, probes not counted as searched,
the cross-file merge rule in by_key and p50, orphan spans, run fallbacks, centered
context, newest group samples, bad windows and shell quoting.
@kitlangton
kitlangton deleted the branch rust/engine October 26, 2026 01:35
@kitlangton

Copy link
Copy Markdown
Owner Author

Closing: this work is moving elsewhere for now. Thanks!

@kitlangton kitlangton closed this Oct 26, 2026
@kitlangton
kitlangton deleted the rust/query branch October 26, 2026 01:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant