Struct FilterFn

pub struct FilterFn<F = fn(_: &Metadata<'_>) -> bool> { /* private fields */ }

A filter implemented by a closure or function pointer that determines whether a given span or event is enabled, based on its Metadata.

This type can be used for both per-layer filtering (using its Filter implementation) and global filtering (using its Layer implementation).

See the documentation on filtering with layers for details.

Implementations

impl<F> FilterFn<F>

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

pub fn new(enabled: F) -> Self

Constructs a FilterFn from a function or closure that returns true if a span or event should be enabled, based on its Metadata.

If determining whether a span or event should be enabled also requires information about the current span context, use DynFilterFn instead.

See the documentation on per-layer filtering for details on using Filters.

Examples

use tracing_subscriber::{
    layer::{Layer, SubscriberExt},
    filter::FilterFn,
    util::SubscriberInitExt,
};

let my_filter = FilterFn::new(|metadata| {
    // Only enable spans or events with the target "interesting_things"
    metadata.target() == "interesting_things"
});

let my_layer = tracing_subscriber::fmt::layer();

tracing_subscriber::registry()
    .with(my_layer.with_filter(my_filter))
    .init();

// This event will not be enabled.
tracing::warn!("something important but uninteresting happened!");

// This event will be enabled.
tracing::debug!(target: "interesting_things", "an interesting minor detail...");

pub fn with_max_level_hint(self, max_level_hint: impl Into<LevelFilter>) -> Self

Sets the highest verbosity Level the filter function will enable.

The value passed to this method will be returned by this FilterFn’s Filter::max_level_hint method.

If the provided function will not enable all levels, it is recommended to call this method to configure it with the most verbose level it will enable.

Examples

use tracing_subscriber::{
    layer::{Layer, SubscriberExt},
    filter::{filter_fn, LevelFilter},
    util::SubscriberInitExt,
};
use tracing_core::Level;

let my_filter = filter_fn(|metadata| {
    // Only enable spans or events with targets starting with `my_crate`
    // and levels at or below `INFO`.
    metadata.level() <= &Level::INFO && metadata.target().starts_with("my_crate")
})
    // Since the filter closure will only enable the `INFO` level and
    // below, set the max level hint
    .with_max_level_hint(LevelFilter::INFO);

let my_layer = tracing_subscriber::fmt::layer();

tracing_subscriber::registry()
    .with(my_layer.with_filter(my_filter))
    .init();

Trait Implementations

impl<F: Clone> Clone for FilterFn<F>

fn clone(&self) -> FilterFn<F>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<F> Debug for FilterFn<F>

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

Formats the value using the given formatter.

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

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

Available on crate features registry and std only.

fn enabled(&self, metadata: &Metadata<'_>, _: &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: &'static Metadata<'static>) -> 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 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.

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.

impl<F> From<F> for FilterFn<F>

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

fn from(enabled: F) -> Self

Converts to this type from the input type.

impl<S, F> Layer<S> for FilterFn<F>

where F: Fn(&Metadata<'_>) -> bool + 'static, S: Subscriber,

fn enabled(&self, metadata: &Metadata<'_>, _: 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 register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest

Registers a new callsite with this layer, returning whether or not the layer is interested in being notified about the callsite, similarly to Subscriber::register_callsite.

fn on_register_dispatch(&self, subscriber: &Dispatch)

Performs late initialization when installing this layer as a Subscriber.

fn on_layer(&mut self, subscriber: &mut S)

Performs late initialization when attaching a Layer to a Subscriber.

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

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

fn on_record(&self, _span: &Id, _values: &Record<'_>, _ctx: Context<'_, S>)

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

fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, S>)

Notifies this layer that a span with the ID span recorded that it follows from the span with the ID follows.

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

Called before on_event, to determine if on_event should be called.

fn on_event(&self, _event: &Event<'_>, _ctx: Context<'_, S>)

Notifies this layer that an event has occurred.

fn on_enter(&self, _id: &Id, _ctx: Context<'_, S>)

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

fn on_exit(&self, _id: &Id, _ctx: Context<'_, S>)

Notifies this layer that the span with the given ID was exited.

fn on_close(&self, _id: Id, _ctx: Context<'_, S>)

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

fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, S>)

Notifies this layer that a span ID has been cloned, and that the subscriber returned a different ID.

fn and_then<L>(self, layer: L) -> Layered<L, Self, S>

where L: Layer<S>, Self: Sized,

Composes this layer around the given Layer, returning a Layered struct implementing Layer.

fn with_subscriber(self, inner: S) -> Layered<Self, S>

where Self: Sized,

Composes this Layer with the given Subscriber, returning a Layered struct that implements Subscriber.

fn with_filter<F>(self, filter: F) -> Filtered<Self, F, S>

where Self: Sized, F: Filter<S>,

Available on crate features registry and std only.

Combines self with a Filter, returning a Filtered layer.

fn boxed(self) -> Box<dyn Layer<S> + Send + Sync + 'static>

where Self: Sized + Layer<S> + Send + Sync + 'static, S: Subscriber,

Available on crate features alloc or std only.

Erases the type of this Layer, returning a Boxed dyn Layer trait object.