Trait tracing_subscriber::layer::Layer
source · [−]pub trait Layer<S> where
S: Subscriber,
Self: 'static, {
fn register_callsite(
&self,
metadata: &'static Metadata<'static>
) -> Interest { ... }
fn enabled(&self, metadata: &Metadata<'_>, ctx: Context<'_, S>) -> bool { ... }
fn 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 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,
{ ... }
}
Expand description
A composable handler for tracing
events.
The Subscriber
trait in tracing-core
represents the complete set of
functionality required to consume tracing
instrumentation. This means that
a single Subscriber
instance is a self-contained implementation of a
complete strategy for collecting traces; but it also means that the
Subscriber
trait cannot easily be composed with other Subscriber
s.
In particular, Subscriber
’s are responsible for generating span IDs and
assigning them to spans. Since these IDs must uniquely identify a span
within the context of the current trace, this means that there may only be
a single Subscriber
for a given thread at any point in time —
otherwise, there would be no authoritative source of span IDs.
On the other hand, the majority of the Subscriber
trait’s functionality
is composable: any number of subscribers may observe events, span entry
and exit, and so on, provided that there is a single authoritative source of
span IDs. The Layer
trait represents this composable subset of the
Subscriber
behavior; it can observe events and spans, but does not
assign IDs.
Composing Layers
Since a Layer
does not implement a complete strategy for collecting
traces, it must be composed with a Subscriber
in order to be used. The
Layer
trait is generic over a type parameter (called S
in the trait
definition), representing the types of Subscriber
they can be composed
with. Thus, a Layer
may be implemented that will only compose with a
particular Subscriber
implementation, or additional trait bounds may be
added to constrain what types implementing Subscriber
a Layer
can wrap.
Layer
s may be added to a Subscriber
by using the SubscriberExt::with
method, which is provided by tracing-subscriber
’s prelude. This method
returns a Layered
struct that implements Subscriber
by composing the
Layer
with the Subscriber
.
For example:
use tracing_subscriber::Layer;
use tracing_subscriber::prelude::*;
use tracing::Subscriber;
pub struct MyLayer {
// ...
}
impl<S: Subscriber> Layer<S> for MyLayer {
// ...
}
pub struct MySubscriber {
// ...
}
impl Subscriber for MySubscriber {
// ...
}
let subscriber = MySubscriber::new()
.with(MyLayer::new());
tracing::subscriber::set_global_default(subscriber);
Multiple Layer
s may be composed in the same manner:
pub struct MyOtherLayer {
// ...
}
impl<S: Subscriber> Layer<S> for MyOtherLayer {
// ...
}
pub struct MyThirdLayer {
// ...
}
impl<S: Subscriber> Layer<S> for MyThirdLayer {
// ...
}
}
let subscriber = MySubscriber::new()
.with(MyLayer::new())
.with(MyOtherLayer::new())
.with(MyThirdLayer::new());
tracing::subscriber::set_global_default(subscriber);
The Layer::with_subscriber
method constructs the Layered
type from a Layer
and Subscriber
, and is called by
SubscriberExt::with
. In general, it is more idiomatic to use
SubscriberExt::with
, and treat Layer::with_subscriber
as an
implementation detail, as with_subscriber
calls must be nested, leading to
less clear code for the reader. However, Layer
s which wish to perform
additional behavior when composed with a subscriber may provide their own
implementations of SubscriberExt::with
.
Recording Traces
The Layer
trait defines a set of methods for consuming notifications from
tracing instrumentation, which are generally equivalent to the similarly
named methods on Subscriber
. Unlike Subscriber
, the methods on
Layer
are additionally passed a Context
type, which exposes additional
information provided by the wrapped subscriber (such as the current span)
to the layer.
Filtering with Layer
s
As well as strategies for handling trace events, the Layer
trait may also
be used to represent composable filters. This allows the determination of
what spans and events should be recorded to be decoupled from how they are
recorded: a filtering layer can be applied to other layers or
subscribers. A Layer
that implements a filtering strategy should override the
register_callsite
and/or enabled
methods. It may also choose to implement
methods such as on_enter
, if it wishes to filter trace events based on
the current span context.
Note that the Layer::register_callsite
and Layer::enabled
methods
determine whether a span or event is enabled globally. Thus, they should
not be used to indicate whether an individual layer wishes to record a
particular span or event. Instead, if a layer is only interested in a subset
of trace data, but does not wish to disable other spans and events for the
rest of the layer stack should ignore those spans and events in its
notification methods.
The filtering methods on a stack of Layer
s are evaluated in a top-down
order, starting with the outermost Layer
and ending with the wrapped
Subscriber
. If any layer returns false
from its enabled
method, or
Interest::never()
from its register_callsite
method, filter
evaluation will short-circuit and the span or event will be disabled.
Provided Methods
fn register_callsite(&self, metadata: &'static Metadata<'static>) -> Interest
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 (andLayer::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 theiron_event
,on_enter
,on_exit
, and other notification methods.
See the trait-level documentation for more information on filtering
with Layer
s.
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()
.
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 (andLayer::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 theiron_event
,on_enter
,on_exit
, and other notification methods.
See the trait-level documentation for more information on filtering
with Layer
s.
fn new_span(&self, attrs: &Attributes<'_>, id: &Id, ctx: Context<'_, S>)
fn 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
.
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>)
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
.
Notifies this layer that an event has occurred.
Notifies this layer that a span with the given ID was entered.
Notifies this layer that the span with the given ID was exited.
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>)
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.
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,
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());