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
Operational
Install
As a Rust library
[dependencies]
rlg = "0.0.16"
Satellites install the same way, all at the same version:
[dependencies]
rlg-otlp = "0.0.16" # ship records to an OpenTelemetry Collector
rlg-tower = "0.0.16" # per-request access logs for tower services
rlg-redact = "0.0.16" # scrub secrets and PII before they are written
[dev-dependencies]
rlg-test = "0.0.16" # 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.16, released together.
| Component | Purpose | Use case |
|---|
rlg | The engine: 65,536-slot ring buffer, background flusher, 14 formats, native sinks | Structured logging in any Rust program |
rlg-cli | The rlg binary: filter by level, component or attribute, convert between formats | my-service | rlg --min-level error --format ecs |
rlg-report | The rlg-report binary and library: counts by level and component, top messages, latency percentiles | On-call triage, daily error digests |
rlg-mcp | MCP server: four tools, one prompt, two resources over stdio, streamable HTTP or HTTP+SSE | AI agents reading production logs |
rlg-otlp | OTLP/HTTP exporter to a local OpenTelemetry Collector | Honeycomb, Datadog, Grafana through a Collector |
rlg-redact | Scrubs cards, JWTs, bearer tokens, emails, IPv4 addresses and AWS keys in one pass | GDPR and audit-trail safety |
|
Capabilities at a glance
| Area | Capability | Status |
|---|
| Ingestion | Atomic level filter, ring-buffer push, no lock on the caller's thread | Stable |
| Formats | JSON, NDJSON, ECS, GELF, Logstash, OTLP, MCP, logfmt, CLF, CEF, ELF, W3C, Apache, Log4j XML | Stable |
| Sinks | os_log (macOS), journald (Linux), file, stdout | Stable |
| Sinks | io_uring file sink (Linux, uring feature) | Scaffold |
| Configuration | TOML load, validation, polling hot-reload (tokio feature) | Stable |
| Bridges | log facade via rlg::init(); tracing layer (tracing-layer feature) | Stable |
| Export | OTLP/HTTP to a local Collector (rlg-otlp) | Stable |
| Agents | MCP server over stdio, streamable HTTP and HTTP+SSE (rlg-mcp) | Stable |
| Enrichment | eBPF kernel context (rlg-ebpf, Linux) | Scaffold |
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.
| Project | Formatting off the caller's thread | Built-in formats | Native journald / os_log |
|---|
| rlg | yes | 14 | yes |
tracing + tracing-subscriber | add-on | text, JSON | add-on |
slog | add-on | add-on | add-on |
log + env_logger | no | text | no |
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.
| Scenario | Result | Environment |
|---|
rlg fire(), one record | 598 ns | GitHub-hosted ubuntu-latest, release profile |
tracing::info! to a discarding writer | 591 ns | same run |
rlg fire() with 3 attributes | 947 ns (tracing: 1,117 ns) | same run |
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.
| Feature | Crate | Adds |
|---|
tokio | rlg | Config::load_async and polling hot-reload |
tui | rlg | A live terminal dashboard, started with RLG_TUI=1 |
tracing-layer | rlg | RlgLayer, a tracing_subscriber::Layer |
fast-queue | rlg | An eight-shard ring buffer for many concurrent producers |
uring | rlg | The io_uring file sink on Linux |
async | rlg-otlp | AsyncOtlpExporter on Tokio |
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
| Example | Shows | Run |
|---|
example_log_format | All 14 formats side by side | cargo run -p rlg --example example_log_format |
example_config | TOML config, async load, hot-reload | cargo run -p rlg --example example_config --features tokio |
example_macros | The logging macros | cargo run -p rlg --example example_macros |
serve_a_session | A full MCP session against rlg-mcp | cargo run -p rlg-mcp --example serve_a_session |
honeycomb | Exporting through a local Collector | cargo run -p rlg-otlp --example honeycomb |
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.89.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
at your option. Unless you state otherwise, any contribution you submit
for inclusion in rlg is dual-licensed as above, without additional terms.
