rlg 0.0.11

A near-lock-free structured logging library for Rust. Sub-microsecond ingestion via a 65k-slot ring buffer (LMAX Disruptor pattern), deferred formatting, and native OS sinks (`os_log` on macOS via `syslog(3)`, `journald` on Linux). 14 output formats including JSON, MCP, OTLP, ECS, GELF, CEF, and Logfmt.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

// src/lib.rs
// Copyright © 2024-2026 RustLogs (RLG). All rights reserved.
// SPDX-License-Identifier: Apache-2.0
// SPDX-License-Identifier: MIT

//! # RLG — Near-Lock-Free Structured Logging for Rust
//!
//! `rlg` pushes structured log events through a 65k-slot ring buffer
//! ([LMAX Disruptor](https://lmax-exchange.github.io/disruptor/) pattern)
//! in ~1.4 µs. A background flusher thread handles serialization and
//! dispatch to platform-native sinks (`os_log`, `journald`, files, stdout).
//!
//! ## Why RLG
//!
//! - **No Mutex on the hot path.** `ingest()` uses atomic operations only.
//! - **Deferred formatting.** Serialization runs on the flusher thread.
//! - **14 output formats.** JSON, MCP, OTLP, ECS, CEF, GELF, Logfmt, and more.
//! - **MIRI-verified.** Zero undefined behaviour under strict provenance.
//!
//! ## Quick Start
//!
//! ```rust,no_run
//! // Initialize once at the top of main. Hold the guard.
//! let _guard = rlg::init().unwrap();
//!
//! use rlg::log::Log;
//! use rlg::log_format::LogFormat;
//!
//! Log::info("User authenticated")
//!     .component("auth-service")
//!     .with("user_id", 42)
//!     .with("session_uuid", "a1b2c3d4")
//!     .format(LogFormat::MCP)
//!     .fire();
//! ```
//!
//! ## Features
//!
//! No features are enabled by default.
//!
//! | Feature | Effect |
//! |---------|--------|
//! | `tokio` | Async config loading, hot-reload via `notify`. |
//! | `tui` | Live terminal dashboard via `terminal_size`. |
//! | `miette` | Pretty diagnostic error reports. |
//! | `tracing-layer` | Composable `tracing_subscriber::Layer`. |
//! | `debug_enabled` | Verbose internal engine diagnostics. |
//!
//! ## Architecture
//!
//! ```text
//! Application Thread → Log::fire() → ArrayQueue (65k)
//!                                         ↓
//!                              Background Flusher Thread
//!                                         ↓
//!                              PlatformSink (os_log / journald / file / stdout)
//! ```
//!
//! The flusher drains events in batches of 64. Fields use `Cow<str>` and
//! `u64` session IDs to minimize heap allocations on the hot path.

#![deny(
    clippy::all,
    clippy::pedantic,
    clippy::nursery,
    rust_2018_idioms
)]
#![allow(clippy::module_name_repetitions)]
// Enable `#[doc(cfg(feature = "…"))]` under docs.rs so feature-gated
// items advertise the flag that enables them. The `docsrs` cfg is set
// by `[package.metadata.docs.rs]`.
#![cfg_attr(docsrs, feature(doc_cfg))]

/// TOML-based configuration, validation, and hot-reload.
pub mod config;
/// Internal ISO 8601 timestamp helpers (replaces the historical `dtt` dep).
pub mod datetime;
/// Ring buffer engine: ingestion, flushing, and the global `ENGINE`.
pub mod engine;
/// Error types and the `RlgResult` alias.
pub mod error;
/// Zero-config `init()`, builder API, and `FlushGuard`.
pub mod init;
/// `Log` struct, fluent builder, and per-format `Display` impls.
pub mod log;
/// 14 structured output formats (JSON, MCP, OTLP, ECS, CEF, ...).
pub mod log_format;
/// Severity levels: `ALL` through `DISABLED`, with `FromStr` parsing.
pub mod log_level;
/// Bridge from the `log` crate facade into the RLG engine.
pub mod logger;
/// Macros: `rlg_span!`, `rlg_time_it!`, `rlg_mcp_notify!`.
pub mod macros;
/// Log rotation policies: size, time, date, and count-based.
pub mod rotation;
/// Internal sharded queue backing the engine's ring buffer.
/// Behaviour switches on the `fast-queue` feature — see
/// `docs/adr/0009-sharded-producer-queue.md`.
//
// `redundant_pub_crate` (clippy::nursery) fires because the module
// is already `pub(crate)`; `unreachable_pub` (workspace lint) fires
// if we drop the `pub(crate)` on items inside. The `allow` here
// resolves the tension by suppressing the nursery lint at the
// module-import site.
#[allow(clippy::redundant_pub_crate)]
pub(crate) mod sharded_queue;
/// Platform-native sinks: `os_log` (macOS), `journald` (Linux), file, stdout.
pub mod sink;
/// `tracing` integration: `RlgSubscriber` and optional `RlgLayer`.
pub mod tracing;
/// Opt-in terminal dashboard for live metrics (`RLG_TUI=1`).
pub mod tui;
/// Timestamps, file I/O helpers, and input sanitization.
pub mod utils;

/// Kani model-checked proofs. Only compiled under `--cfg kani`
/// (set automatically by `cargo kani`). See
/// `docs/adr/0004-kani-verified-invariants.md`.
#[cfg(kani)]
mod kani_proofs;

/// Shared utilities from `euxis-commons`.
pub use euxis_commons as commons;

// --- Flattened re-exports ---
pub use crate::error::{RlgError, RlgResult};
pub use crate::init::{
    FlushGuard, InitError, RlgBuilder, builder, init,
};
pub use crate::log::Log;
pub use crate::log_format::LogFormat;
pub use crate::log_level::LogLevel;
pub use crate::logger::RlgLogger;
pub use crate::sink::PlatformSink;
pub use crate::tracing::RlgSubscriber;

#[cfg(feature = "tracing-layer")]
#[cfg_attr(docsrs, doc(cfg(feature = "tracing-layer")))]
pub use crate::tracing::RlgLayer;

/// Crate version, injected at compile time.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");