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#![allow(clippy::module_name_repetitions)]
69// Enable `#[doc(cfg(feature = "…"))]` under docs.rs so feature-gated
70// items advertise the flag that enables them. The `docsrs` cfg is set
71// by `[package.metadata.docs.rs]`.
72#![cfg_attr(docsrs, feature(doc_cfg))]
73
74/// TOML-based configuration, validation, and hot-reload.
75pub mod config;
76/// Internal ISO 8601 timestamp helpers (replaces the historical `dtt` dep).
77pub mod datetime;
78/// Ring buffer engine: ingestion, flushing, and the global `ENGINE`.
79pub mod engine;
80/// Error types and the `RlgResult` alias.
81pub mod error;
82/// Zero-config `init()`, builder API, and `FlushGuard`.
83pub mod init;
84/// `Log` struct, fluent builder, and per-format `Display` impls.
85pub mod log;
86/// 14 structured output formats (JSON, MCP, OTLP, ECS, CEF, ...).
87pub mod log_format;
88/// Severity levels: `ALL` through `DISABLED`, with `FromStr` parsing.
89pub mod log_level;
90/// Bridge from the `log` crate facade into the RLG engine.
91pub mod logger;
92/// Macros: `rlg_span!`, `rlg_time_it!`, `rlg_mcp_notify!`.
93pub mod macros;
94/// Log rotation policies: size, time, date, and count-based.
95pub mod rotation;
96/// Internal sharded queue backing the engine's ring buffer.
97/// Behaviour switches on the `fast-queue` feature — see
98/// `docs/adr/0009-sharded-producer-queue.md`.
99//
100// `redundant_pub_crate` (clippy::nursery) fires because the module
101// is already `pub(crate)`; `unreachable_pub` (workspace lint) fires
102// if we drop the `pub(crate)` on items inside. The `allow` here
103// resolves the tension by suppressing the nursery lint at the
104// module-import site.
105#[allow(clippy::redundant_pub_crate)]
106pub(crate) mod sharded_queue;
107/// Platform-native sinks: `os_log` (macOS), `journald` (Linux), file, stdout.
108pub mod sink;
109/// `tracing` integration: `RlgSubscriber` and optional `RlgLayer`.
110pub mod tracing;
111/// Opt-in terminal dashboard for live metrics (`RLG_TUI=1`).
112pub mod tui;
113/// Timestamps, file I/O helpers, and input sanitization.
114pub mod utils;
115
116/// Kani model-checked proofs. Only compiled under `--cfg kani`
117/// (set automatically by `cargo kani`). See
118/// `docs/adr/0004-kani-verified-invariants.md`.
119#[cfg(kani)]
120mod kani_proofs;
121
122/// Shared utilities from `euxis-commons`.
123pub use euxis_commons as commons;
124
125// --- Flattened re-exports ---
126pub use crate::error::{RlgError, RlgResult};
127pub use crate::init::{
128    FlushGuard, InitError, RlgBuilder, builder, init,
129};
130pub use crate::log::Log;
131pub use crate::log_format::LogFormat;
132pub use crate::log_level::LogLevel;
133pub use crate::logger::RlgLogger;
134pub use crate::sink::PlatformSink;
135pub use crate::tracing::RlgSubscriber;
136
137#[cfg(feature = "tracing-layer")]
138#[cfg_attr(docsrs, doc(cfg(feature = "tracing-layer")))]
139pub use crate::tracing::RlgLayer;
140
141/// Crate version, injected at compile time.
142pub const VERSION: &str = env!("CARGO_PKG_VERSION");
rlg/lib.rs

rlg/
lib.rs
