Struct Builder

pub struct Builder { /* private fields */ }

Available on crate features env-filter and std only.

A builder for constructing new EnvFilters.

Implementations

impl Builder

pub fn with_regex(self, regex: bool) -> Self

Sets whether span field values can be matched with regular expressions.

If this is true, field filter directives will be interpreted as regular expressions if they are not able to be interpreted as a bool, i64, u64, or f64 literal. If this is false, those field values will be interpreted as literal std::fmt::Debug output instead.

By default, regular expressions are enabled.

Note: when EnvFilters are constructed from untrusted inputs, disabling regular expressions is strongly encouraged.

pub fn with_default_directive(self, default_directive: Directive) -> Self

Sets a default [filtering directive] that will be added to the filter if the parsed string or environment variable contains no filter directives.

By default, there is no default directive.

Examples

If parse, parse_lossy, from_env, or from_env_lossy are called with an empty string or environment variable, the default directive is used instead:

use tracing_subscriber::filter::{EnvFilter, LevelFilter};

let filter = EnvFilter::builder()
    .with_default_directive(LevelFilter::INFO.into())
    .parse("")?;

assert_eq!(format!("{}", filter), "info");

Note that the lossy variants (parse_lossy and from_env_lossy) will ignore any invalid directives. If all directives in a filter string or environment variable are invalid, those methods will also use the default directive:

use tracing_subscriber::filter::{EnvFilter, LevelFilter};

let filter = EnvFilter::builder()
    .with_default_directive(LevelFilter::INFO.into())
    .parse_lossy("some_target=fake level,foo::bar=lolwut");

assert_eq!(format!("{}", filter), "info");

If the string or environment variable contains valid filtering directives, the default directive is not used:

use tracing_subscriber::filter::{EnvFilter, LevelFilter};

let filter = EnvFilter::builder()
    .with_default_directive(LevelFilter::INFO.into())
    .parse_lossy("foo=trace");

// The default directive is *not* used:
assert_eq!(format!("{}", filter), "foo=trace");

Parsing a more complex default directive from a string:

use tracing_subscriber::filter::{EnvFilter, LevelFilter};

let default = "myapp=debug".parse()
    .expect("hard-coded default directive should be valid");

let filter = EnvFilter::builder()
    .with_default_directive(default)
    .parse("")?;

assert_eq!(format!("{}", filter), "myapp=debug");

pub fn with_env_var(self, var: impl ToString) -> Self

Sets the name of the environment variable used by the from_env, from_env_lossy, and try_from_env methods.

By default, this is the value of EnvFilter::DEFAULT_ENV (RUST_LOG).

pub fn parse_lossy<S: AsRef<str>>(&self, dirs: S) -> EnvFilter

Returns a new EnvFilter from the directives in the given string, ignoring any that are invalid.

pub fn parse<S: AsRef<str>>(&self, dirs: S) -> Result<EnvFilter, ParseError>

Returns a new EnvFilter from the directives in the given string, or an error if any are invalid.

pub fn from_env_lossy(&self) -> EnvFilter

Returns a new EnvFilter from the directives in the configured environment variable, ignoring any directives that are invalid.

pub fn from_env(&self) -> Result<EnvFilter, FromEnvError>

Returns a new EnvFilter from the directives in the configured environment variable. If the environment variable is unset, no directive is added.

An error is returned if the environment contains invalid directives.

pub fn try_from_env(&self) -> Result<EnvFilter, FromEnvError>

Returns a new EnvFilter from the directives in the configured environment variable, or an error if the environment variable is not set or contains invalid directives.

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Builder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Builder

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

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Self

Returns the “default value” for a type.