log-io 2.2.0

Features

Pipeline

• Three formats - JSON Lines, logfmt, and an aligned human-readable line with optional terminal colour.
• Per-target filtering - RUST_LOG-style directives where the most specific rule wins; read them from an environment variable with env_filter.
• Ambient fields - service-level default fields and thread-local context (trace_id, request_id), de-duplicated with clear precedence.
• Several sinks per logger - stdout/stderr, buffered files, size- and time-based rotation, any io::Write, and a background writer with a bounded queue.

Ergonomics

• Macros with format! messages - info!("user {id} logged in", http.status = 200, peer = %addr), with or without an explicit logger.
• Global logger - log_io::init(logger) returns a guard that flushes at the end of main.
• Async-friendly context - capture context once and re-install it around every poll of a future, on any executor.
• log and tracing bridges - route existing ecosystem logging into log-io sinks (features log and tracing).

Safety and reliability

• Injection-safe output - C0/C1 controls, DEL, U+2028/2029 and bidi controls are escaped in every format; metadata keys cannot be spoofed by fields.
• Redaction - replace password, token, authorization and other configured keys with [REDACTED] at the logging boundary.
• Durable shutdown - flush-on-level (errors by default), flush guards, fsync on flush when you need it, and an opt-in panic hook.
• Zero unsafe code - #![forbid(unsafe_code)]; sinks recover from mutex poisoning; library code never unwraps.

Installation

[dependencies]
log-io = "2"

# Optional integrations:
log-io = { version = "2", features = [
    "log",      # route `log` macros into log-io (LogBridge)
    "tracing",  # use log-io as a tracing-subscriber layer (TracingLayer)
] }

Feature recommendations

• Applications: the defaults (std, json, logfmt, human).
• Libraries already using log or tracing: add log or tracing and keep your existing macros.
• Embedded (no_std): default-features = false, features = ["json"] (or logfmt / human) for the data model and formatters only.

Quick Start

One line installs a JSON logger on standard output (info, or the filter in LOG_IO); init_logfmt and init_human pick the other layouts:

let _guard = log_io::init_json()?;
let port = 8080_u16;
log_io::info!("listening on port {port}", tls = true);
# Ok::<(), log_io::InitError>(())

To configure it, build the logger:

use log_io::{Level, Logger};

let logger = Logger::builder()
    .level(Level::Info)
    .env_filter("LOG_IO") // e.g. LOG_IO="info,my_app::db=debug"
    .with_default_field("service", "billing")
    .stdout_json()
    .build();
let _guard = log_io::init(logger).expect("first and only global logger");

let port = 8080_u16;
log_io::info!("listening on port {port}", tls = true);
log_io::warn!(target: "my_app::db", "slow query", ms = 412_u64, table = "users");

Context across threads and async tasks

use log_io::{context, Logger};

let logger = Logger::builder().stdout_logfmt().build();
let _request = context::with_request_id("req-7");
log_io::info!(logger, "accepted"); // carries request_id=req-7

let snapshot = context::capture();
let worker = logger.clone();
std::thread::spawn(move || {
    snapshot.scope(|| log_io::info!(worker, "processing")); // carries it too
})
.join()
.unwrap();
// For futures: tokio::spawn(snapshot.wrap(async move { ... }))

Durable file output off the hot path

use log_io::format::JsonFormat;
use log_io::sink::{NonBlocking, RotatingFile, Rotation};
use log_io::{Level, Logger};

let file = RotatingFile::builder("logs/app.jsonl")
    .max_bytes(50 * 1024 * 1024)
    .rotation(Rotation::Daily)
    .max_files(14)
    .open()?;
let sink = NonBlocking::new(file, JsonFormat::new())?;
let logger = Logger::builder()
    .level(Level::Info)
    .redact_common_secrets()
    .with_sink(sink)
    .build();
let _guard = log_io::init(logger)?; // drains the queue when main returns
# Ok::<(), Box<dyn std::error::Error>>(())

Plugging into log and tracing

use log_io::compat::{LogBridge, TracingLayer};
use log_io::Logger;
use tracing_subscriber::layer::SubscriberExt;

let logger = Logger::builder().stdout_logfmt().build();
LogBridge::new(logger.clone()).install().ok();
log::info!(user = "alice"; "from the log facade");

let subscriber = tracing_subscriber::registry().with(TracingLayer::new(logger));
tracing::subscriber::with_default(subscriber, || {
    let _span = tracing::info_span!("request", id = 7_u64).entered();
    tracing::info!(status = 200_u16, "from tracing"); // carries id=7
});

Performance

Measured on an AMD Ryzen 9 9950X3D, Windows 11, rustc 1.95; see BENCH.md for the method and the full tables.

No heap allocation per record in steady state (enforced by tests/alloc.rs).

Status: Stable

Current version: 2.1.0. The API follows Semantic Versioning; Value, Error, Metadata, Record and the configuration enums are #[non_exhaustive] so they can grow in minor releases. Upgrading from 1.x: see docs/MIGRATION.md.

Planned: sampling and rate limiting per call site, OpenTelemetry-shaped JSON layouts, compression of rotated files.

Documentation & Resources

Documentation

• Documentation Index - where everything is
• API Reference - every component with runnable examples
• Migration Guide - upgrading from 1.x
• Benchmarks - method, machine and numbers
• Specification - design contract and policies
• docs.rs/log-io - generated rustdoc

Examples

Run one with cargo run --example 02_macros (add --features log or --features tracing for the last two).

Troubleshooting

Version Compatibility

• Rust: 1.85+ (edition 2024). Raising the MSRV is a major-version change.
• API stability: semantic versioning; see REPS.md section 9.
• Feature flags: additive; log and tracing are independent of each other.

Development Setup

git clone https://github.com/jamesgober/log-io.git
cd log-io
cargo test --all-features    # unit, integration, property, doc tests
cargo bench --all-features   # criterion benchmarks
cargo clippy --all-targets --all-features -- -D warnings
cargo +nightly fuzz run json_format   # see fuzz/README.md