Lifecycle and live traces
Trace collection and failure analysis do not finish at the same instant. Perseval exposes lifecycle and pipeline state so “the queue is empty” is not mistaken for “the diagnosis is ready.”
Revision lifecycle
Section titled “Revision lifecycle”| State | Meaning |
|---|---|
| Live | Committed spans are still arriving for the active revision. |
| Quiescent | No committed activity for 30 seconds; the grace period is running. |
| Finalized | Another 5 seconds passed without activity; the revision is immutable and eligible for analysis. |
| Reopened | A late span arrived after finalization; a new live revision was created. |
Root completion is useful UI information but is not authoritative. Distributed exporters can deliver children after the root ended.
Analysis state
Section titled “Analysis state”Finalization creates a clean input boundary for deterministic analysis. The UI may show Analyzing or pending analysis after collection and projection have caught up. A finding group appears only after its committed analysis result is projected.
Source health counters
Section titled “Source health counters”Sources and the status bar expose:
- effective endpoint and receiver state;
- queue utilization and backpressure;
- rejected spans;
- journal and projection lag;
- live, quiescent, finalized, and reopened counts;
- analysis pending state.
Queue 0/64 and journal lag 0 mean the ingest path caught up. Check lifecycle and analysis state separately.
Live UI updates
Section titled “Live UI updates”The application subscribes to committed deltas. It coalesces a bounded number per frame, invalidates affected pages, and preserves selection by stable project/run/revision/span IDs. It does not reload a complete trace because one batch arrived.
If a sequence gap exceeds retained history, the UI marks itself Delayed, takes a bounded snapshot, invalidates affected pages, and resumes without blocking input.
Backpressured
Section titled “Backpressured”When the pre-durable queue is full, the receiver returns 429 plus Retry-After. The status surface shows Backpressured rather than pretending the batch was accepted. See OTLP ingestion.
Shutdown
Section titled “Shutdown”The embedded receiver follows the GUI lifecycle. Perseval drains admitted work for up to 5 seconds during coordinated shutdown. Producers should still retry retryable transport errors and rely on content deduplication.