log-io 1.0.0

Structured logging pipeline for Rust. Zero-allocation fast path, JSON / logfmt / human-readable outputs, context propagation (request-id, trace-id), per-module filtering, async-safe sinks. An IO pipeline for log records, not a wrapper around log+tracing.
Documentation
  • Coverage
  • 100%
    74 out of 74 items documented5 out of 22 items with examples
  • Size
  • Source code size: 238.91 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 2.24 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 4s Average build duration of successful builds.
  • all releases: 4s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • jamesgober/log-io
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • jamesgober

Overview

log-io is a structured logging pipeline for Rust. It is not a wrapper around log or tracing. A record flows through three composable stages: filter, format, sink. The fast path is allocation-free; the data model is no_std-compatible; the crate has zero runtime dependencies.

Install

[dependencies]
log-io = "1"

Quick start

use log_io::{Level, Logger};

let logger = Logger::builder()
    .level(Level::Info)
    .stdout_json()
    .build();

log_io::info!(logger, "server started", port = 8080_u32);
log_io::warn!(logger, "slow request", path = "/api/users", ms = 412_u64);

Features

  • Three output formats: JSON (line-delimited), logfmt (key=value), human-readable (timestamp + aligned level column).
  • Per-target filtering: info, app::auth=debug, hyper=off style directives, prefix-matched on :: and . boundaries.
  • Thread-local context: stash trace_id / request_id once at the request boundary; every downstream record carries them.
  • Per-logger default fields: attach service / version / region once at builder time; every record carries them.
  • Multi-sink fan-out: human format on stderr for developer eyes and JSON to a file for ingest, served from one logger.
  • Source location capture: macros attach file!(), line!(), and module_path!() to every record.
  • Zero runtime dependencies: depends only on core and std.
  • no_std-compatible data model: the Record / Format layer compiles without std and can be wired to embedded core::fmt::Write destinations.
  • #![forbid(unsafe_code)] crate-wide.

Performance

Workload ns / record
JSON, 5 fields, formatter only ~131
logfmt, 5 fields, formatter only ~159
human, 5 fields, formatter only ~210
Pipeline, 3 fields, JSON + writer ~59
Pipeline, filtered out below thresh ~1

Single-thread throughput is ~15 M records/sec to a discarding writer; scales to ~28 M at four threads. See BENCH.md for the full methodology.

Documentation

Examples

The examples/ directory contains runnable demos:

Example Topic
basic Minimal usage with the human format.
json JSON output to stdout using macros.
context Thread-local trace / request ID propagation.
filter Directive-style per-target filtering.
file_sink Writing records to a file.
multi_sink Fanning out one record to several destinations.
custom_format Implementing the Format trait yourself.
custom_sink Implementing the Sink trait yourself.
default_fields Service-level fields attached once at builder time.

Run any of them with cargo run --example <name>.

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.