Trait Filter

pub trait Filter<S> {
    // Required method
    fn enabled(&self, meta: &Metadata<'_>, cx: &Context<'_, S>) -> bool;

    // Provided methods
    fn callsite_enabled(&self, meta: &'static Metadata<'static>) -> Interest { ... }
    fn max_level_hint(&self) -> Option<LevelFilter>  { ... }
    fn event_enabled(&self, event: &Event<'_>, cx: &Context<'_, S>) -> bool { ... }
    fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>) { ... }
    fn on_record(&self, id: &Id, values: &Record<'_>, ctx: Context<'_, S>) { ... }
    fn on_enter(&self, id: &Id, ctx: Context<'_, S>) { ... }
    fn on_exit(&self, id: &Id, ctx: Context<'_, S>) { ... }
    fn on_close(&self, id: Id, ctx: Context<'_, S>) { ... }
}

Available on crate features registry and std only.

A per-Subscribe filter that determines whether a span or event is enabled for an individual subscriber.

Required Methods

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

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

If this returns false, the span or event will be disabled for the wrapped Subscribe. Unlike Subscribe::enabled, the span or event will still be recorded if any other subscribers choose to enable it. However, the subscriber filtered by this filter will skip recording that span or event.

If all subscribers indicate that they do not wish to see this span or event, it will be disabled.

Provided Methods

fn callsite_enabled(&self, meta: &'static Metadata<'static>) -> Interest

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

When a given callsite will always or never be enabled, the results of evaluating the filter may be cached for improved performance. Therefore, if a filter is capable of determining that it will always or never enable a particular callsite, providing an implementation of this function is recommended.

Note: If a Filter will perform
dynamic filtering that depends on the current context in which
a span or event was observed (e.g. only enabling an event when it
occurs within a particular span), it must return
Interest::sometimes() from this method. If it returns
Interest::always() or Interest::never(), the
enabled method may not be called when a particular instance
of that span or event is recorded.

This method is broadly similar to Collect::register_callsite; however, since the returned value represents only the interest of this subscriber, the resulting behavior is somewhat different.

If a Collect returns Interest::always() or Interest::never() for a given Metadata, its enabled method is then guaranteed to never be called for that callsite. On the other hand, when a Filter returns Interest::always() or Interest::never() for a callsite, other Subscribes may have differing interests in that callsite. If this is the case, the callsite will receive Interest::sometimes(), and the enabled method will still be called for that callsite when it records a span or event.

Returning Interest::always() or Interest::never() from Filter::callsite_enabled will permanently enable or disable a callsite (without requiring subsequent calls to enabled) if and only if the following is true:

• all Subscribes that comprise the subscriber include Filters (this includes a tree of Layered subscribers that share the same Filter)
• all those Filters return the same Interest.

For example, if a Collect consists of two Filtered subscribers, and both of those subscribers return Interest::never(), that callsite will never be enabled, and the enabled methods of those Filters will not be called.

Default Implementation

The default implementation of this method assumes that the Filter’s enabled method may perform dynamic filtering, and returns Interest::sometimes(), to ensure that enabled is called to determine whether a particular instance of the callsite is enabled in the current context. If this is not the case, and the Filter’s enabled method will always return the same result for a particular Metadata, this method can be overridden as follows:

use tracing_subscriber::subscribe;
use tracing_core::{Metadata, collect::Interest};

struct MyFilter {
    // ...
}

impl MyFilter {
    // The actual logic for determining whether a `Metadata` is enabled
    // must be factored out from the `enabled` method, so that it can be
    // called without a `Context` (which is not provided to the
    // `callsite_enabled` method).
    fn is_enabled(&self, metadata: &Metadata<'_>) -> bool {
        // ...
    }
}

impl<C> subscribe::Filter<C> for MyFilter {
    fn enabled(&self, metadata: &Metadata<'_>, _: &subscribe::Context<'_, C>) -> bool {
        // Even though we are implementing `callsite_enabled`, we must still provide a
        // working implementation of `enabled`, as returning `Interest::always()` or
        // `Interest::never()` will *allow* caching, but will not *guarantee* it.
        // Other filters may still return `Interest::sometimes()`, so we may be
        // asked again in `enabled`.
        self.is_enabled(metadata)
    }

    fn callsite_enabled(&self, metadata: &'static Metadata<'static>) -> Interest {
        // The result of `self.enabled(metadata, ...)` will always be
        // the same for any given `Metadata`, so we can convert it into
        // an `Interest`:
        if self.is_enabled(metadata) {
            Interest::always()
        } else {
            Interest::never()
        }
    }
}

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

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

If this method returns a LevelFilter, it will be used as a hint to determine the most verbose level that will be enabled. This will allow spans and events which are more verbose than that level to be skipped more efficiently. An implementation of this method is optional, but strongly encouraged.

If the maximum level the Filter will enable can change over the course of its lifetime, it is free to return a different value from multiple invocations of this method. However, note that changes in the maximum level will only be reflected after the callsite Interest cache is rebuilt, by calling the tracing_core::callsite::rebuild_interest_cache function. Therefore, if the Filter will change the value returned by this method, it is responsible for ensuring that [rebuild_interest_cache`] is called after the value of the max level changes.

Default Implementation

By default, this method returns None, indicating that the maximum level is unknown.

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

Called before the filtered subscribers’ on_event, to determine if on_event should be called.

This gives a chance to filter events based on their fields. Note, however, that this does not override enabled, and is not even called if enabled returns false.

Default Implementation

By default, this method returns true, indicating that no events are filtered out based on their fields.

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.

By default, this method does nothing. Filter implementations that need to be notified when new spans are created can override this method.

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.

By default, this method does nothing. Filter implementations that need to be notified when new spans are created can override this method.

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

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

By default, this method does nothing. Filter implementations that need to be notified when a span is entered can override this method.

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

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

By default, this method does nothing. Filter implementations that need to be notified when a span is exited can override this method.

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

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

By default, this method does nothing. Filter implementations that need to be notified when a span is closed can override this method.

Trait Implementations

impl<S> Filter<S> for Box<dyn Filter<S> + Send + Sync + 'static>

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

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

fn callsite_enabled(&self, meta: &'static Metadata<'static>) -> Interest

Returns an Interest indicating whether this subscriber 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 event_enabled(&self, event: &Event<'_>, cx: &Context<'_, S>) -> bool

Called before the filtered subscribers’ on_event, to determine if on_event should be called.

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.

Implementations on Foreign Types

impl<F, S> Filter<S> for Option<F>

where F: Filter<S>,

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

fn callsite_enabled(&self, meta: &'static Metadata<'static>) -> Interest

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

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

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

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

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

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

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

impl<S> Filter<S> for Box<dyn Filter<S> + Send + Sync + 'static>

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

fn callsite_enabled(&self, meta: &'static Metadata<'static>) -> Interest

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

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

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

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

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

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

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

impl<S> Filter<S> for Arc<dyn Filter<S> + Send + Sync + 'static>

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

fn callsite_enabled(&self, meta: &'static Metadata<'static>) -> Interest

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

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

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

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

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

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

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

Implementors

impl<A, B, S> Filter<S> for And<A, B, S>

where A: Filter<S>, B: Filter<S>,

impl<A, B, S> Filter<S> for Or<A, B, S>

where A: Filter<S>, B: Filter<S>,

impl<A, S> Filter<S> for Not<A, S>

where A: Filter<S>,

impl<C> Filter<C> for EnvFilter

Available on crate feature env-filter only.

impl<C> Filter<C> for LevelFilter

impl<C> Filter<C> for Targets

Available on crate features std or alloc only.

impl<C, F> Filter<C> for FilterFn<F>

where F: Fn(&Metadata<'_>) -> bool,

impl<C, F, R> Filter<C> for DynFilterFn<C, F, R>

where F: Fn(&Metadata<'_>, &Context<'_, C>) -> bool, R: Fn(&'static Metadata<'static>) -> Interest,

impl<S, C> Filter<C> for Subscriber<S>

where S: Filter<C> + 'static, C: Collect,