Crate log_io 

Structured logging pipeline for Rust.

log-io moves structured log records through three stages: a Filter decides whether a record is wanted, a Format serializes it (JSON, logfmt, or a human-readable line), and one or more Sinks deliver the bytes. The steady-state hot path performs no heap allocation, the data model and formatters work under no_std, and the default build has zero dependencies. Optional bridges plug the pipeline into the log and tracing ecosystems.

Quick start

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"
    .stdout_json()
    .build();
let _guard = log_io::init(logger)?; // flushes on drop

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");

Features

Feature	Default	Enables
std	yes	Logger, sinks, context, timestamps, the global logger
json	yes	format::JsonFormat
logfmt	yes	format::LogfmtFormat
human	yes	format::HumanFormat (works under no_std)
log	no	compat::LogBridge, a log::Log implementation (adds the log crate)
tracing	no	compat::TracingLayer, a tracing-subscriber layer (adds tracing-core and tracing-subscriber)

Without std the crate is no_std (no alloc needed): Record, Field, Value, Level and the three formatters, which write to any core::fmt::Write.

Threading and async

Logger and every sink are Send + Sync. The built-in synchronous sinks write on the calling thread under a mutex, so inside an async runtime they block the executor thread for the duration of the write; sink::NonBlocking moves the write to a background thread. Context is thread-local; context::ContextSnapshot carries it into tasks and other threads.

Durability

Records at or above the flush level (default Level::Error) are flushed to every sink before the logging call returns. The one exception is a sink::NonBlocking sink with Overflow::DropNewest: it only queues that flush so the call never waits, and a FlushGuard drop or Logger::flush still drains it. Everything else may sit in a buffer until a flush, a FlushGuard drop, or the last Logger clone being dropped. See sink::FileSink for the exit paths that lose buffered data and how to avoid them.

Allocation

Emitting a record through the built-in synchronous sinks does not allocate in steady state, including timestamps, thread-local context, default fields, and format!-style messages, as long as at most 16 ambient (default + context) fields are attached. Creating a context guard, capturing a context snapshot, and queueing a record on sink::NonBlocking may allocate. tests/alloc.rs enforces this with a counting allocator.

Stability

Semantic versioning. Value, Error, Metadata, Record and the configuration enums are #[non_exhaustive], so they can grow in minor releases. See docs/MIGRATION.md for upgrading from 1.x.

Re-exports

pub use crate::format::Format;

pub use crate::global::init_human;human and std

pub use crate::global::init_json;json and std

pub use crate::global::init_logfmt;logfmt and std

pub use crate::global::FlushGuard;std

pub use crate::global::InitError;std

pub use crate::global::SetGlobalError;std

pub use crate::global::init;std

pub use crate::global::set as set_global;std

pub use crate::sink::Sink;std

Modules

compatlog or tracing

Bridges from the log and tracing ecosystems into a Logger.

contextstd

Thread-local logging context.

format

Output formats.

globalstd

The process-wide logger.

sinkstd

Output sinks.

Macros

debugstd

Emit a crate::Level::Debug record. See log_at! for the syntax.

errorstd

Emit a crate::Level::Error record. See log_at! for the syntax.

infostd

Emit a crate::Level::Info record. See log_at! for the syntax.

log_atstd

Emit a record at a runtime-chosen level.

tracestd

Emit a crate::Level::Trace record. See log_at! for the syntax.

warnstd

Emit a crate::Level::Warn record. See log_at! for the syntax.

Structs

Field

A single key-value pair attached to a Record.

Filterstd

A target-aware severity gate.

FilterRulestd

One rule in a Filter: records whose target is (or is nested under) target are admitted when their level is at least level.

Loggerstd

The configured logging pipeline.

LoggerBuilderstd

Builder for Logger. Create with Logger::builder.

Metadata

Metadata describing the origin and severity of a record.

ParseFilterErrorstd

Error returned by Filter::parse.

ParseLevelError

Error returned when a string cannot be parsed as a Level.

Record

A complete, immutable log record.

Enums

BuildErrorstd

Error returned by LoggerBuilder::try_build.

Errorstd

Errors produced by the logging pipeline.

Level

Severity of a log record.

ParseFilterErrorKindstd

What was wrong with a directive passed to Filter::parse.

Value

A field value attached to a log record.

Constants

REDACTEDstd

Value written in place of a redacted field.

VERSION

Crate version string, populated by Cargo at build time.

Type Aliases

ErrorHandlerstd

Callback invoked for every sink error, flush error, and message formatting error the logger encounters.

Resultstd

Crate result alias.