Struct Logger 

pub struct Logger { /* private fields */ }

Builder for initializing the global tracing subscriber.

Uses a fluent builder pattern to configure log level, output format, and optional environment-based filtering before calling init.

Examples

Minimal setup (text output at INFO level):

use tiny_tracing::Logger;

let _guard = Logger::new().init().unwrap();
tiny_tracing::info!("Ready");

JSON output with environment filter:

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

let _guard = Logger::new()
    .with_level(Level::DEBUG)
    .with_format(LogFormat::Json)
    .with_env_filter("info,my_crate=trace")
    .init()
    .unwrap();

Implementations

impl Logger

pub fn new() -> Self

Creates a new Logger with default values.

Defaults: Level::INFO, LogFormat::Text, no env filter, file location off, target on, timestamps on, output to stdout, colours chosen automatically.

Examples found in repository

examples/basic.rs (line 8)

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

    info!("hello from tiny-tracing");
    Ok(())
}

examples/colored.rs (line 8)

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

    info!("hello from tiny-tracing");

    Ok(())
}

examples/no_timestamp.rs (line 9)

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

    info!("this line has no timestamp");
    Ok(())
}

examples/stderr.rs (line 9)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new().with_output(Output::Stderr).init()?;

    info!("this log line goes to stderr");
    println!("this is program output, on stdout");

    Ok(())
}

examples/file.rs (line 11)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new()
        .with_output(Output::Both("app.log".into()))
        .init()?;

    info!("this line goes to both stdout and app.log");
    warn!(file = "app.log", "check the file for a colour-free copy");
    Ok(())
}

examples/json.rs (line 8)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new()
        .with_level(Level::DEBUG)
        .with_format(LogFormat::Json)
        .with_file(true)
        .init()?;

    info!(user_id = 42, action = "login", "structured event");
    warn!("something worth a second look");
    Ok(())
}

Additional examples can be found in:

• examples/env_filter.rs
• examples/env_filter_from_env.rs

pub fn with_level(self, level: Level) -> Self

Sets the global (default) log level.

This is the base level applied to every target. Per-target directives passed to with_env_filter refine it on top — the level is never silently ignored. A global directive inside the env filter string (e.g. the info in "info,my_crate=debug") does take precedence over this value.

Examples found in repository

examples/json.rs (line 9)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new()
        .with_level(Level::DEBUG)
        .with_format(LogFormat::Json)
        .with_file(true)
        .init()?;

    info!(user_id = 42, action = "login", "structured event");
    warn!("something worth a second look");
    Ok(())
}

examples/env_filter_from_env.rs (line 13)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new()
        .with_level(Level::DEBUG)
        .with_env_filter_from_env()
        .init()?;

    warn!("warn line — visible unless RUST_LOG is set to error");
    info!("info line — visible at INFO or lower");
    debug!("debug line — visible by default, hidden by RUST_LOG=info");
    trace!("trace line — needs RUST_LOG=trace");
    Ok(())
}

pub fn with_format(self, format: LogFormat) -> Self

Sets the output format.

Examples found in repository

examples/json.rs (line 10)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new()
        .with_level(Level::DEBUG)
        .with_format(LogFormat::Json)
        .with_file(true)
        .init()?;

    info!(user_id = 42, action = "login", "structured event");
    warn!("something worth a second look");
    Ok(())
}

pub fn with_env_filter_from_env(self) -> Self

Reads the filter directives from the RUST_LOG environment variable.

When RUST_LOG is set (and valid UTF-8) it is used exactly as if it had been passed to with_env_filter, replacing any filter set earlier. When it is not set, nothing changes and only the with_level value (plus any earlier env filter) applies. A RUST_LOG that EnvFilter rejects makes init return LoggerError::InvalidEnvFilter.

The precedence rules of with_level apply: a global directive inside RUST_LOG (e.g. RUST_LOG=warn) takes precedence over the configured level.

Examples found in repository

examples/env_filter_from_env.rs (line 14)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new()
        .with_level(Level::DEBUG)
        .with_env_filter_from_env()
        .init()?;

    warn!("warn line — visible unless RUST_LOG is set to error");
    info!("info line — visible at INFO or lower");
    debug!("debug line — visible by default, hidden by RUST_LOG=info");
    trace!("trace line — needs RUST_LOG=trace");
    Ok(())
}

pub fn colored(self, colored: bool) -> Self

Forces ANSI colours on or off for stdout or stderr.

By default colours are chosen automatically (on only when the stream being written to, stdout or stderr, is a terminal). File output is never coloured, regardless of this setting.

Examples found in repository

examples/colored.rs (line 8)

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

    info!("hello from tiny-tracing");

    Ok(())
}

pub fn with_env_filter(self, filter: impl Into<String>) -> Self

