Struct Filter

pub struct Filter { /* private fields */ }

A filter matching tracing-subscriber’s legacy EnvFilter format.

Example

Use the RUST_LOG filter if it is set, but provide a fallback filter if the environment variable is not set.

let (filter, diagnostics) = Filter::from_default_env()
    .unwrap_or_else(|| Filter::parse("noisy_crate=warn,info"));

tracing_subscriber::registry()
    .with(filter.layer())
    .with(tracing_subscriber::fmt::layer())
    .init();

if let Some(diagnostics) = diagnostics {
    if let Some(error) = diagnostics.error(DiagnosticsTheme::default()) {
        error!("{error}");
    }
    if let Some(warn) = diagnostics.warn(DiagnosticsTheme::default()) {
        warn!("{warn}");
    }
}

Implementations

impl Filter

pub fn parse(spec: &str) -> (Filter, Option<Diagnostics<'_>>)

Parse a filter from its string representation.

Filter compilation can produce warnings even when it succeeds, thus the nonstandard return type to provide Diagnostics on success.

impl Filter

pub fn new(spec: &str) -> Self

Create a new filter, ignoring any invalid directives. It is highly recommended you use Self::parse instead, and display the warnings for ignored directives.

pub fn empty() -> Self

Create an empty filter (i.e. one that filters nothing out).

pub fn from_default_env() -> Option<(Self, Option<Diagnostics<'static>>)>

Create a filter from the default RUST_LOG environment.

pub fn from_env( key: impl AsRef<OsStr>, ) -> Option<(Self, Option<Diagnostics<'static>>)>

Create a filter from the environment.

Returns None if the environment variable is not set.

pub fn layer(self) -> FilterLayer<Self>

Lift this filter to a filter layer.

Trait Implementations

impl Debug for Filter

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

Formats the value using the given formatter.

impl Display for Filter

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

Formats the value using the given formatter.

impl<S: Subscriber + for<'a> LookupSpan<'a>> Filter<S> for Filter

fn enabled(&self, metadata: &Metadata<'_>, _ctx: &Context<'_, S>) -> bool

Returns true if this layer is interested in a span or event with the given Metadata in the current Context, similarly to Subscriber::enabled.

fn callsite_enabled(&self, metadata: &Metadata<'_>) -> Interest

Returns an Interest indicating whether this layer will always, sometimes, or never be interested in the given Metadata.

fn max_level_hint(&self) -> Option<LevelFilter>

Returns an optional hint of the highest verbosity level that this Filter will enable.

fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>)

Notifies this filter that a new span was constructed with the given Attributes and Id.

fn on_record(&self, id: &Id, values: &Record<'_>, ctx: Context<'_, S>)

Notifies this filter that a span with the given Id recorded the given values.

fn on_enter(&self, id: &Id, ctx: Context<'_, S>)

Notifies this filter that a span with the given ID was entered.

fn on_exit(&self, id: &Id, ctx: Context<'_, S>)

Notifies this filter that a span with the given ID was exited.

fn on_close(&self, id: Id, ctx: Context<'_, S>)

Notifies this filter that a span with the given ID has been closed.

fn event_enabled(&self, event: &Event<'_>, cx: &Context<'_, S>) -> bool

Called before the filtered [Layer]'s [on_event], to determine if on_event` should be called.

impl FromStr for Filter

fn from_str(s: &str) -> Result<Self, Diagnostics<'static>>

Parse a filter from its string representation, discarding warnings.

type Err = Diagnostics<'static>

The associated error which can be returned from parsing.