🛈 Note: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem.

For the release documentation, please see docs.rs, instead.

tracing_subscriber::filter

Struct FilterFn

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

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-subscriber filtering (using its Filter implementation) and global filtering (using its Subscribe implementation).

See the documentation on filtering with subscribers for details.

Implementations§

Source§

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

Source

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-subscriber filtering for details on using Filters.

§Examples
use tracing_subscriber::{
    subscribe::{Subscribe, CollectExt},
    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_subscriber = tracing_subscriber::fmt::subscriber();

tracing_subscriber::registry()
    .with(my_subscriber.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...");
Source

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::{
    subscribe::{Subscribe, CollectExt},
    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_subscriber = tracing_subscriber::fmt::subscriber();

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

Trait Implementations§

Source§

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

Source§

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

Returns a copy of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

impl<F> Debug for FilterFn<F>

Source§

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

Formats the value using the given formatter. Read more
Source§

impl<C, F> Filter<C> for FilterFn<F>
where F: Fn(&Metadata<'_>) -> bool,

Available on crate features registry and std only.
Source§

fn enabled(&self, metadata: &Metadata<'_>, _: &Context<'_, C>) -> 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. Read more
Source§

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

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

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

Returns an optional hint of the highest verbosity level that this Filter will enable. Read more
Source§

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. Read more
Source§

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. Read more
Source§

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. Read more
Source§

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

Notifies this filter that a span with the given ID was entered. Read more
Source§

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

Notifies this filter that a span with the given ID was exited. Read more
Source§

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

Notifies this filter that a span with the given ID has been closed. Read more
Source§

impl<F> From<F> for FilterFn<F>
where F: Fn(&Metadata<'_>) -> bool,

Source§

fn from(enabled: F) -> Self

Converts to this type from the input type.
Source§

impl<C, F> Subscribe<C> for FilterFn<F>
where F: Fn(&Metadata<'_>) -> bool + 'static, C: Collect,

Source§

fn enabled(&self, metadata: &Metadata<'_>, _: Context<'_, C>) -> 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. Read more
Source§

fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest

Registers a new callsite with this subscriber, returning whether or not the subscriber is interested in being notified about the callsite, similarly to Collect::register_callsite. Read more
Source§

fn on_register_dispatch(&self, collector: &Dispatch)

Performs late initialization when installing this subscriber as a collector. Read more
Source§

fn on_subscribe(&mut self, collector: &mut C)

Performs late initialization when attaching a subscriber to a collector. Read more
Source§

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

Notifies this subscriber that a new span was constructed with the given Attributes and Id.
Source§

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

Notifies this subscriber that a span with the given Id recorded the given values.
Source§

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

Notifies this subscriber that a span with the ID span recorded that it follows from the span with the ID follows.
Source§

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

Called before on_event, to determine if on_event should be called. Read more
Source§

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

Notifies this subscriber that an event has occurred.
Source§

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

Notifies this subscriber that a span with the given ID was entered.
Source§

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

Notifies this subscriber that the span with the given ID was exited.
Source§

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

Notifies this subscriber that the span with the given ID has been closed.
Source§

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

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

fn and_then<S>(self, subscriber: S) -> Layered<S, Self, C>
where S: Subscribe<C>, Self: Sized,

Composes this subscriber around the given collector, returning a Layered struct implementing Subscribe. Read more
Source§

fn with_collector(self, inner: C) -> Layered<Self, C>
where Self: Sized,

Composes this subscriber with the given collector, returning a Layered struct that implements Collect. Read more
Source§

fn with_filter<F>(self, filter: F) -> Filtered<Self, F, C>
where Self: Sized, F: Filter<C>,

Available on crate features registry and std only.
Combines self with a Filter, returning a Filtered subscriber. Read more
Source§

fn boxed(self) -> Box<dyn Subscribe<C> + Send + Sync + 'static>
where Self: Sized + Subscribe<C> + Send + Sync + 'static, C: Collect,

Available on crate features alloc or std only.
Erases the type of this subscriber, returning a Boxed dyn Subscribe trait object. Read more

Auto Trait Implementations§

§

impl<F> Freeze for FilterFn<F>
where F: Freeze,

§

impl<F> RefUnwindSafe for FilterFn<F>
where F: RefUnwindSafe,

§

impl<F> Send for FilterFn<F>
where F: Send,

§

impl<F> Sync for FilterFn<F>
where F: Sync,

§

impl<F> Unpin for FilterFn<F>
where F: Unpin,

§

impl<F> UnwindSafe for FilterFn<F>
where F: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit #126799)
Performs copy-assignment from self to dst. Read more
Source§

impl<F, S> FilterExt<S> for F
where F: Filter<S>,

Source§

fn and<B>(self, other: B) -> And<Self, B, S>
where Self: Sized, B: Filter<S>,

Available on crate features registry and std only.
Combines this Filter with another Filter s so that spans and events are enabled if and only if both filters return true. Read more
Source§

fn or<B>(self, other: B) -> Or<Self, B, S>
where Self: Sized, B: Filter<S>,

Available on crate features registry and std only.
Combines two Filters so that spans and events are enabled if either filter returns true. Read more
Source§

fn not(self) -> Not<Self, S>
where Self: Sized,

Available on crate features registry and std only.
Inverts self, returning a filter that enables spans and events only if self would not enable them. Read more
Source§

fn boxed(self) -> Box<dyn Filter<S> + Send + Sync + 'static>
where Self: Sized + Send + Sync + 'static,

Available on crate features registry and std only.
Boxes self, erasing its concrete type. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithCollector for T

Source§

fn with_collector<C>(self, collector: C) -> WithDispatch<Self>
where C: Into<Dispatch>,

Attaches the provided collector to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_collector(self) -> WithDispatch<Self>

Attaches the current default collector to this type, returning a WithDispatch wrapper. Read more