Crate zeroclaw_log 

Unified log emission surface for the ZeroClaw workspace.

Every crate that emits domain events (agent activity, channel I/O, cron runs, tool calls, memory ops, session lifecycle, errors) goes through record!. That single emission point fans out to:

1. A tracing::event! at the matching severity so RUST_LOG-gated terminal output and any external tracing-subscriber consumer see the event with structured key=value fields.
2. The persisted JSONL log at <workspace>/state/runtime-trace.jsonl (when [observability] log_persistence is "rolling" or "full").
3. The process-wide broadcast channel so the dashboard’s SSE stream sees every event live.

Schema is an OTel/ECS hybrid with a ZeroClaw-domain zeroclaw.* namespace for the alias-bound attribution fields. See event::LogEvent.

Re-exports

pub use broadcast::LogBroadcastSender;

pub use broadcast::clear_broadcast_hook;

pub use broadcast::current_broadcast_hook;

pub use broadcast::set_broadcast_hook;

pub use broadcast::subscribe;

pub use chain::display_chain;

pub use config::LogConfig;

pub use config::ResolvedPolicy;

pub use config::StoragePolicy;

pub use config::ToolIoPolicy;

pub use event::ATTRIBUTION_FIELDS;

pub use event::Action;

pub use event::COMPOSITE_PREFIXES;

pub use event::Event;

pub use event::EventCategory;

pub use event::EventOutcome;

pub use event::LogEvent;

pub use event::Severity;

pub use event::ZeroclawAttribution;

pub use event::is_attribution_field;

pub use event::severity_text_from_number;

pub use event::severity_text_from_tracing_level;

pub use layer::LogCaptureLayer;

pub use migrate::migrate_legacy_jsonl_in_place;

pub use observer_bridge::clear_observer_bridge;

pub use observer_bridge::set_observer_bridge;

pub use reader::LogFilter;

pub use reader::LogPage;

pub use reader::current_log_path;

pub use reader::find_event_by_id;

pub use reader::load_page;

pub use tool_io::ToolIoCapture;

pub use tool_io::capture_tool_input;

pub use tool_io::capture_tool_output;

pub use writer::init_from_config;

pub use writer::record_event;

pub use writer::runtime_trace_path;

Modules

broadcast

Process-wide broadcast channel for the canonical log stream.

chain

Anyhow error-chain rendering helper.

config

Policy types parsed from the runtime’s observability config.

event

Canonical event schema. OTel logs data model + ECS attribute conventions, with a zeroclaw.* namespace for the alias-bound domain attribution fields.

field

Span field helpers (e.g. field::Empty for fields that get recorded later via span.record(...)).

layer

tracing-subscriber Layer that captures record! emissions and attribution_span! spans, assembling alias-bound LogEvents and routing them to JSONL persistence, the broadcast hook, and the Observer bridge.

migrate

One-shot, streaming, in-place migration from schema_version 1 rows to schema_version 2.

observer_bridge

Observer bridge — projects crate::LogEvents onto the typed [zeroclaw_api::observability_traits::ObserverEvent] variants when a bound observer is installed.

reader

Paginated stream reader for the JSONL log file.

tool_io

Tool input/output capture: leak-scan + truncation + denylist.

writer

JSONL append-only writer + rolling rotation.

Macros

attribution_span

Open an attribution span for the given Attributable thing. Every record! emitted while the returned span is entered inherits the thing’s role + alias as alias-bound attribution on the resulting LogEvent. Wrap entry-point work with .instrument(span) (async) or let _g = span.entered() (sync).

debug_span

Ad-hoc span constructors. Prefer attribution_span!(thing) when the field set comes from an Attributable impl; reach for these only when the work doesn’t tie to a role. Constructs a span at the debug level.

error_span

Ad-hoc span constructors. Prefer attribution_span!(thing) when the field set comes from an Attributable impl; reach for these only when the work doesn’t tie to a role. Constructs a span at the error level.

info_span

Ad-hoc span constructors. Prefer attribution_span!(thing) when the field set comes from an Attributable impl; reach for these only when the work doesn’t tie to a role. Constructs a span at the info level.

record

Emit a structured ZeroClaw log event. The single positional Event expression carries the typed payload; the trailing literal is the human-readable message.

scope

Open a free-form context span carrying ad-hoc fields (sender id, message id, turn id, etc.) for every record! inside its scope. Use sparingly — prefer attribution_span!(thing) for role-bearing attribution. This is for transient per-scope identifiers that aren’t tied to an Attributable.

spawn

tokio::spawn that propagates the caller’s current span(s) into the spawned task. Use everywhere a per-message child task needs the parent’s attribution.

trace_span

Ad-hoc span constructors. Prefer attribution_span!(thing) when the field set comes from an Attributable impl; reach for these only when the work doesn’t tie to a role. Constructs a span at the trace level.

warn_span

Ad-hoc span constructors. Prefer attribution_span!(thing) when the field set comes from an Attributable impl; reach for these only when the work doesn’t tie to a role. Constructs a span at the warn level.

Structs

Span

Opaque span handle. Same wire format as tracing::Span (we re-export the type) but the public path is zeroclaw_log::Span — no tracing in any consumer’s source. A handle representing a span, with the capability to enter the span if it exists.

Traits

Instrument

Future combinator that attaches a Span to the future. Use as future.instrument(span).await at entry points. Attaches spans to a std::future::Future.

Functions

install_global_subscriber

Install the global tracing subscriber: stderr fmt with the agent-alias-prefixed formatter on top + the LogCaptureLayer that routes structured events to the JSONL writer, broadcast hook, and Observer bridge.