Module telemetry 

Retroactive telemetry aggregation over a completed (corpus, service) run.

The latexml-oxide cortex_worker writes a per-job telemetry.json into every result archive (wall/RSS, per-phase microseconds, message + asset counts). This module reads those records back off disk — one random-access by_name("telemetry.json") seek per result ZIP, mirroring crate::helpers’s read_cortex_log — and rolls them up into a TelemetrySummary: nearest-rank wall/RSS percentiles, a per-phase P99 breakdown, an outcome mix, and the slowest / highest-RSS witness papers.

It is read-only and off the dispatch hot path — the frontend telemetry dashboard (crate::frontend::telemetry) drives it lazily on a cache miss. Every field of a record is #[serde(default)], because the worker’s failure path emits only paper_id/category/ exit_code; a missing numeric or array field is simply zero / empty, never a parse error.

Structs

MathStats

Math-parsing rollup. parses_per_formula = parse_count / attempts — the corpus-wide grammar ambiguity (over-parse) multiplier that semantics-pruning then collapses.

OutcomeWall

Wall-time profile of one outcome bucket — used to show that fatal papers are bimodal (most fail fast; a slow-runaway subset burns ~timeout before dying).

Percentiles

Nearest-rank percentiles of a sample (plus its max), in whatever unit the input carries.

RssBuckets

Peak-RSS bucket counts — how many papers cross each memory line (the 4 GiB alloc wall being the release concern).

TailStats

Wall-time tail concentration: how top-heavy the run is, and how close the slowest papers get to the conversion timeout. topN_pct_wall_share is the fraction (%) of all wall time held by the slowest N% of papers; the over_*s counts are papers at/above that wall threshold.

TelemetryRecord

One worker telemetry.json record. Every field is #[serde(default)]: the worker’s failure path emits only paper_id/category/exit_code, so a missing numeric field decodes to 0 and a missing phase_us to an empty vector rather than failing the whole parse.

TelemetrySummary

The rolled-up telemetry of a completed (corpus, service) run — the shared read model for both the telemetry dashboard screen and its agent JSON twin.

Constants

PHASES

The 17 conversion phases the worker times, in emission order — the index into a TelemetryRecord::phase_us entry and the label of a per-phase P99 row. Kept in lock-step with the latexml-oxide worker’s telemetry writer; a shorter/absent phase_us (the failure path) simply contributes nothing to the tail phases.

Functions

aggregate

Aggregates the telemetry of a completed run: reads each task entry’s result-archive telemetry.json in parallel (a bounded std::thread::scope pool, N = available_parallelism capped at 16, the entries chunked evenly across threads), skipping any archive that is missing / unreadable / lacks a telemetry record, then summarizes. sandbox_id is threaded through result_archive_path so a sandbox corpus reads its own name-scoped archives, not the parent’s.

percentiles

Nearest-rank percentiles of values (the copy is sorted; the input may be unsorted). The rank for percentile p is ceil(p/100 * n) clamped to [1, n], taken at index rank - 1. An empty sample yields all-zeros.

read_telemetry_json

Reads and decodes the telemetry.json member of a result .zip. Mirrors crate::helpers’s read_cortex_log: the pure-Rust zip crate’s random-access by_name seeks straight to telemetry.json via the central directory, never decompressing the (potentially large) converted output. Returns the decoded record, or an Err describing why it couldn’t (a non-zip / corrupt archive, a missing telemetry.json, or invalid JSON) — the caller counts that as a skipped sample rather than failing the whole aggregation.

summarize

Rolls a slice of telemetry records into a TelemetrySummary. Pure and DB-free (the reading is aggregate’s job): outcome bucketing, unit conversions (µs→ms, KiB→MiB), nearest-rank percentiles, per-phase P99, witnesses, and totals. skipped is left 0 — aggregate fills it from the read pass.