rlg 0.0.9

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

// 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
)]
#![warn(missing_docs)]
#![allow(clippy::module_name_repetitions)]

/// 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;
/// 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;

/// 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")]
pub use crate::tracing::RlgLayer;

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