Struct LoggerBuilder

Source

pub struct LoggerBuilder { /* private fields */ }

Available on crate feature std only.

Expand description

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§

Source §

impl LoggerBuilder

Source

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

Keys redacted by LoggerBuilder::redact_common_secrets.

Matching treats - and _ alike, so api_key also covers the HTTP header names api-key and x-api-key (via x_api_key), and set_cookie covers set-cookie. Matching is otherwise exact: user_password is not covered by password; add such keys with LoggerBuilder::redact_key.

Source

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

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

Source

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

Replace the filter wholesale.

Source

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

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

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn no_timestamps(self) -> Self

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

Source

pub fn no_context(self) -> Self

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

Source

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.

Source

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.

Source

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).

Source

pub fn redact_common_secrets(self) -> Self

Redact every key in Self::COMMON_SECRET_KEYS.

Source

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

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

Source

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

Install a sink.

Source

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

Install a standard-output sink with format.

Source

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

Install a standard-error sink with format.

Source

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.

Source

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.

Source

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.

Source §