Trait tracing_subscriber::layer::Filter

source · [−]

pub trait Filter<S> {
    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 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>) { ... }
}

Expand description

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

source

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

source

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()
        }
    }
}

source

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.