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.15"

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

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

[dev-dependencies]
rlg-test   = "0.0.15"  # 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.88.0 or newer (edition 2024). CI builds every library and binary on 1.88.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.15, 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 release may break, and it has one maintainer.

Development

make verify   # everything CI runs on a pull request
make demo     # re-render .github/demo.gif from .github/demo.tape

DEVELOPMENT.md lists every gate with its local command: Miri, Loom and Kani for the engine's concurrency and memory safety, four fuzz targets, cargo-deny and cargo-vet for the dependency tree, cargo-semver-checks, a 95% coverage floor and complexity ceilings. Contribution and signing rules are in CONTRIBUTING.md and AGENTS.md.

Security

• Reporting: privately, by email or GitHub's advisory form; never in a public issue. The process and response time are in SECURITY.md.
• Memory safety: unsafe is denied across the workspace except the documented macOS os_log FFI in crates/rlg/src/sink.rs. The engine runs under Miri on every push.
• Resource limits: the ring buffer is bounded at 65,536 records and evicts the oldest when full; rlg-otlp caps a collector's response headers at 16 KiB and times out every request.
• Fuzzing: four cargo-fuzz targets (record parsing, format names, config loading, redaction) run on every pull request; see docs/OSS-FUZZ.md for OSS-Fuzz status.
• Supply chain: every dependency passes cargo-deny and cargo-vet; releases publish through crates.io Trusted Publishing with sigstore-signed SBOMs (pkg/VERIFY.md).

Report vulnerabilities according to SECURITY.md.

Documentation

Stability guarantees

• SemVer axis: rlg is at 0.0.x, so under Cargo's rules every release may be breaking. Breaking changes are marked Breaking in the CHANGELOG, and cargo-semver-checks runs on every pull request so none slips through unannounced.
• Output stability: the bytes a format produces are an interface. A change to them for the same record is breaking even when no signature moves, and is recorded the same way.
• Minimum toolchain: Rust 1.88.0, enforced in CI; a rise is its own CHANGELOG entry with the reason. docs/POLICIES.md has the full policy.

License

Dual-licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option. Unless you state otherwise, any contribution you submit for inclusion in rlg is dual-licensed as above, without additional terms.