Trait tracing_subscriber::layer::Layer

pub trait Layer<S>
where
    S: Subscriber,
    Self: 'static,
{
    // Provided methods
    fn on_register_dispatch(&self, subscriber: &Dispatch) { ... }
    fn on_layer(&mut self, subscriber: &mut S) { ... }
    fn register_callsite(
        &self,
        metadata: &'static Metadata<'static>,
    ) -> Interest { ... }
    fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool { ... }
    fn on_new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>) { ... }
    fn on_record(&self, _span: &Id, _values: &Record<'_>, _ctx: Context<'_, S>) { ... }
    fn on_follows_from(&self, _span: &Id, _follows: &Id, _ctx: Context<'_, S>) { ... }
    fn event_enabled(&self, _event: &Event<'_>, _ctx: Context<'_, S>) -> bool { ... }
    fn on_event(&self, _event: &Event<'_>, _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>) { ... }
    fn on_id_change(&self, _old: &Id, _new: &Id, _ctx: Context<'_, S>) { ... }
    fn and_then<L>(self, layer: L) -> Layered<L, Self, S> 
       where L: Layer<S>,
             Self: Sized { ... }
    fn with_subscriber(self, inner: S) -> Layered<Self, S> 
       where Self: Sized { ... }
}

A composable handler for tracing events.

A Layer implements a behavior for recording or collecting traces that can be composed together with other Layers to build a Subscriber. See the module-level documentation for details.

Provided Methods

fn on_register_dispatch(&self, subscriber: &Dispatch)

Performs late initialization when installing this layer as a Subscriber.

Avoiding Memory Leaks

Layers should not store the Dispatch pointing to the Subscriber that they are a part of. Because the Dispatch owns the Subscriber, storing the Dispatch within the Subscriber will create a reference count cycle, preventing the Dispatch from ever being dropped.

Instead, when it is necessary to store a cyclical reference to the Dispatch within a Layer, use Dispatch::downgrade to convert a Dispatch into a WeakDispatch. This type is analogous to [std::sync::Weak], and does not create a reference count cycle. A WeakDispatch can be stored within a subscriber without causing a memory leak, and can be upgraded into a Dispatch temporarily when the Dispatch must be accessed by the subscriber.

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

Performs late initialization when attaching a Layer to a Subscriber.

This is a callback that is called when the Layer is added to a Subscriber (e.g. in Layer::with_subscriber and SubscriberExt::with). Since this can only occur before the Subscriber has been set as the default, both the Layer and Subscriber are passed to this method mutably. This gives the Layer the opportunity to set any of its own fields with values recieved by method calls on the Subscriber.

For example, Filtered layers implement on_layer to call the Subscriber’s register_filter method, and store the returned FilterId as a field.

Note In most cases, Layer implementations will not need to implement this method. However, in cases where a type implementing Layer wraps one or more other types that implement Layer, like the Layered and Filtered types in this crate, that type MUST ensure that the inner Layers’ on_layer methods are called. Otherwise, functionality that relies on on_layer, such as per-layer filtering, may not work correctly.

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.

By default, this returns Interest::always() if self.enabled returns true, or Interest::never() if it returns false.

Note: This method (and 
Layer::enabled) determine whether a span or event is
globally enabled, not whether the individual layer will be
notified about that span or event. This is intended to be used
by layers that implement filtering for the entire stack. Layers which do
not wish to be notified about certain spans or events but do not wish to
globally disable them should ignore those spans or events in their
on_event,
on_enter,
on_exit, and other notification
methods.

See the trait-level documentation for more information on filtering with Layers.

Layers may also implement this method to perform any behaviour that should be run once per callsite. If the layer wishes to use register_callsite for per-callsite behaviour, but does not want to globally enable or disable those callsites, it should always return Interest::always().

fn enabled(&self, metadata: &Metadata<'_>, ctx: 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.

By default, this always returns true, allowing the wrapped subscriber to choose to disable the span.

Note: This method (and 
Layer::register_callsite) determine whether a span or event is
globally enabled, not whether the individual layer will be
notified about that span or event. This is intended to be used
by layers that implement filtering for the entire stack. Layers which do
not wish to be notified about certain spans or events but do not wish to
globally disable them should ignore those spans or events in their
on_event,
on_enter,
on_exit, and other notification
methods.

See the trait-level documentation for more information on filtering with Layers.

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.

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.

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.

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

Called before on_event, to determine if on_event should be called.

Note: This method determines whether an event is globally enabled,
not whether the individual Layer will be notified about the
event. This is intended to be used by Layers that implement
filtering for the entire stack. Layers which do not wish to be
notified about certain events but do not wish to globally disable them
should ignore those events in their on_event.

See the trait-level documentation for more information on filtering with Layers.

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

Notifies this layer that an event has occurred.

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

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

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

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

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

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

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.

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.

The returned Layer will call the methods on this Layer and then those of the new Layer, before calling the methods on the subscriber it wraps. For example:

pub struct FooLayer {
    // ...
}

pub struct BarLayer {
    // ...
}

pub struct MySubscriber {
    // ...
}

impl<S: Subscriber> Layer<S> for FooLayer {
    // ...
}

impl<S: Subscriber> Layer<S> for BarLayer {
    // ...
}

let subscriber = FooLayer::new()
    .and_then(BarLayer::new())
    .with_subscriber(MySubscriber::new());

Multiple layers may be composed in this manner:

pub struct BazLayer {
    // ...
}

impl<S: Subscriber> Layer<S> for BazLayer {
    // ...
}

let subscriber = FooLayer::new()
    .and_then(BarLayer::new())
    .and_then(BazLayer::new())
    .with_subscriber(MySubscriber::new());

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.

The returned Layered subscriber will call the methods on this Layer and then those of the wrapped subscriber.

For example:

pub struct FooLayer {
    // ...
}

pub struct MySubscriber {
    // ...
}

impl<S: Subscriber> Layer<S> for FooLayer {
    // ...
}

let subscriber = FooLayer::new()
    .with_subscriber(MySubscriber::new());

Implementations on Foreign Types

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

where L: Layer<S>, S: Subscriber,

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

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

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

fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool

fn on_record(&self, span: &Id, values: &Record<'_>, ctx: Context<'_, S>)

fn on_follows_from(&self, span: &Id, follows: &Id, ctx: Context<'_, S>)

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

fn on_event(&self, event: &Event<'_>, 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>)

fn on_id_change(&self, old: &Id, new: &Id, ctx: Context<'_, S>)

Implementors

impl<S, A, B> Layer<S> for Layered<A, B, S>

where A: Layer<S>, B: Layer<S>, S: Subscriber,

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

where F: Fn(&Metadata<'_>) -> bool + 'static, S: Subscriber,

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,

impl<S: Subscriber> Layer<S> for LevelFilter

impl<S: Subscriber> Layer<S> for Identity