Adds environment-based, per-target filtering via EnvFilter.

The directives here are layered on top of the global with_level value. Supported syntax: "info", "info,my_crate=debug", etc.

To take the directives from RUST_LOG instead of passing them in code, use with_env_filter_from_env.

If not called, only the static with_level value applies.

Examples found in repository

examples/env_filter.rs (line 11)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let filter = std::env::var("RUST_LOG").unwrap_or_else(|_| "info,env_filter=debug".to_string());

    let _guard = Logger::new().with_env_filter(filter).init()?;

    info!("info line — always visible");
    debug!("debug line — visible when this crate is at DEBUG or lower");
    trace!("trace line — needs RUST_LOG=trace or similar");
    Ok(())
}

pub fn with_file(self, enabled: bool) -> Self

Controls whether the source file name appears in log lines.

Disabled by default.

Examples found in repository

examples/json.rs (line 11)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new()
        .with_level(Level::DEBUG)
        .with_format(LogFormat::Json)
        .with_file(true)
        .init()?;

    info!(user_id = 42, action = "login", "structured event");
    warn!("something worth a second look");
    Ok(())
}

pub fn with_timestamp(self, enabled: bool) -> Self

Controls whether each log line starts with a timestamp.

Enabled by default. When on, timestamps are always UTC and formatted as RFC 3339 with a sub-second fraction (e.g. 2026-10-01T12:00:00.123456Z), in both text and JSON output. Trailing zeros of the fraction are trimmed, so its length varies. Turn it off when something else already adds one, such as journald or a container runtime.

Examples found in repository

examples/no_timestamp.rs (line 9)

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

    info!("this line has no timestamp");
    Ok(())
}

pub fn with_target(self, enabled: bool) -> Self

Controls whether the module path (target) appears in log lines.

Enabled by default.

pub fn with_output(self, output: Output) -> Self

Sets where log lines are written: stdout, stderr, a file, or stdout and a file.

Defaults to Output::Stdout. When a file is involved it is opened in append mode (created if missing), so the call stays panic-free — an unopenable path yields LoggerError::OpenLogFile from init.

File writes are non-blocking: lines are queued and written by a background thread owned by the LoggerGuard that init returns, which must be kept alive. The queue holds up to 128 000 lines and no line is ever dropped; if it fills up, the logging call waits for room.

Writes to stdout and stderr are synchronous: each log line is written on the calling thread, which waits until the write finishes.

Examples found in repository

examples/stderr.rs (line 9)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new().with_output(Output::Stderr).init()?;

    info!("this log line goes to stderr");
    println!("this is program output, on stdout");

    Ok(())
}

examples/file.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new()
        .with_output(Output::Both("app.log".into()))
        .init()?;

    info!("this line goes to both stdout and app.log");
    warn!(file = "app.log", "check the file for a colour-free copy");
    Ok(())
}

pub fn level(&self) -> Level

Returns the configured log level.

pub fn format(&self) -> LogFormat

Returns the configured output format.

pub fn init(self) -> Result<LoggerGuard, LoggerError>

Initializes the global tracing subscriber.

Consumes the builder. Must be called only once per process; subsequent calls return LoggerError::TryInitError.

Returns a LoggerGuard that must be kept alive for as long as logging is needed: dropping it flushes and stops the background file writer.

Errors

• LoggerError::InvalidEnvFilter if an env filter was set and EnvFilter rejects it.
• LoggerError::OpenLogFile if a file output was requested but the path could not be opened for writing.
• LoggerError::TryInitError if a global subscriber is already set.

Examples found in repository

examples/basic.rs (line 8)

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

    info!("hello from tiny-tracing");
    Ok(())
}

examples/colored.rs (line 8)

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

    info!("hello from tiny-tracing");

    Ok(())
}

examples/no_timestamp.rs (line 9)

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

    info!("this line has no timestamp");
    Ok(())
}

examples/stderr.rs (line 9)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new().with_output(Output::Stderr).init()?;

    info!("this log line goes to stderr");
    println!("this is program output, on stdout");

    Ok(())
}

examples/file.rs (line 13)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new()
        .with_output(Output::Both("app.log".into()))
        .init()?;

    info!("this line goes to both stdout and app.log");
    warn!(file = "app.log", "check the file for a colour-free copy");
    Ok(())
}

examples/json.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _guard = Logger::new()
        .with_level(Level::DEBUG)
        .with_format(LogFormat::Json)
        .with_file(true)
        .init()?;

    info!(user_id = 42, action = "login", "structured event");
    warn!("something worth a second look");
    Ok(())
}

Additional examples can be found in:

• examples/env_filter.rs
• examples/env_filter_from_env.rs

Trait Implementations

impl Default for Logger

fn default() -> Self

Returns the “default value” for a type.