Crate facett_trace 

facett-trace — a structured event trace: the machine-readable sibling of a free-form action log.

An action log is a human free-form trail (tab=Bench, reload … → 3 release(s)). This is its typed counterpart: every instrumented operation emits its INPUT parameters and its OUTPUT data as real JSON payloads, so an external agent (or a headless test matrix) can read back exactly the data the UI rendered — the bubble table, the bench rows, the server response — not a summary and not a screenshot.

Adopted verbatim from nornir’s src/viz/trace.rs; it was already zero-coupling (generic over serde::Serialize). The only change is the output-path env var: $FACETT_TRACE (default /tmp/facett_trace.jsonl), truncated on launch.

One JSON object per line (JSONL):

{"seq":7,"ts_ms":1733961825678,"stamp":"01:23:45.678",
 "span":"knowledge.scan","phase":"in","data":{"workspace_root":"…","repos":["njord"]}}
{"seq":8,...,"span":"knowledge.scan.repo","phase":"end","data":{"repo":"njord","symbols":642,…}}
{"seq":9,...,"span":"knowledge.scan","phase":"out","data":{"repos_ok":1,"repos_total":1,"ms":83}}
{"seq":10,...,"span":"knowledge.render","phase":"end","data":{"bubbles":[{"repo":"njord",…}]}}

The contract

• span — the operation name (knowledge.scan, ui.tab, server.reload).
• phase — in (params accepted), out (result produced), end (a unit of work finished), or event (a point-in-time fact, e.g. a tab switch). Pair an in with its later out/end of the same span by adjacency — the UI is single-threaded, so within one operation they don’t interleave.
• data — the real, structured payload. Emit typed structs (serialized via serde), never a pre-formatted string, so the consumer parses fields.

Cheap by design: a Mutex<File> writeln! + a global atomic seq. Call sites only emit on edge-triggered events (a scan, a click, an RPC), never per-frame.

Enums

Phase

Phase of an instrumented operation. Lets a consumer correlate the inputs a call accepted with the data it produced.

Functions

emit

Emit one structured event: span is the operation, phase its stage, and data the real payload (any Serialize — a typed struct, ideally). Writes a single JSONL line to $FACETT_TRACE; never panics (best-effort I/O).

emit_end

Convenience: a unit of work finished (no separate in/out).

emit_event

Convenience: a point-in-time fact (tab switch, selection).

emit_in

Convenience: the inputs a call accepted.

emit_out

Convenience: the data a call produced.