Struct tracing_subscriber::filter::DynFilterFn

source ·
pub struct DynFilterFn<S, F = fn(_: &Metadata<'_>, _: &Context<'_, S>) -> bool, R = fn(_: &'static Metadata<'static>) -> Interest> { /* private fields */ }
Expand description

A filter implemented by a closure or function pointer that determines whether a given span or event is enabled dynamically, potentially based on the current span context.

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§

source§

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

source

pub fn new(enabled: F) -> Self

Constructs a Filter from a function or closure that returns true if a span or event should be enabled in the current span context.

Unlike FilterFn, a DynFilterFn is constructed from a closure or function pointer that takes both the Metadata for a span or event and the current Context. This means that a DynFilterFn can choose whether to enable spans or events based on information about the current span (or its parents).

If this is not necessary, use FilterFn instead.

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

§Examples
use tracing_subscriber::{
    layer::{Layer, SubscriberExt},
    filter::DynFilterFn,
    util::SubscriberInitExt,
};

// Only enable spans or events within a span named "interesting_span".
let my_filter = DynFilterFn::new(|metadata, cx| {
    // If this *is* "interesting_span", make sure to enable it.
    if metadata.is_span() && metadata.name() == "interesting_span" {
        return true;
    }

    // Otherwise, are we in an interesting span?
    if let Some(current_span) = cx.lookup_current() {
        return current_span.name() == "interesting_span";
    }

    false
});

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::info!("something happened");

tracing::info_span!("interesting_span").in_scope(|| {
    // This event will be enabled.
    tracing::debug!("something else happened");
});
source§

impl<S, F, R> DynFilterFn<S, F, R>
where F: Fn(&Metadata<'_>, &Context<'_, S>) -> bool,

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 DynFilterFn’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::{DynFilterFn, LevelFilter},
    util::SubscriberInitExt,
};
use tracing_core::Level;

// Only enable spans or events with levels at or below `INFO`, if
// we are inside a span called "interesting_span".
let my_filter = DynFilterFn::new(|metadata, cx| {
    // If the level is greater than INFO, disable it.
    if metadata.level() > &Level::INFO {
        return false;
    }

    // If any span in the current scope is named "interesting_span",
    // enable this span or event.
    for span in cx.lookup_current().iter().flat_map(|span| span.scope()) {
        if span.name() == "interesting_span" {
            return true;
         }
    }

    // Otherwise, disable it.
    false
})
    // 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();
source

pub fn with_callsite_filter<R2>( self, callsite_enabled: R2, ) -> DynFilterFn<S, F, R2>
where R2: Fn(&'static Metadata<'static>) -> Interest,

Adds a function for filtering callsites to this filter.

When this filter’s Filter::callsite_enabled method is called, the provided function will be used rather than the default.

By default, DynFilterFn assumes that, because the filter may depend dynamically on the current span context, its result should never be cached. However, some filtering strategies may require dynamic information from the current span context in some cases, but are able to make static filtering decisions from Metadata alone in others.

For example, consider the filter given in the example for DynFilterFn::new. That filter enables all spans named “interesting_span”, and any events and spans that occur inside of an interesting span. Since the span’s name is part of its static Metadata, the “interesting_span” can be enabled in callsite_enabled:

use tracing_subscriber::{
    layer::{Layer, SubscriberExt},
    filter::DynFilterFn,
    util::SubscriberInitExt,
};
use tracing_core::subscriber::Interest;

// Only enable spans or events within a span named "interesting_span".
let my_filter = DynFilterFn::new(|metadata, cx| {
    // If this *is* "interesting_span", make sure to enable it.
    if metadata.is_span() && metadata.name() == "interesting_span" {
        return true;
    }

    // Otherwise, are we in an interesting span?
    if let Some(current_span) = cx.lookup_current() {
        return current_span.name() == "interesting_span";
    }

    false
}).with_callsite_filter(|metadata| {
    // If this is an "interesting_span", we know we will always
    // enable it.
    if metadata.is_span() && metadata.name() == "interesting_span" {
        return Interest::always();
    }

    // Otherwise, it depends on whether or not we're in an interesting
    // span. You'll have to ask us again for each span/event!
    Interest::sometimes()
});

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

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

Trait Implementations§

source§

impl<S, F, R> Clone for DynFilterFn<S, F, R>
where F: Clone, R: Clone,

source§

fn clone(&self) -> Self

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<S, F, R> Debug for DynFilterFn<S, F, R>

source§

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

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

impl<S, F, R> Filter<S> for DynFilterFn<S, F, R>
where F: Fn(&Metadata<'_>, &Context<'_, S>) -> bool, R: Fn(&'static Metadata<'static>) -> Interest,

source§

fn enabled(&self, metadata: &Metadata<'_>, cx: &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. Read more
source§

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. 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 [Layer]'s [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, S> From<F> for DynFilterFn<S, F>
where F: Fn(&Metadata<'_>, &Context<'_, S>) -> bool,

source§

fn from(f: F) -> Self

Converts to this type from the input type.
source§

impl<S, F, R> Layer<S> for DynFilterFn<S, F, R>
where F: Fn(&Metadata<'_>, &Context<'_, S>) -> bool + 'static, R: Fn(&'static Metadata<'static>) -> Interest + 'static, S: Subscriber,

source§

fn enabled(&self, metadata: &Metadata<'_>, cx: 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. Read more
source§

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

fn on_register_dispatch(&self, subscriber: &Dispatch)

Performs late initialization when installing this layer as a Subscriber. Read more
source§

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

Performs late initialization when attaching a Layer to a Subscriber. Read more
source§

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.
source§

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.
source§

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.
source§

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

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

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

Notifies this layer that an event has occurred.
source§

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

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

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

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

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

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

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.
source§

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

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

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

Combines self with a Filter, returning a Filtered layer. Read more

Auto Trait Implementations§

§

impl<S, F, R> Freeze for DynFilterFn<S, F, R>
where F: Freeze, R: Freeze,

§

impl<S, F, R> RefUnwindSafe for DynFilterFn<S, F, R>

§

impl<S, F, R> Send for DynFilterFn<S, F, R>
where F: Send, R: Send,

§

impl<S, F, R> Sync for DynFilterFn<S, F, R>
where F: Sync, R: Sync,

§

impl<S, F, R> Unpin for DynFilterFn<S, F, R>
where F: Unpin, R: Unpin,

§

impl<S, F, R> UnwindSafe for DynFilterFn<S, F, R>
where F: UnwindSafe, R: 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§

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

🔬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>,

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>,

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,

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,

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,

§

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>,

§

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>,

§

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> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

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