fix(tracing): reliability follow-ups from v0.8.4 review (#901, #902, #903)

Merged
AN
6mo ago
+350-10

What does this PR do?

Three reliability follow-ups filed during the v0.8.4 release review of the trace-data-loss fix (#895), all in the observability subsystem.

#901 — reconstructed spans no longer masquerade as failures. When rehydrateFromFile force-closes an in-flight generation span (worker restart / cache eviction), the span kept status: "error", so the viewer painted it red and counted it in the session error total — a false alarm on a postmortem surface. Spans now also carry interrupted: true. The viewer renders them amber ("⚠ / Interrupted") instead of red on every surface (preview, detail, waterfall row, tree view, log view) and the session error count (errSpans) excludes them. status: "error" is kept so the boundary stays visible.

#902 — getOrCreateTrace can no longer resurrect a Trace into a cleared cache. The async rehydrate added an await where a concurrent startEventStream (e.g. setWorkspace) can abort the stream and sessionTraces.clear() while we're suspended. On resume the old code inserted the freshly built Trace into the just-cleared map — an orphan writer under a dead stream. We now capture a monotonic streamGeneration before the await and, if it changed, discard the Trace (endTrace) and defer to the live stream. Keyed on a counter (not AbortController identity) per review feedback.

#903 — long-lived traces no longer grow ses_<id>.json without bound. snapshot() rewrites the entire spans array on every event (O(n²) over a session). capSpansForSerialization bounds the on-disk projection to MAX_SERIALIZED_SPANS (default 5000, override ALTIMATE_TRACE_MAX_SPANS) via head + tail retention + one elision marker. In-memory spans are untouched; summary totals come from separate counters, so they're unaffected. The cut explicitly preserves the structural root span.

A two-model review panel (GPT-5.4 + Kimi-K2.5) reviewed the first commit; the second commit applies their MAJOR findings (stream-generation counter, explicit root preservation, amber treatment on all viewer surfaces) plus table-driven edge-case tests.

Known minor (deferred): a trace with only interrupted spans correctly contributes nothing to the error count but shows no "incomplete" hint in the summary; a dedicated incomplete banner is a small follow-up.

Type of change

  • Bug fix (non-breaking change which fixes an issue)

Issue for this PR

Closes #901
Closes #902
Closes #903

How did you verify your code works?

  • New test/altimate/tracing-followups.test.ts (15 tests): interrupted flag set on rehydrate; viewer carries amber/!sp.interrupted contract + flag in embedded data; capSpansForSerialization head/tail/marker, no-op under cap, no-benefit guard, root-not-at-index-0, tiny caps 1–5 with marker-parent validity, exact boundary, elided-count accuracy; scope-bounded source contract for the #902 guard ordering (await → guard → insert) and the streamGeneration bump.
  • Full tracing/viewer/worker sweep: 410 pass, 0 fail (22 files).
  • tsgo typecheck clean. Marker guard (analyze.ts --markers --base main --strict) clean — worker.ts edits wrapped in altimate_change markers.

Checklist

  • My code follows the style guidelines of this project
  • I have added tests that prove my fix is effective
  • New and existing unit tests pass locally with my changes
  • I have made corresponding changes to the documentation (n/a — internal observability behavior; ALTIMATE_TRACE_MAX_SPANS documented inline)

Summary by cubic

Marks reconstructed spans as interrupted (warning, not failure), guards against orphan trace writers across stream restarts, and caps on-disk spans to keep session files bounded. This removes false error counts and improves stability and performance for long sessions.

  • Bug Fixes
    • #901: rehydrateFromFile sets interrupted: true on force-closed generation spans; viewer shows amber "⚠ Interrupted" on all surfaces and excludes them from the session error count (keeps status: "error" for boundary visibility).
    • #902: getOrCreateTrace keys ownership to a monotonic streamGeneration; if the stream changed during rehydrate, it discards the trace instead of inserting into a cleared sessionTraces map (guard placed after await, before insert).
    • #903: Adds capSpansForSerialization to bound serialized spans to MAX_SERIALIZED_SPANS (default 5000; override ALTIMATE_TRACE_MAX_SPANS) using head+tail retention with an elision marker; always preserves the root span. In-memory spans and summary totals are unaffected.

Summary by CodeRabbit

  • New Features

    • Trace serialization now automatically capped to prevent unbounded growth, preserving head and tail of trace history
    • Trace viewer now visually distinguishes interrupted spans from genuine failures using distinct styling and status indicators
  • Bug Fixes

    • Fixed race condition in trace cache invalidation during stream resets