Rlg MCP

rlg

Near-lock-free structured logging for Rust: records leave the application thread with a few atomic operations and are formatted and written by a background flusher.

---

Contents

Getting started

• Install — Cargo for the libraries, cargo install for the CLIs and the MCP server
• Requirements — toolchain floor, platforms
• Quick Start — one structured record, fired and flushed

The rlg ecosystem

• The rlg ecosystem — rlg, rlg-cli, rlg-report, rlg-mcp, rlg-otlp, rlg-redact, rlg-tower, rlg-test, rlg-wasm, rlg-ebpf

Library reference

• Capabilities at a glance — the current surface by theme
• Ecosystem comparison — short matrix; full table at docs/COMPARISON.md
• Benchmarks — headline numbers; full table at docs/BENCHMARKS.md
• Features — module-level capability list
• Configuration — core options
• Examples — runnable example index

Operational

• When not to use rlg — limitations
• Development — make targets, fuzzing, CI
• Security — guarantees and compliance
• Documentation — all reference docs
• Stability guarantees — SemVer axis, output stability, minimum toolchain discipline
• License

---

Install

As a Rust library

[dependencies]

rlg = "0.0.18"

Satellites install the same way, all at the same version:

[dependencies]

rlg-otlp = "0.0.18" # ship records to an OpenTelemetry Collector rlg-tower = "0.0.18" # per-request access logs for tower services rlg-redact = "0.0.18" # scrub secrets and PII before they are written

[dev-dependencies] rlg-test = "0.0.18" # assert on captured records in tests

Command-line tools

cargo install rlg-cli      # `rlg`: filter and convert log files

cargo install rlg-report # rlg-report: summaries by level, component and message cargo install rlg-mcp # rlg-mcp: log files as tools for AI agents

From a checkout, make install builds the three binaries and installs them with their manpages and bash, zsh and fish completions under /usr/local (PREFIX and DESTDIR are honoured; make uninstall reverses it). The binaries generate both themselves: rlg --manpage > rlg.1, rlg --completions zsh > _rlg.

rlg-mcp is also published as a container image, ghcr.io/sebastienrousseau/rlg-mcp, and listed in the MCP registry.

---

Requirements

• Rust 1.89.0 or newer (edition 2024). CI builds every library and binary on 1.89.0; see the toolchain policy.
• macOS or Linux for the native sinks (os_log, journald). Everywhere else, including Windows, rlg writes to a file or stdout.

---

Quick Start

use rlg::log::Log;

use rlg::log_format::LogFormat;

fn main() { // Keep the guard for the life of the program: dropping it flushes // pending records and stops the background thread. let _guard = rlg::init().unwrap();

Log::info("User authenticated") .component("auth-service") .with("user_id", 42) .format(LogFormat::JSON) .fire(); }

fire() checks the level, pushes the record into a ring buffer and returns; the flusher thread formats it as JSON and writes it to the platform sink. This block is compiled and run by cargo test.

---

The rlg ecosystem

Ten crates at lockstep version 0.0.18, released together.

---

Capabilities at a glance

---

Ecosystem comparison

rlg trades tracing's span model for an event-only engine that keeps formatting and I/O off the application thread and ships native sinks, many formats and an agent interface in the box.

See docs/COMPARISON.md for the evidence and complete matrix.

---

Benchmarks

The competitive_bench suite times rlg's fire() against tracing::info! and log::info! for single records, records with attributes, 10,000-record bursts and latency distribution. It runs in CI on every release tag, and its results are published as workflow artifacts.

On the calling thread rlg now costs about what tracing costs, without formatting there; what it buys is that the caller never waits on the sink's I/O.

See docs/BENCHMARKS.md for methodology and full results.

---

Features

Everything optional is off by default.

---

Configuration

Config loads from TOML, validates, and creates the log paths it needs.

# rlg.toml

version = "1.0" profile = "production" log_file_path = "/var/log/rlg.log" log_level = "INFO" logging_destinations = [ { type = "File", value = "/var/log/rlg.log" }, { type = "Stdout" }, ] log_rotation = { Size = 10485760 } # 10 MiB

Load it with Config::load(Some("rlg.toml")), or with the tokio feature Config::load_async, and follow edits with Config::hot_reload_async. RUST_LOG sets the level too. The crate README lists every field.

---

Examples

CI runs every example on each pull request (examples-smoke.yml), except example_config and example_utils, async demos whose behaviour the crate's own tests cover.

---

When not to use rlg

• Low volume. Below about a hundred records a second, a background thread and a 65k-slot buffer buy nothing a synchronous logger does not already give you.
• Spans are your model. rlg records events. If hierarchical spans are what you analyse, use tracing directly; rlg's layer only bridges its events.
• Windows Event Log. There is no native Windows sink; rlg writes to a file or stdout there.
• Every record must survive a crash. Records wait in memory until the flusher writes them; a process killed before the FlushGuard drops loses what is still buffered.
• You need a stable API. rlg is at 0.0.x: any r