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 type, `current()`
11//! accessor, `scope()` / `scope_default()` async functions (behind the `tokio`
12//! feature), `WideLogLayer` tower middleware (behind the `tokio` feature),
13//! and all logging macros (`wl_set!`, `wl_inc!`, `info!`, etc.) in one
14//! 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 = EventKeyGuard::new();
30//!     wl_set!("service.name", "example-service");
31//!     wl_inc!("requests");
32//!     info!("request received");
33//!     // _guard drops → duration.total_ms set, event emitted as JSON.
34//! }
35//! ```
36//!
37//! ## Auto-Added Keys
38//!
39//! - **`"log"`** — log entries from `info!()`, `warn!()`, etc. Handled
40//!   internally; never declared by the user.
41//! - **`"duration"`** — elapsed time in ms. Auto-added as
42//!   `"duration": { "total_ms": duration! }` if not declared.
43//!
44//! ## `info!` Shadowing
45//!
46//! The generated `info!`, `warn!`, `error!`, `debug!`, `trace!` macros shadow
47//! `tracing::info!` etc. when both are in scope. To call the real tracing
48//! macros, use the fully qualified path: `::tracing::info!(...)`.
49//!
50//! ## Features
51//!
52//! - `tokio` — enables async support: `scope()`, `scope_default()`,
53//!   `WideLogLayer` tower middleware, and `tokio::task_local!` storage.
54
55pub mod context;
56pub mod error;
57pub mod guard;
58pub mod key;
59pub(crate) mod log;
60pub mod value;
61pub mod wide_event;
62
63#[cfg(feature = "tokio")]
64pub mod middleware;
65
66pub use error::Error;
67pub use guard::WideEventGuard;
68pub use key::Key;
69pub use value::Value;
70pub use wide_event::WideEvent;
71
72pub use context::ContextCell;
73
74/// The `wide_log!` proc-macro. See the [crate-level documentation](crate)
75/// for syntax and usage details.
76///
77/// Takes a JSON object literal as its only parameter. The JSON structure
78/// defines all keys, their nesting/paths, default values, and which keys
79/// are counters or durations. The macro generates:
80///
81/// - The `EventKey` enum (`#[repr(u8)]`, one variant per unique JSON key)
82/// - The `Key` trait impl (`as_str`, `MAX_KEYS`, `as_index`, `DURATION_PATH`)
83/// - `__wl_resolve_path` — compile-time path resolution function
84/// - Thread-local storage (`CURRENT_EVENT: ContextCell<WideEvent<EventKey>>`)
85/// - `default_emit` — serializes via `sonic_rs` and emits via `::tracing::info!`
86/// - `EventKeyGuard` — guard type with `new()` and `new_with_emit()`
87/// - `current()` — returns the innermost active event
88/// - `scope()` / `scope_default()` (behind `tokio` feature)
89/// - `WideLogLayer` tower middleware (behind `tokio` feature)
90/// - All logging macros: `wl_set!`, `wl_inc!`, `wl_dec!`, `wl_add!`,
91///   `wl_null!`, `info!`, `warn!`, `error!`, `debug!`, `trace!`
92///
93/// # Value Markers
94///
95/// | Marker | Meaning |
96/// |---|---|
97/// | `duration!` | Duration leaf; set to elapsed ms on drop |
98/// | `counter!` | Incrementable counter; init to 0 (absent) |
99/// | `null` | No default value; set via `wl_set!` |
100/// | `"literal"` | String default; set on guard creation |
101/// | `123` | Numeric default; set on guard creation |
102/// | `true`/`false` | Boolean default; set on guard creation |
103///
104/// # Duration Auto-Add Rules
105///
106/// If no `"duration"` key is declared, the macro adds
107/// `"duration": { "total_ms": duration! }` automatically. See the README for
108/// the full duration resolution table.
109pub use wide_log_macros::wide_log;
110
111#[cfg(feature = "tokio")]
112pub mod __re_exports {
113    pub use tokio;
114    pub use tower;
115}
wide_log/lib.rs

wide_log/
lib.rs
