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//! with a few atomic operations. 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 and polling hot-reload. |
44//! | `tui` | Live terminal dashboard via `terminal_size`. |
45//! | `tracing-layer` | Composable `tracing_subscriber::Layer`. |
46//! | `debug_enabled` | Verbose internal engine diagnostics. |
47//!
48//! ## Architecture
49//!
50//! ```text
51//! Application Thread → Log::fire() → ArrayQueue (65k)
52//!                                         ↓
53//!                              Background Flusher Thread
54//!                                         ↓
55//!                              PlatformSink (os_log / journald / file / stdout)
56//! ```
57//!
58//! The flusher drains events in batches of 64. Fields use `Cow<str>` and
59//! `u64` session IDs to minimize heap allocations on the hot path.
60
61#![deny(
62    clippy::all,
63    clippy::pedantic,
64    clippy::nursery,
65    rust_2018_idioms
66)]
67#![allow(clippy::module_name_repetitions)]
68// Enable `#[doc(cfg(feature = "…"))]` under docs.rs so feature-gated
69// items advertise the flag that enables them. The `docsrs` cfg is set
70// by `[package.metadata.docs.rs]`.
71#![cfg_attr(docsrs, feature(doc_cfg))]
72
73/// TOML-based configuration, validation, and hot-reload.
74pub mod config;
75/// Internal ISO 8601 timestamp helpers (replaces the historical `dtt` dep).
76pub mod datetime;
77/// Ring buffer engine: ingestion, flushing, and the global `ENGINE`.
78pub mod engine;
79/// Error types and the `RlgResult` alias.
80pub mod error;
81/// Zero-config `init()`, builder API, and `FlushGuard`.
82pub mod init;
83/// `Log` struct, fluent builder, and per-format `Display` impls.
84pub mod log;
85/// 14 structured output formats (JSON, MCP, OTLP, ECS, CEF, ...).
86pub mod log_format;
87/// Severity levels: `ALL` through `DISABLED`, with `FromStr` parsing.
88pub mod log_level;
89/// Bridge from the `log` crate facade into the RLG engine.
90pub mod logger;
91/// Macros: `rlg_span!`, `rlg_time_it!`, `rlg_mcp_notify!`.
92pub mod macros;
93/// Log rotation policies: size, time, date, and count-based.
94pub mod rotation;
95/// Internal sharded queue backing the engine's ring buffer.
96/// Behaviour switches on the `fast-queue` feature — see
97/// `docs/adr/0009-sharded-producer-queue.md`.
98//
99// `redundant_pub_crate` (clippy::nursery) fires because the module
100// is already `pub(crate)`; `unreachable_pub` (workspace lint) fires
101// if we drop the `pub(crate)` on items inside. The `allow` here
102// resolves the tension by suppressing the nursery lint at the
103// module-import site.
104#[allow(clippy::redundant_pub_crate)]
105pub(crate) mod sharded_queue;
106/// Platform-native sinks: `os_log` (macOS), `journald` (Linux), file, stdout.
107pub mod sink;
108/// `tracing` integration: `RlgSubscriber` and optional `RlgLayer`.
109pub mod tracing;
110/// Opt-in terminal dashboard for live metrics (`RLG_TUI=1`).
111pub mod tui;
112/// Timestamps, file I/O helpers, and input sanitization.
113pub mod utils;
114
115/// Kani model-checked proofs. Only compiled under `--cfg kani`
116/// (set automatically by `cargo kani`). See
117/// `docs/adr/0004-kani-verified-invariants.md`.
118#[cfg(kani)]
119mod kani_proofs;
120
121/// Shared utilities from `euxis-commons`.
122pub use euxis_commons as commons;
123
124/// The workspace README's code blocks, compiled and run as doctests so
125/// its Quick Start cannot drift from the API.
126#[cfg(doctest)]
127#[doc = include_str!("../../../README.md")]
128pub struct WorkspaceReadmeDoctests;
129
130// --- Flattened re-exports ---
131pub use crate::error::{RlgError, RlgResult};
132pub use crate::init::{
133    FlushGuard, InitError, RlgBuilder, builder, init,
134};
135pub use crate::log::Log;
136pub use crate::log_format::LogFormat;
137pub use crate::log_level::LogLevel;
138pub use crate::logger::RlgLogger;
139pub use crate::sink::PlatformSink;
140pub use crate::tracing::RlgSubscriber;
141
142#[cfg(feature = "tracing-layer")]
143#[cfg_attr(docsrs, doc(cfg(feature = "tracing-layer")))]
144pub use crate::tracing::RlgLayer;
145
146/// Crate version, injected at compile time.
147pub const VERSION: &str = env!("CARGO_PKG_VERSION");
rlg/lib.rs

rlg/
lib.rs
