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.

[!NOTE] AI coding assistants are used in this project mainly for best-practice and design guidance (through the agent skills listed below), to keep the library as simple and productive as possible, and above all to document its functions.

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_env_filter_from_env()            // or read it from RUST_LOG instead
        .with_file(true)                           // show source file in log lines
        .with_target(false)                        // hide module path
        .with_timestamp(false)                     // omit the timestamp (default: on, UTC RFC 3339)
        .with_output(Output::Both("app.log".into())) // stdout + file
        .colored(false)                            // force ANSI colours off (default: auto)
        .init()?;
    Ok(())
}

Output destinations

with_output takes an Output: Stdout (default), Stderr, File(path), or Both(path) (stdout plus a file). Use Stderr in command-line tools so stdout stays free for program output. File output is opened in append mode (created if missing) with synchronised, blocking writes — no background thread, no guard to keep alive.

Colours

By default ANSI colours are used only when the stream being written to is a terminal, so piped output, Docker and CI logs stay free of escape codes. Call colored(true) or colored(false) to override that. File output is never coloured, whatever you choose. The NO_COLOR environment variable is not read; use colored(false) if you want to honour it yourself.

Timestamps

By default every log line carries an RFC 3339 timestamp in UTC (for example 2026-10-01T12:00:00.123456Z), in both text and JSON output. The sub-second fraction has a variable length because trailing zeros are trimmed. Local time is not supported, so lines from different hosts are easy to correlate.

Call with_timestamp(false) to leave the timestamp out, for example when journald or your container runtime already adds its own. In JSON output the timestamp field is then omitted too.

Environment filter

with_env_filter("info,my_crate=debug") takes the directives as a string. with_env_filter_from_env() reads them from RUST_LOG instead. If RUST_LOG is unset only the level applies, and an invalid value makes init() return LoggerError::InvalidEnvFilter. A global directive in the filter (such as RUST_LOG=warn) takes precedence over with_level.

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 passed as a string
cargo run --example env_filter_from_env  # filter read from RUST_LOG
cargo run --example file        # write to stdout + a file at once
cargo run --example colored     # force ANSI colours off
cargo run --example no_timestamp  # omit the timestamp
cargo run --example stderr      # log to stderr, keep stdout for program output

Limitations

tiny-tracing is deliberately a thin wrapper, so some things are left out on purpose:

• File writes are blocking. Each log line is written synchronously under a mutex, with no background thread. That is fine for small and medium workloads, but heavy logging from many threads or from async tasks can contend on the lock. If you need non-blocking writes, use tracing-appender with tracing-subscriber directly.
• No file rotation. The log file is only ever appended to and grows without bound. Rotate it externally (for example with logrotate) or use tracing-appender's rolling files.
• In containers, log to stdout. In Docker, Kubernetes or systemd, keep the default Output::Stdout and let the platform collect and rotate the logs, rather than writing files inside the container. LogFormat::Json is usually the best fit for log aggregators, and colours switch off by themselves because stdout is not a terminal. Use Output::Stderr instead for command-line tools whose stdout carries data.

Planned improvements are tracked in roadmap.md.

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.

To report a vulnerability, see the security policy.

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.

Minimum supported Rust version (MSRV)

rust-version in Cargo.toml is the oldest Rust the crate promises to build with. It is independent of rust-toolchain.toml, which only pins the toolchain used for development. CI checks it with the msrv job. After bumping dependencies or adding code that needs a newer compiler, measure the real minimum with cargo-msrv:

cargo install cargo-msrv --locked
cargo msrv find        # tries older toolchains until the build breaks

Then update rust-version in Cargo.toml, the MSRV badge at the top of this file and the msrv job in .github/workflows/ci.yml to the same version.

Agent skills

AI coding agents working on this repo use these third-party skills (installed under .claude/skills/, pinned in skills-lock.json):

npx skills add trailofbits/skills@cargo-fuzz               # fuzzing Rust code with cargo-fuzz
npx skills add apollographql/skills@rust-best-practices    # idiomatic Rust guidelines
npx skills add openai/skills@security-ownership-map        # security-oriented ownership / bus-factor analysis
npx skills add vercel-labs/skills@find-skills              # discover and install other skills

The release skill is specific to this repo and not installed from anywhere.