wide_log/lib.rs
1//! # wide-log
2//!
3//! A high-speed wide-event logging system for Rust. A single structured event
4//! accumulates fields throughout a request/task lifecycle and is emitted as
5//! one JSON line on completion.
6//!
7//! ## Quick Start
8//!
9//! The [`wide_log!`] macro takes a JSON object literal and generates the key
10//! enum, `Key` trait impl, thread-local storage, guard builder, `current()`
11//! accessor, `scope()` / `scope_default()` async functions (behind the
12//! `tokio` feature), `WideLogLayer` tower middleware (behind the `tokio`
13//! feature), and all logging macros (`wl_set!`, `wl_inc!`, `info!`, etc.) in
14//! one invocation.
15//!
16//! ```rust,ignore
17//! use wide_log::wide_log;
18//!
19//! wide_log!({
20//! "service": {
21//! "name": null,
22//! "version": "1.0.0",
23//! },
24//! "requests": counter!,
25//! });
26//!
27//! fn main() {
28//! tracing_subscriber::fmt().init();
29//! let _guard = WideLogGuard::builder().build();
30//! wl_set!("service.name", "example-service");
31//! wl_inc!("requests");
32//! info!("request received");
33//! // _guard drops → duration.total_ms set, timestamp set,
34//! // event emitted as JSON.
35//! }
36//! ```
37//!
38//! ## Auto-Added Keys
39//!
40//! - **`"log"`** — log entries from `info!()`, `warn!()`, etc. Handled
41//! internally; never declared by the user.
42//! - **`"duration"`** — elapsed time in ms. Auto-added as
43//! `"duration": { "total_ms": duration! }` if not declared.
44//! - **`"event"`** — event metadata. Auto-added as
45//! `"event": { "timestamp": null, "id": null }` if not declared.
46//! The `timestamp` is set to an RFC 3339 string on drop. The `id` is
47//! set to a ULID string (or UUIDv4 with the `uuid` feature) on `build()`.
48//!
49//! ## Builder Pattern
50//!
51//! Use `WideLogGuard::builder()` to construct a guard. The builder allows
52//! specifying a custom timezone, ID generator, and emit function:
53//!
54//! ```rust,ignore
55//! // Default: UTC timezone, ULID ID, tracing emit
56//! let _guard = WideLogGuard::builder().build();
57//!
58//! // Custom timezone
59//! use chrono_tz::Tz;
60//! let _guard = WideLogGuard::builder()
61//! .with_timezone(Tz::America__New_York)
62//! .build();
63//!
64//! // Custom ID generator
65//! let _guard = WideLogGuard::builder()
66//! .with_id(|| "my-custom-id".to_string())
67//! .build();
68//!
69//! // UUIDv4 ID (requires `uuid` feature)
70//! let _guard = WideLogGuard::builder()
71//! .with_uuid()
72//! .build();
73//!
74//! // Custom emit function
75//! let _guard = WideLogGuard::builder()
76//! .with_emit(|ev| { println!("{}", ev.to_json().unwrap()); })
77//! .build();
78//! ```
79//!
80//! ## `info!` Shadowing
81//!
82//! The generated `info!`, `warn!`, `error!`, `debug!`, `trace!` macros shadow
83//! `tracing::info!` etc. when both are in scope. To call the real tracing
84//! macros, use the fully qualified path: `::tracing::info!(...)`.
85//!
86//! ## Features
87//!
88//! - `tokio` — enables async support: `scope()`, `scope_default()`,
89//! `WideLogLayer` tower middleware, and `tokio::task_local!` storage.
90//! - `uuid` — enables `WideLogGuardBuilder::with_uuid()` for UUIDv4 ID
91//! generation instead of the default ULID.
92
93pub mod context;
94pub mod error;
95pub mod guard;
96pub mod key;
97pub(crate) mod log;
98pub mod value;
99pub mod wide_event;
100
101#[cfg(feature = "tokio")]
102pub mod middleware;
103
104pub use error::Error;
105pub use guard::ScopedGuard;
106pub use key::Key;
107pub use value::Value;
108pub use wide_event::WideEvent;
109
110pub use context::ContextCell;
111
112/// The `wide_log!` proc-macro. See the [crate-level documentation](crate)
113/// for syntax and usage details.
114///
115/// Takes a JSON object literal as its only parameter. The JSON structure
116/// defines all keys, their nesting/paths, default values, and which keys
117/// are counters or durations. The macro generates:
118///
119/// - The `EventKey` enum (`#[repr(u8)]`, one variant per unique JSON key)
120/// - The `Key` trait impl (`as_str`, `MAX_KEYS`, `as_index`,
121/// `DURATION_PATH`, `TIMESTAMP_PATH`, `ID_PATH`)
122/// - `__wl_resolve_path` — compile-time path resolution function
123/// - Thread-local storage (`CURRENT_EVENT: ContextCell<WideEvent<EventKey>>`)
124/// - `default_emit` — serializes via `sonic_rs` and emits via `::tracing::info!`
125/// - `WideLogGuardBuilder` — builder for constructing guards with timezone,
126/// ID generator, and emit function
127/// - `WideLogGuard` — guard type (constructed via `builder().build()`)
128/// - `current()` — returns the innermost active event
129/// - `scope()` / `scope_default()` (behind `tokio` feature)
130/// - `WideLogLayer` tower middleware (behind `tokio` feature)
131/// - All logging macros: `wl_set!`, `wl_inc!`, `wl_dec!`, `wl_add!`,
132/// `wl_null!`, `info!`, `warn!`, `error!`, `debug!`, `trace!`
133///
134/// # Value Markers
135///
136/// | Marker | Meaning |
137/// |---|---|
138/// | `duration!` | Duration leaf; set to elapsed ms on drop |
139/// | `counter!` | Incrementable counter; init to 0 (absent) |
140/// | `null` | No default value; set via `wl_set!` |
141/// | `"literal"` | String default; set on guard creation |
142/// | `123` | Numeric default; set on guard creation |
143/// | `true`/`false` | Boolean default; set on guard creation |
144///
145/// # Duration Auto-Add Rules
146///
147/// If no `"duration"` key is declared, the macro adds
148/// `"duration": { "total_ms": duration! }` automatically. See the README for
149/// the full duration resolution table.
150///
151/// # Event Auto-Add Rules
152///
153/// If no `"event"` key is declared, the macro adds
154/// `"event": { "timestamp": null, "id": null }` automatically.
155/// The `timestamp` is set to an RFC 3339 string on drop.
156/// The `id` is set to a ULID string (or UUIDv4 with the `uuid` feature)
157/// on `build()`.
158pub use wide_log_macros::wide_log;
159
160#[cfg(feature = "tokio")]
161pub mod __re_exports {
162 pub use tokio;
163 pub use tower;
164}
165
166pub mod __re_exports_core {
167 pub use chrono;
168 pub use chrono_tz;
169 pub use ulid;
170}