Struct Logger 

pub struct Logger { /* private fields */ }

Available on crate feature std only.

The configured logging pipeline.

Build one with Logger::builder. A Logger is cheap to clone and Send + Sync; share it by cloning or install it process-wide with crate::init.

Record assembly

For each admitted record the logger:

1. stamps the wall-clock time (unless disabled);
2. collects ambient fields: default fields, then the thread’s context (crate::context), then any extra context supplied by an integration (for example tracing span fields);
3. removes duplicate keys so every key appears once in the output. Precedence is call-site fields > extra context > thread context > defaults, and within call-site fields the last one wins (as in most JSON parsers). Keys count as duplicates when the JSON and logfmt formats would write them identically, so a level field (written as fields.level) and a fields.level field collide. Records written straight to a crate::format::Format without a logger are not de-duplicated;
4. replaces the values of redacted keys with REDACTED;
5. hands the record to every sink in installation order. A failing sink does not stop the others; each failure goes to the error handler;
6. flushes every sink if the record is at or above the flush level (default Level::Error).

Steps 2-4 use stack buffers for up to 16 fields per group and do not allocate in that case.

Shutdown

When the last clone is dropped, every sink is shut down (flushed, background threads drained and joined) and failures are reported to the error handler. A logger stored in a static is never dropped: keep the crate::FlushGuard from crate::init or Logger::flush_guard alive, or call Logger::shutdown.

Examples

use log_io::{Field, Level, Logger};

let logger = Logger::builder()
    .level(Level::Info)
    .with_default_field("service", "billing")
    .stdout_json()
    .build();

logger.log(Level::Info, "ready", &[Field::new("port", 8443_u16)]);
log_io::warn!(logger, "slow query took {} ms", 1280, table = "invoices");

Implementations

impl Logger

pub fn builder() -> LoggerBuilder

Start configuring a logger. See LoggerBuilder for defaults.

pub fn threshold_for(&self, target: &str) -> Level

The filter threshold that applies to target.

pub fn enabled(&self, target: &str, level: Level) -> bool

Returns true if a record with this target and level would pass the filter. The macros call this before evaluating any field or formatting the message.

pub fn min_level(&self) -> Level

The lowest severity the filter admits for any target. A record below it is rejected without looking at its target.

pub fn filter(&self) -> &Filter

The filter in use.

pub fn sink_count(&self) -> usize

Number of installed sinks.

pub fn default_target(&self) -> &str

The target used by Logger::log (empty unless set with LoggerBuilder::default_target).

pub fn log(&self, level: Level, message: &str, fields: &[Field<'_>])

Emit a record with the logger’s default target.

Errors are passed to the error handler, not returned. Note that per-target filter rules only apply to this record if they match the default target; the macros use the calling module’s path instead.

pub fn try_log( &self, level: Level, target: &str, message: &str, fields: &[Field<'_>], ) -> Result<()>

Emit a record with an explicit target.

Errors

Returns the first sink or flush error. Every sink still receives the record, and every error is also passed to the error handler.

pub fn try_emit( &self, metadata: Metadata<'_>, message: &str, fields: &[Field<'_>], ) -> Result<()>

Lowest-level entry point: emit a record with caller-supplied metadata (for example a source location). The filter uses metadata.target and metadata.level; a timestamp is added if timestamps are enabled and metadata has none.

Errors

Same as Logger::try_log.

pub fn flush(&self) -> Result<()>

Flush every sink. Records at or above the flush level are already flushed as they are written; call this before a planned exit.

Errors

Returns the first error. Every sink is still flushed, and every error is also passed to the error handler.

pub fn shutdown(&self) -> Result<()>

Flush every sink and stop background workers, draining their queues first. The logger stays usable afterwards: sinks with a background thread write later records synchronously.

Errors

Same as Logger::flush.

pub fn flush_guard(&self) -> FlushGuard

A guard that calls Logger::shutdown when dropped. Keep it alive in main when the logger outlives main (for example in a static).

Trait Implementations

impl Clone for Logger

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Logger

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl RefUnwindSafe for Logger

impl UnwindSafe for Logger