Struct Filter

Source

pub struct Filter { /* private fields */ }

Available on crate feature std only.

Expand description

A target-aware severity gate.

§Examples

use log_io::{Filter, Level};

// Order does not matter: the most specific rule always wins.
let f = Filter::parse("info, app::db=trace, app=warn")?;
assert!(f.is_enabled("app::db::pool", Level::Trace));
assert!(!f.is_enabled("app::http", Level::Info));
assert!(f.is_enabled("hyper", Level::Info));

Implementations§

Source §

impl Filter

Source

pub fn new(default_level: Level) -> Self

New filter with a default minimum severity and no overrides.

Source

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

Add (or replace) the rule for target.

Rules may be added in any order; matching always picks the most specific one. Adding a second rule for the same target replaces the first. Unlike Filter::parse, the target is not validated: an empty target matches only records whose target is empty (which is what crate::Logger::log uses unless a default target is configured).

Source

pub fn default_level(&self) -> Level

The default severity, applied when no rule matches.

Source

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

Replace the default severity, keeping every rule.

Source

pub fn rules(&self) -> &[FilterRule]

The configured rules, most specific (longest target) first.

Source

pub fn min_level(&self) -> Level

The lowest severity this filter can admit for any target. Records below it are rejected without examining their target.

Source

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

Decide whether a record at level for target is admitted.

Source

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

The threshold that applies to target: the level of the most specific matching rule, or the default.

Source

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

Parse a directive string such as info,app::auth=debug,hyper=off.

The grammar is a comma-separated list of segments. Each segment is either a bare level (sets the default) or target=level (adds a rule). Whitespace around segments, targets and levels is ignored, and empty segments (a=info,,b=warn) are skipped. Level names are case-insensitive and accept the aliases warning and err. When a level or a target appears more than once, the last occurrence wins. If no bare level is given, the default is Level::Off: only the listed targets are logged.

Differences from env_logger: a bare word must be a level (a bare target such as my_crate is rejected rather than meaning “everything for my_crate”, so a misspelt level is reported instead of silently becoming a target), and the /regex message filter is not supported.

§Errors

Returns ParseFilterError identifying the offending segment when the input has no segment (empty, blank, or only commas such as ","), a level is unknown, a target is empty (=debug), a target contains whitespace, or a target ends with a separator (app::=debug, app.=debug).

§Examples

use log_io::{Filter, Level, ParseFilterErrorKind};

let f = Filter::parse("warn,app=debug")?;
assert_eq!(f.default_level(), Level::Warn);

let err = Filter::parse("info,app=loud").unwrap_err();
assert_eq!(err.kind(), ParseFilterErrorKind::InvalidLevel);
assert_eq!(err.segment(), "app=loud");