zeroclaw_log/
lib.rs

1//! Unified log emission surface for the ZeroClaw workspace.
2//!
3//! Every crate that emits domain events (agent activity, channel I/O, cron
4//! runs, tool calls, memory ops, session lifecycle, errors) goes through
5//! [`record!`]. That single emission point fans out to:
6//!
7//! 1. A `tracing::event!` at the matching severity so `RUST_LOG`-gated
8//!    terminal output and any external `tracing-subscriber` consumer see
9//!    the event with structured `key=value` fields.
10//! 2. The persisted JSONL log at `<workspace>/state/runtime-trace.jsonl`
11//!    (when `[observability] log_persistence` is `"rolling"` or `"full"`).
12//! 3. The process-wide broadcast channel so the dashboard's SSE stream
13//!    sees every event live.
14//!
15//! Schema is an OTel/ECS hybrid with a ZeroClaw-domain `zeroclaw.*`
16//! namespace for the alias-bound attribution fields. See [`event::LogEvent`].
17
18pub mod broadcast;
19pub mod chain;
20pub mod config;
21pub mod event;
22pub mod layer;
23pub mod migrate;
24pub mod observer_bridge;
25pub mod reader;
26mod subscriber;
27pub mod tool_io;
28pub mod writer;
29
30/// Private re-export root. The `record!` / `scope!` / `attribution_span!`
31/// macros expand to paths under here so external crates can never
32/// reach `tracing` types via `zeroclaw_log::*`. Do NOT use directly
33/// from anywhere outside this crate.
34#[doc(hidden)]
35pub mod __private {
36    pub use ::chrono;
37    pub use ::serde_json;
38    pub use ::tracing;
39    pub use ::uuid;
40}
41
42pub use broadcast::{
43    LogBroadcastSender, clear_broadcast_hook, current_broadcast_hook, set_broadcast_hook,
44    subscribe, subscribe_or_install,
45};
46pub use chain::display_chain;
47pub use config::{LogConfig, ResolvedPolicy, StoragePolicy, ToolIoPolicy};
48pub use event::{
49    ATTRIBUTION_FIELDS, Action, COMPOSITE_PREFIXES, Event, EventCategory, EventOutcome, LogEvent,
50    Severity, ZeroclawAttribution, is_attribution_field, severity_text_from_number,
51    severity_text_from_tracing_level,
52};
53pub use layer::LogCaptureLayer;
54
55/// Opaque span handle. Same wire format as `tracing::Span` (we re-export
56/// the type) but the public path is `zeroclaw_log::Span` — no `tracing`
57/// in any consumer's source.
58pub use ::tracing::Span;
59
60/// Future combinator that attaches a [`Span`] to the future. Use as
61/// `future.instrument(span).await` at entry points.
62pub use ::tracing::Instrument;
63
64/// Ad-hoc span constructors. Prefer `attribution_span!(thing)` when
65/// the field set comes from an `Attributable` impl; reach for these
66/// only when the work doesn't tie to a role.
67pub use ::tracing::{debug_span, error_span, info_span, trace_span, warn_span};
68
69/// Span field helpers (e.g. [`field::Empty`] for fields that get
70/// recorded later via `span.record(...)`).
71pub mod field {
72    pub use ::tracing::field::{Empty, FieldSet};
73}
74
75pub use migrate::migrate_legacy_jsonl_in_place;
76pub use observer_bridge::{clear_observer_bridge, set_observer_bridge};
77pub use reader::{LogFilter, LogPage, current_log_path, find_event_by_id, load_page};
78pub use subscriber::{install_global_subscriber, try_install_capture_subscriber};
79pub use tool_io::{ToolIoCapture, capture_tool_input, capture_tool_output};
80pub use writer::{init_from_config, record_event, runtime_trace_path};
81
82mod r#macro;
zeroclaw_log/lib.rs

zeroclaw_log/
lib.rs
