Struct KVFilter

pub struct KVFilter<D: Drain> { /* private fields */ }

Drain filtering records using list of keys and values they must have unless they are of a higher level than filtering applied. it can apply a negative filter as well that overrides any matches but will let higher level than filtering applied as well.

This Drain filters a log entry on a filtermap that holds the key name in question and acceptable values Key values are gathered up the whole hierarchy of inherited loggers.

Example

Logger( … ; o!(“thread” => “100”); log( … ; “packet” => “send”); log( … ; “packet” => “receive”);

can be filtered on a map containing “thread” key component. If the values contain “100” the log will be output, otherwise filtered. The filtering map can contain further key “packet” and value “send”. With that the output for “receive” would be filtered.

More precisely

• a key is ignored until present in filters, otherwise an entry must match for all the keys present in filters for any of the values given for the key to pass the filter.
• an entry that hits any value of any negative filter key is filtered, this takes precedence over filters
• Behavior of empty KVFilterList is undefined but normally anything should pass.
• Behavior of KVFilter that has same key in both the matching and the suppressing section is undefined even if we have different values there. Logically, it should be matching the positive and pass and only suppress negative if it finds matching value but it’s untested.

Additionally, the resulting message (without keys and values) can be constrained by both presence of a regex or its absence by applying the only_pass_on_regex and always_suppress_on_regex API calls. As the names suggest, suppression wins if both regex’s are set.

Usage

Filtering in large systems that consist of multiple threads of same code or have functionality of interest spread across many components, modules, such as e.g. “sending packet” or “running FSM”.

Implementations

impl<'a, D: Drain> KVFilter<D>

pub fn new(drain: D, level: Level) -> Self

Create KVFilter letting e’thing pass unless filters are set. Anything more important than level will pass in any case.

• drain - drain to be sent to
• level - maximum level filtered, higher levels pass by without filtering

pub fn only_pass_any_on_all_keys(self, filters: Option<KVFilterList>) -> Self

pass through entries with all keys with any of the matching values in its entries or ignore condition if None

pub fn always_suppress_any(self, filters: Option<KVFilterList>) -> Self

suppress any key with any of the matching values in its entries or ignore condition if None. @note: This takes precedence over only_pass_any

pub fn only_pass_on_regex(self, regex: Option<Regex>) -> Self

only pass when this regex is found in the log message output.

pub fn always_suppress_on_regex(self, regex: Option<Regex>) -> Self

suppress output if this regex if found in the log message output.

Trait Implementations

impl<'a, D: Drain> Drain for KVFilter<D>

type Err = <D as Drain>::Err

Type of potential errors that can be returned by this Drain

type Ok = Option<<D as Drain>::Ok>

Type returned by this drain

fn log( &self, info: &Record<'_>, logger_values: &OwnedKVList, ) -> Result<Self::Ok, Self::Err>

Handle one logging statement (Record)

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

Avoid: Check if messages at the specified log level are maybe enabled for this logger.

fn is_critical_enabled(&self) -> bool

Avoid: See is_enabled

fn is_error_enabled(&self) -> bool

Avoid: See is_enabled

fn is_warning_enabled(&self) -> bool

Avoid: See is_enabled

fn is_info_enabled(&self) -> bool

Avoid: See is_enabled

fn is_debug_enabled(&self) -> bool

Avoid: See is_enabled

fn is_trace_enabled(&self) -> bool

Avoid: See is_enabled

fn map<F, R>(self, f: F) -> R

where Self: Sized, F: FnOnce(Self) -> R,

Pass Drain through a closure, eg. to wrap into another Drain.

fn filter<F>(self, f: F) -> Filter<Self, F>

where Self: Sized, F: FilterFn,

Filter logging records passed to Drain

fn filter_level(self, level: Level) -> LevelFilter<Self>

where Self: Sized,

Filter logging records passed to Drain (by level)

fn map_err<F, E>(self, f: F) -> MapError<Self, E>

where Self: Sized, F: MapErrFn<Self::Err, E>,

Map logging errors returned by this drain

fn ignore_res(self) -> IgnoreResult<Self>

where Self: Sized,

Ignore results returned by this drain

fn fuse(self) -> Fuse<Self>

where Self::Err: Debug, Self: Sized,

Make Self panic when returning any errors

impl<D: Drain> RefUnwindSafe for KVFilter<D>

impl<D: Drain> UnwindSafe for KVFilter<D>