Trait tracing_subscriber::layer::Filter
source · 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>) { ... }
}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§
sourcefn enabled(&self, meta: &Metadata<'_>, cx: &Context<'_, S>) -> bool
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§
sourcefn callsite_enabled(&self, meta: &'static Metadata<'static>) -> Interest
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 aFilterwill 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 returnInterest::sometimes()from this method. If it returnsInterest::always()orInterest::never(), theenabledmethod 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 includeFilters (this includes a tree ofLayeredlayers that share the sameFilter) - all those
Filters return the sameInterest.
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()
}
}
}sourcefn event_enabled(&self, event: &Event<'_>, cx: &Context<'_, S>) -> bool
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.
sourcefn max_level_hint(&self) -> Option<LevelFilter>
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.
sourcefn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>)
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.
sourcefn on_record(&self, id: &Id, values: &Record<'_>, ctx: Context<'_, S>)
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.
sourcefn on_enter(&self, id: &Id, ctx: Context<'_, S>)
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.
Trait Implementations§
source§impl<S> Filter<S> for Box<dyn Filter<S> + Send + Sync + 'static>
impl<S> Filter<S> for Box<dyn Filter<S> + Send + Sync + 'static>
source§fn enabled(&self, meta: &Metadata<'_>, cx: &Context<'_, S>) -> bool
fn enabled(&self, meta: &Metadata<'_>, cx: &Context<'_, S>) -> bool
true if this layer is interested in a span or event with the
given Metadata in the current Context, similarly to
Subscriber::enabled. Read moresource§fn callsite_enabled(&self, meta: &'static Metadata<'static>) -> Interest
fn callsite_enabled(&self, meta: &'static Metadata<'static>) -> Interest
source§fn max_level_hint(&self) -> Option<LevelFilter>
fn max_level_hint(&self) -> Option<LevelFilter>
source§fn event_enabled(&self, event: &Event<'_>, cx: &Context<'_, S>) -> bool
fn event_enabled(&self, event: &Event<'_>, cx: &Context<'_, S>) -> bool
Layer]'s [on_event], to determine if on_event` should be called. Read more