Struct LoggerBuilder 

pub struct LoggerBuilder { /* private fields */ }

Available on crate feature std only.

Builder for Logger. Create with Logger::builder.

Defaults: filter info for every target, timestamps on, thread-local context capture on, flush after every record at Level::Error or above, no default fields, no redaction, empty default target, no error handler, no sinks.

Examples

use log_io::{Level, Logger};

let logger = Logger::builder()
    .level(Level::Info)
    .env_filter("LOG_IO")              // e.g. LOG_IO="info,app::db=debug"
    .with_default_field("service", "api")
    .redact_common_secrets()
    .stderr_human()
    .try_build()?;

Implementations

impl LoggerBuilder

pub const COMMON_SECRET_KEYS: &'static [&'static str]

Key patterns redacted by LoggerBuilder::redact_common_secrets.

Each * matches any run of characters (see LoggerBuilder::redact_key), so *password* covers password, db_password and user_password_hash, and *token* covers x-auth-token and refresh_token. Matching treats - and _ alike and ignores ASCII case, so *api_key* also covers the HTTP header names Api-Key and X-Api-Key.

The patterns favour catching secrets over keeping every value: *token* also redacts a count such as token_count. Rename such fields, or list your own keys with LoggerBuilder::redact_key instead of this set. (Before 2.2 the set held exact names only.)

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

Set the default minimum severity, keeping any per-target rules.

pub fn filter(self, filter: Filter) -> Self

Replace the filter wholesale.

pub fn target_level(self, target: impl Into<String>, level: Level) -> Self

Add (or replace) a per-target rule. See Filter::with_rule.

pub fn filter_directive(self, directive: &str) -> Self

Parse directive (see Filter::parse) and replace the filter.

A blank directive (empty or whitespace only) changes nothing. An invalid directive, including one with only empty segments such as ",", keeps the previous filter and is reported by Self::try_build as BuildError::InvalidFilter; Self::build ignores it. Use Self::try_filter_directive to handle the error immediately.

pub fn try_filter_directive( self, directive: &str, ) -> Result<Self, ParseFilterError>

Parse directive and replace the filter, failing immediately on an invalid directive.

Errors

Returns the ParseFilterError from Filter::parse.

pub fn env_filter(self, var: &str) -> Self

Configure the filter from the environment variable var, using the Filter::parse directive syntax (RUST_LOG-style), for example .env_filter("LOG_IO") or .env_filter("RUST_LOG").

If the variable is unset, empty, or blank, the filter configured so far (for example by an earlier Self::level) is kept. A set value replaces the whole filter, default level included, as RUST_LOG does: LOG_IO=app::db=debug logs only app::db, so write LOG_IO=info,app::db=debug to keep info elsewhere. An invalid value (including "," and a value that is not valid Unicode) keeps the previous filter and is reported by Self::try_build.

pub fn default_target(self, target: impl Into<String>) -> Self

Target used by Logger::log, which has no target argument. Defaults to the empty string. Per-target filter rules apply to Logger::log records only through this target.

pub fn no_timestamps(self) -> Self

Do not timestamp records. By default every record gets the current wall-clock time from std::time::SystemTime.

pub fn no_context(self) -> Self

Do not attach thread-local context (crate::context).

pub fn with_default_field<'a, V: Into<Value<'a>>>( self, key: impl Into<String>, value: V, ) -> Self

Attach a field to every record, for identifiers such as service or version. Setting the same key again replaces the value. Context and call-site fields with the same key take precedence over defaults.

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

Flush every sink after each record at or above level. Default Level::Error, so errors reach the OS before the logging call returns. Level::Off disables flush-on-level; Level::Trace flushes after every record.

The flush goes through Sink::request_flush. The built-in synchronous sinks flush before the call returns. A crate::sink::NonBlocking sink with crate::sink::Overflow::Block also waits, until its queue has been written and flushed; with crate::sink::Overflow::DropNewest it only queues the request and returns at once, so the record is not yet durable when the call returns. Call Logger::flush when you need that.

pub fn redact_key(self, key: impl Into<String>) -> Self

Replace the value of every field named key with "[REDACTED]". Applies to call-site fields, context, and default fields. The message text is never inspected.

Matching is ASCII case-insensitive, treats - and _ as the same character (so api_key covers the header name Api-Key), and also tests the last dot-separated segment of a key (so password covers db.password).

A * in key matches any run of characters, including none (since 2.2): *_secret covers client_secret, db_* covers every key starting with db_, and *token* any key containing token. Without a * the key must match exactly.

Only keys are matched. A secret inside a Debug or Display value (req = ?login_form) or in the message text is not seen.

pub fn redact_common_secrets(self) -> Self

Redact every key in Self::COMMON_SECRET_KEYS.

pub fn on_error(self, handler: ErrorHandler) -> Self

Install a callback for sink, flush, and formatting errors. See ErrorHandler.

pub fn with_sink(self, sink: impl Sink + 'static) -> Self

Install a sink.

pub fn stdout<F: Format + 'static>(self, format: F) -> Self

Install a standard-output sink with format.

pub fn stderr<F: Format + 'static>(self, format: F) -> Self

Install a standard-error sink with format.

pub fn writer<W, F>(self, writer: W, format: F) -> Self

where W: Write + Send + 'static, F: Format + 'static,

Install a sink that writes to writer with format.

pub fn build(self) -> Logger

Finish configuration.

An invalid filter directive recorded by Self::filter_directive or Self::env_filter is ignored (the previous filter stays in effect); use Self::try_build to surface it.

Panics

Panics if no sink has been installed, which is a programming error rather than a runtime condition. Use Self::try_build when the sinks depend on configuration.

pub fn try_build(self) -> Result<Logger, BuildError>

Finish configuration, reporting problems as values.

Errors

• BuildError::NoSink if no sink was installed.
• BuildError::InvalidFilter if a filter directive (including one read from the environment) failed to parse.

impl LoggerBuilder

pub fn stdout_json(self) -> Self

Available on crate feature json only.

Install a standard-output sink with crate::format::JsonFormat.

pub fn stderr_json(self) -> Self

Available on crate feature json only.

Install a standard-error sink with crate::format::JsonFormat.

impl LoggerBuilder

pub fn stdout_logfmt(self) -> Self

Available on crate feature logfmt only.

Install a standard-output sink with crate::format::LogfmtFormat.

pub fn stderr_logfmt(self) -> Self

Available on crate feature logfmt only.

Install a standard-error sink with crate::format::LogfmtFormat.

impl LoggerBuilder

pub fn stdout_human(self) -> Self

Available on crate feature human only.

Install a standard-output sink with crate::format::HumanFormat, coloured when standard output is a terminal (see crate::format::ColorChoice::Auto).

pub fn stderr_human(self) -> Self

Available on crate feature human only.

Install a standard-error sink with crate::format::HumanFormat, coloured when standard error is a terminal (see crate::format::ColorChoice::Auto).

Trait Implementations

impl Debug for LoggerBuilder

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

Formats the value using the given formatter.