Trait tracing_subscriber::layer::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 event_enabled(&self, event: &Event<'_>, cx: &Context<'_, S>) -> bool { ... }
    fn max_level_hint(&self) -> Option<LevelFilter> { ... }
    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>) { ... }
}

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

See the module-level documentation for details on using Filters.

Required Methods

fn enabled(&self, meta: &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.

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

If all layers 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 layer 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 observered (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 Subscriber::register_callsite; however, since the returned value represents only the interest of this layer, the resulting behavior is somewhat different.

If a Subscriber 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 Layers may have differing interests in that callsite. If this is the case, the callsite will recieve 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 Layers that comprise the subscriber include Filters (this includes a tree of Layered layers that share the same Filter)
• all those Filters return the same Interest.

For example, if a Subscriber consists of two Filtered layers, and both of those layers 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::layer;
use tracing_core::{Metadata, subscriber::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<S> layer::Filter<S> for MyFilter {
    fn enabled(&self, metadata: &Metadata<'_>, _: &layer::Context<'_, S>) -> 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 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.

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 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`]rebuild 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 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 layer is interested in a span or event with the given Metadata in the current Context, similarly to Subscriber::enabled.

fn callsite_enabled(&self, meta: &'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.

Implementations on Foreign Types

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>

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>

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<S> Filter<S> for EnvFilter

impl<S> Filter<S> for LevelFilter

impl<S> Filter<S> for Targets

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

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

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

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

impl<S, L> Filter<S> for Layer<L, S>

where L: Filter<S> + 'static, S: Subscriber,