Module logs 

Available on crate feature serve only.

Per-run log capture for SSE streaming (GET /v1/runs/{id}/logs, spec §12).

RunLogLayer is a tracing Layer added to serve’s global subscriber. It tags every span that carries a serve_run_id field (the faucet.serve.run span each run executes inside — see runner.rs) and, for every event in such a span’s scope, formats a redacted line and pushes it into that run’s per-run buffer: a bounded ring (for backfill) plus a broadcast channel (for the live tail). The /logs handler replays the ring, then streams the live tail via log_events.

Ephemeral lifecycle. Buffers live while a run is active plus a short drain window (LOG_DRAIN) for late fetchers, then are dropped regardless of --retain-terminal-runs-secs — only RunRecord metadata honours that retention. Bulk/historic logs belong in the centralized tracing sink.

Structs

LogHub

Shared, cheaply-cloneable registry of per-run log buffers. One instance is created at subscriber install and shared between RunLogLayer and the /logs handler via ServerState.

LogLine

A single captured log line, tagged with a monotonic sequence number so a late /logs subscriber can de-duplicate ring backfill against the live tail.

RunLogLayer

Tracing layer that captures events tagged with a serve_run_id into the LogHub for SSE streaming. Added to serve’s global subscriber alongside the redacting fmt layer (observability.rs).

Enums

LogEvent

An SSE-bound log event, decoupled from axum’s Event so the streaming logic (ring replay → live tail, de-dup, lag handling) is unit-testable.

LogMsg

A message on a run’s live-tail broadcast channel.

Constants

BROADCAST_CAPACITY

Live-tail broadcast channel depth. A /logs reader that falls this far behind gets a truncated event rather than blocking producers.

LOG_DRAIN

How long a run’s log buffer survives after the run reaches a terminal state, so a late /logs fetcher can still replay it. Independent of run-record retention (spec §12).

RING_CAPACITY

Per-run ring-buffer capacity (lines). Past this the oldest line is evicted and late /logs subscribers see a truncated event.

Functions

log_events

Build the ordered event stream for a /logs request: replay the ring snapshot, then forward the live tail, de-duplicating against the snapshot by sequence number and mapping broadcast lag to LogEvent::Truncated.