rlg/
lib.rs

1// src/lib.rs
2// Copyright © 2024-2026 RustLogs (RLG). All rights reserved.
3// SPDX-License-Identifier: Apache-2.0
4// SPDX-License-Identifier: MIT
5
6//! # RLG — Near-Lock-Free Structured Logging for Rust
7//!
8//! `rlg` pushes structured log events through a 65k-slot ring buffer
9//! ([LMAX Disruptor](https://lmax-exchange.github.io/disruptor/) pattern)
10//! in ~1.4 µs. A background flusher thread handles serialization and
11//! dispatch to platform-native sinks (`os_log`, `journald`, files, stdout).
12//!
13//! ## Why RLG
14//!
15//! - **No Mutex on the hot path.** `ingest()` uses atomic operations only.
16//! - **Deferred formatting.** Serialization runs on the flusher thread.
17//! - **14 output formats.** JSON, MCP, OTLP, ECS, CEF, GELF, Logfmt, and more.
18//! - **MIRI-verified.** Zero undefined behaviour under strict provenance.
19//!
20//! ## Quick Start
21//!
22//! ```rust,no_run
23//! // Initialize once at the top of main. Hold the guard.
24//! let _guard = rlg::init().unwrap();
25//!
26//! use rlg::log::Log;
27//! use rlg::log_format::LogFormat;
28//!
29//! Log::info("User authenticated")
30//!     .component("auth-service")
31//!     .with("user_id", 42)
32//!     .with("session_uuid", "a1b2c3d4")
33//!     .format(LogFormat::MCP)
34//!     .fire();
35//! ```
36//!
37//! ## Features
38//!
39//! No features are enabled by default.
40//!
41//! | Feature | Effect |
42//! |---------|--------|
43//! | `tokio` | Async config loading, hot-reload via `notify`. |
44//! | `tui` | Live terminal dashboard via `terminal_size`. |
45//! | `miette` | Pretty diagnostic error reports. |
46//! | `tracing-layer` | Composable `tracing_subscriber::Layer`. |
47//! | `debug_enabled` | Verbose internal engine diagnostics. |
48//!
49//! ## Architecture
50//!
51//! ```text
52//! Application Thread → Log::fire() → ArrayQueue (65k)
53//!                                         ↓
54//!                              Background Flusher Thread
55//!                                         ↓
56//!                              PlatformSink (os_log / journald / file / stdout)
57//! ```
58//!
59//! The flusher drains events in batches of 64. Fields use `Cow<str>` and
60//! `u64` session IDs to minimize heap allocations on the hot path.
61
62#![deny(
63    clippy::all,
64    clippy::pedantic,
65    clippy::nursery,
66    rust_2018_idioms
67)]
68#![warn(missing_docs)]
69#![allow(clippy::module_name_repetitions)]
70
71/// TOML-based configuration, validation, and hot-reload.
72pub mod config;
73/// Ring buffer engine: ingestion, flushing, and the global `ENGINE`.
74pub mod engine;
75/// Error types and the `RlgResult` alias.
76pub mod error;
77/// Zero-config `init()`, builder API, and `FlushGuard`.
78pub mod init;
79/// `Log` struct, fluent builder, and per-format `Display` impls.
80pub mod log;
81/// 14 structured output formats (JSON, MCP, OTLP, ECS, CEF, ...).
82pub mod log_format;
83/// Severity levels: `ALL` through `DISABLED`, with `FromStr` parsing.
84pub mod log_level;
85/// Bridge from the `log` crate facade into the RLG engine.
86pub mod logger;
87/// Macros: `rlg_span!`, `rlg_time_it!`, `rlg_mcp_notify!`.
88pub mod macros;
89/// Log rotation policies: size, time, date, and count-based.
90pub mod rotation;
91/// Platform-native sinks: `os_log` (macOS), `journald` (Linux), file, stdout.
92pub mod sink;
93/// `tracing` integration: `RlgSubscriber` and optional `RlgLayer`.
94pub mod tracing;
95/// Opt-in terminal dashboard for live metrics (`RLG_TUI=1`).
96pub mod tui;
97/// Timestamps, file I/O helpers, and input sanitization.
98pub mod utils;
99
100/// Shared utilities from `euxis-commons`.
101pub use euxis_commons as commons;
102
103// --- Flattened re-exports ---
104pub use crate::error::{RlgError, RlgResult};
105pub use crate::init::{
106    FlushGuard, InitError, RlgBuilder, builder, init,
107};
108pub use crate::log::Log;
109pub use crate::log_format::LogFormat;
110pub use crate::log_level::LogLevel;
111pub use crate::logger::RlgLogger;
112pub use crate::sink::PlatformSink;
113pub use crate::tracing::RlgSubscriber;
114
115#[cfg(feature = "tracing-layer")]
116pub use crate::tracing::RlgLayer;
117
118/// Crate version, injected at compile time.
119pub const VERSION: &str = env!("CARGO_PKG_VERSION");
rlg/lib.rs

rlg/
lib.rs
