Crate rlg 

RLG — Near-Lock-Free Structured Logging for Rust

rlg pushes structured log events through a 65k-slot ring buffer (LMAX 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

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

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.

Re-exports

pub use crate::error::RlgError;

pub use crate::error::RlgResult;

pub use crate::init::FlushGuard;

pub use crate::init::InitError;

pub use crate::init::RlgBuilder;

pub use crate::init::builder;

pub use crate::init::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;

pub use crate::tracing::RlgLayer;

pub use euxis_commons as commons;

Modules

config

TOML-based configuration, validation, and hot-reload. TOML-based configuration: loading, validation, diffing, and hot-reload.

engine

Ring buffer engine: ingestion, flushing, and the global ENGINE. Near-lock-free ingestion engine backed by a bounded ring buffer.

error

Error types and the RlgResult alias.

init

Zero-config init(), builder API, and FlushGuard. One-call initialization for the RLG engine.

log

Log struct, fluent builder, and per-format Display impls.

log_format

14 structured output formats (JSON, MCP, OTLP, ECS, CEF, …).

log_level

Severity levels: ALL through DISABLED, with FromStr parsing.

logger

Bridge from the log crate facade into the RLG engine. Bridge from the log crate facade into the RLG engine.

macros

Macros: rlg_span!, rlg_time_it!, rlg_mcp_notify!. Convenience macros for span tracking, latency profiling, and MCP notifications.

rotation

Log rotation policies: size, time, date, and count-based. Log rotation policies: size, time, date, and count-based.

sink

Platform-native sinks: os_log (macOS), journald (Linux), file, stdout. Platform-native logging sinks.

tracing

tracing integration: RlgSubscriber and optional RlgLayer. Integration with the tracing ecosystem.

tui

Opt-in terminal dashboard for live metrics (RLG_TUI=1). Opt-in terminal dashboard for live observability metrics.

utils

Timestamps, file I/O helpers, and input sanitization.

Macros

rlg_mcp_notify

Emit an MCP-formatted state transition notification.

rlg_span

Execute a block within an OTLP-tagged span.

rlg_time_it

Measure wall-clock latency of a block and emit a Logfmt metric.

Constants

VERSION

Crate version, injected at compile time.