tiny-tracing

A lightweight, builder-style logging library for Rust that wraps tracing and tracing-subscriber. Designed for small to medium projects that want structured or plain-text output with zero fuss.

---

Quickstart

Add the crate to your project:

cargo add tiny-tracing

Minimal setup — text output at INFO level, nothing else needed:

use tiny_tracing::Logger;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    Logger::new().init()?;

    tiny_tracing::info!("Application started");
    Ok(())
}

Configuration

The builder API exposes every knob through chainable methods:

use tiny_tracing::{Logger, LogFormat, Level, Output};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    Logger::new()
        .with_level(Level::DEBUG)                  // TRACE | DEBUG | INFO | WARN | ERROR
        .with_format(LogFormat::Json)              // Text | Json
        .with_env_filter("info,my_crate=trace")    // per-target EnvFilter, on top of level
        .with_file(true)                           // show source file in log lines
        .with_target(false)                        // hide module path
        .with_output(Output::Both("app.log".into())) // stdout + file
        .init()?;
    Ok(())
}

Method	Default	Description
with_level(Level::DEBUG)	Level::INFO	Global log level (tracing::Level); with_env_filter refines it per-target
with_format(LogFormat::Json)	LogFormat::Text	Output format
with_env_filter("info,my_crate=debug")	none	Per-target filter via EnvFilter, layered on the level
with_file(true)	false	Show source file path in log lines
with_target(false)	true	Show module path in log lines
with_output(Output::Both("app.log".into()))	Output::Stdout	Write to stdout, a file, or both

Output destinations

with_output takes an Output: Stdout (default), File(path), or Both(path). File output is opened in append mode (created if missing) with synchronised, blocking writes — no background thread, no guard to keep alive. ANSI colours are kept on stdout but stripped from the file, so the on-disk log stays clean.

Need to load config from a string (env var, TOML)? LogFormat implements FromStr, and tracing::Level does too:

use tiny_tracing::{LogFormat, Level};

let format: LogFormat = "json".parse()?;
let level: Level = "debug".parse()?;
# Ok::<_, Box<dyn std::error::Error>>(())

Examples

Runnable examples live under examples/:

cargo run --example basic       # text output at INFO
cargo run --example json        # JSON output at DEBUG, with file locations
cargo run --example env_filter  # per-target filter (respects RUST_LOG)
cargo run --example file        # write to stdout + a file at once

Safety

The library calls tracing_subscriber::try_init() internally — calling init() more than once returns a LoggerError::TryInitError instead of panicking. No unsafe code anywhere in the crate.

License

tiny-tracing is distributed under the terms of the MIT license.

Development

git clone https://github.com/containerscrew/tiny-tracing.git
cd tiny-tracing

cargo test                                        # unit + integration + doc-tests
cargo fmt --all -- --check                        # check formatting
cargo clippy --all-targets --all-features -- -D warnings

Releases are automated via cocogitto (Conventional Commits). See the release skill for the full workflow.