Lines Matching full:layer
1 //! The [`Layer`] trait, a composable abstraction for building [`Subscriber`]s.
18 //! span IDs. The [`Layer`] trait represents this composable subset of the
24 //! Since a [`Layer`] does not implement a complete strategy for collecting
26 //! [`Layer`] trait is generic over a type parameter (called `S` in the trait
28 //! with. Thus, a [`Layer`] may be implemented that will only compose with a
30 //! added to constrain what types implementing `Subscriber` a `Layer` can wrap.
32 //! `Layer`s may be added to a `Subscriber` by using the [`SubscriberExt::with`]
35 //! `Layer` with the `Subscriber`.
39 //! use tracing_subscriber::Layer;
47 //! impl<S: Subscriber> Layer<S> for MyLayer {
79 //! Multiple `Layer`s may be composed in the same manner:
81 //! # use tracing_subscriber::{Layer, layer::SubscriberExt};
87 //! impl<S: Subscriber> Layer<S> for MyOtherLayer {
95 //! impl<S: Subscriber> Layer<S> for MyThirdLayer {
99 //! # impl<S: Subscriber> Layer<S> for MyLayer {}
132 //! The [`Layer::with_subscriber`] constructs the [`Layered`] type from a
133 //! [`Layer`] and [`Subscriber`], and is called by [`SubscriberExt::with`]. In
135 //! [`Layer::with_subscriber`] as an implementation detail, as `with_subscriber`
138 //! ## Runtime Configuration With `Layer`s
140 //! In some cases, a particular [`Layer`] may be enabled or disabled based on
143 //! or `match` expression adds some [`Layer`] implementation in one branch,
158 //! let stdout_log = tracing_subscriber::fmt::layer().pretty();
165 //! let layer = tracing_subscriber::fmt::layer()
168 //! layer.with(subscriber)
170 //! layer
178 //! However, a [`Layer`] wrapped in an [`Option`] [also implements the `Layer`
193 //! let stdout_log = tracing_subscriber::fmt::layer().pretty();
199 //! let json_log = tracing_subscriber::fmt::layer()
207 //! // If `cfg.is_prod` is false, then `json` will be `None`, and this layer
217 //! If a [`Layer`] may be one of several different types, note that [`Box<dyn
218 //! Layer<S> + Send + Sync>` implements `Layer`][box-impl].
219 //! This may be used to erase the type of a [`Layer`].
221 //! For example, a function that configures a [`Layer`] to log to one of
222 //! several outputs might return a `Box<dyn Layer<S> + Send + Sync + 'static>`:
225 //! Layer,
239 //! pub fn layer<S>(self) -> Box<dyn Layer<S> + Send + Sync + 'static>
245 //! let fmt = tracing_subscriber::fmt::layer()
263 //! .with(config.layer())
267 //! The [`Layer::boxed`] method is provided to make boxing a `Layer`
270 //! When the number of `Layer`s varies at runtime, note that a
271 //! [`Vec<L> where L: Layer` also implements `Layer`][vec-impl]. This
272 //! can be used to add a variable number of `Layer`s to a `Subscriber`:
275 //! use tracing_subscriber::{Layer, prelude::*};
281 //! impl<S: tracing_core::Subscriber> Layer<S> for MyLayer {
302 //! If a variable number of `Layer` is needed and those `Layer`s have
303 //! different types, a `Vec` of [boxed `Layer` trait objects][box-impl] may
307 //! use tracing_subscriber::{filter::LevelFilter, Layer, prelude::*};
330 //! let layer = tracing_subscriber::fmt::layer()
335 //! // Box the layer as a type-erased trait object, so that it can
338 //! layers.push(layer);
342 //! let layer = tracing_subscriber::fmt::layer()
345 //! // Box the layer as a type-erased trait object, so that it can
348 //! layers.push(layer);
352 //! let layer = tracing_subscriber::fmt::layer()
355 //! // Box the layer as a type-erased trait object, so that it can
358 //! layers.push(layer);
371 //! [option-impl]: Layer#impl-Layer<S>-for-Option<L>
372 //! [box-impl]: Layer#impl-Layer%3CS%3E-for-Box%3Cdyn%20Layer%3CS%3E%20+%20Send%20+%20Sync%3E
373 //! [vec-impl]: Layer#impl-Layer<S>-for-Vec<L>
378 //! The [`Layer`] trait defines a set of methods for consuming notifications from
381 //! `Layer` are additionally passed a [`Context`] type, which exposes additional
383 //! to the layer.
385 //! # Filtering with `Layer`s
387 //! As well as strategies for handling trace events, the `Layer` trait may also
390 //! recorded: a filtering layer can be applied to other layers or
391 //! subscribers. `Layer`s can be used to implement _global filtering_, where a
392 //! `Layer` provides a filtering strategy for the entire subscriber.
393 //! Additionally, individual recording `Layer`s or sets of `Layer`s may be
394 //! combined with _per-layer filters_ that control what spans and events are
399 //! A `Layer` that implements a filtering strategy should override the
404 //! Note that the [`Layer::register_callsite`] and [`Layer::enabled`] methods
406 //! **not** be used to indicate whether an individual layer wishes to record a
407 //! particular span or event. Instead, if a layer is only interested in a subset
409 //! rest of the layer stack should ignore those spans and events in its
412 //! The filtering methods on a stack of `Layer`s are evaluated in a top-down
413 //! order, starting with the outermost `Layer` and ending with the wrapped
414 //! [`Subscriber`]. If any layer returns `false` from its [`enabled`] method, or
423 //! `Layer`s that implement filtering should attempt to disable unwanted
440 //! ## Per-Layer Filtering
442 //! **Note**: per-layer filtering APIs currently require the [`"registry"` crate
445 //! Sometimes, it may be desirable for one `Layer` to record a particular subset
447 //! recorded by other `Layer`s. For example:
449 //! - A layer that records metrics may wish to observe only events including
450 //! particular tracked values, while a logging layer ignores those events.
459 //! observed by an individual `Layer`, while still allowing other `Layer`s to
460 //! potentially record them. The [`Layer::with_filter`] method combines a
461 //! `Layer` with a [`Filter`], returning a [`Filtered`] layer.
476 //! # use tracing_subscriber::{filter::filter_fn, Layer};
480 //! # impl<S: Subscriber> Layer<S> for MyLayer<S> {}
483 //! let layer = MyLayer::<S>::new()
492 //! <code>Subscriber</code> capable of supporting <code>Layer</code>s with
493 //! per-layer filters. In the future, new APIs will be added to allow other
494 //! root <code>Subscriber</code>s to support per-layer filters.
499 //! standard out, a [`Filter`] can be added to the access log layer:
508 //! // Add a filter to the access log layer so that it only observes
516 //! // A general-purpose logging layer.
517 //! let fmt_layer = tracing_subscriber::fmt::layer();
527 //! Multiple layers can have their own, separate per-layer filters. A span or
528 //! event will be recorded if it is enabled by _any_ per-layer filter, but it
537 //! let fmt_layer = tracing_subscriber::fmt::layer();
541 //! // log layer, like before.
546 //! // and below to the logging layer.
550 //! // Neither layer will observe this event
553 //! // This event will be observed by the logging layer, but not
554 //! // by the access log layer.
557 //! // This event will be observed only by the access log layer.
564 //! A per-layer filter can be applied to multiple [`Layer`]s at a time, by
565 //! combining them into a [`Layered`] layer using [`Layer::and_then`], and then
566 //! calling [`Layer::with_filter`] on the resulting [`Layered`] layer.
571 //! - A third layer, `layer_c`, which should receive spans and events at
586 //! // Combine `layer_a` and `layer_b` into a `Layered` layer:
588 //! // ...and then add an `INFO` `LevelFilter` to that layer:
598 //! If a [`Filtered`] [`Layer`] is combined with another [`Layer`]
599 //! [`Layer::and_then`], and a filter is added to the [`Layered`] layer, that
600 //! layer will be filtered by *both* the inner filter and the outer filter.
602 //! observed by that layer. This can be used to implement complex filtering
608 //! observed by a layer that collects metrics.
624 //! // A layer that logs events to stdout using the human-readable "pretty"
626 //! let stdout_log = tracing_subscriber::fmt::layer()
629 //! // A layer that logs events to a file.
631 //! let debug_log = tracing_subscriber::fmt::layer()
634 //! // A layer that collects metrics using specific events.
640 //! // Add an `INFO` filter to the stdout logging layer
642 //! // Combine the filtered `stdout_log` layer with the
643 //! // `debug_log` layer, producing a new `Layered` layer.
660 //! // This event will *only* be recorded by the metrics layer.
663 //! // This event will only be seen by the debug log file layer:
666 //! // This event will be seen by both the stdout log layer *and*
667 //! // the debug log file layer, but not by the metrics layer.
675 //! [`register_callsite`]: Layer::register_callsite
676 //! [`enabled`]: Layer::enabled
677 //! [`event_enabled`]: Layer::event_enabled
678 //! [`on_enter`]: Layer::on_enter
679 //! [`Layer::register_callsite`]: Layer::register_callsite
680 //! [`Layer::enabled`]: Layer::enabled
721 /// A `Layer` implements a behavior for recording or collecting traces that can
722 /// be composed together with other `Layer`s to build a [`Subscriber`]. See the
723 /// [module-level documentation](crate::layer) for details.
727 pub trait Layer<S> interface
732 /// Performs late initialization when installing this layer as a
737 /// `Layer`s should not store the [`Dispatch`] pointing to the [`Subscriber`]
743 /// `Dispatch` within a `Layer`, use [`Dispatch::downgrade`] to convert a
757 /// Performs late initialization when attaching a `Layer` to a
760 /// This is a callback that is called when the `Layer` is added to a
761 /// [`Subscriber`] (e.g. in [`Layer::with_subscriber`] and
763 /// [`Subscriber`] has been set as the default, both the `Layer` and
765 /// `Layer` the opportunity to set any of its own fields with values
772 /// **Note** In most cases, `Layer` implementations will not need to
774 /// `Layer` wraps one or more other types that implement `Layer`, like the
776 /// that the inner `Layer`s' `on_layer` methods are called. Otherwise,
777 /// functionality that relies on `on_layer`, such as [per-layer filtering],
782 /// [per-layer filtering]: #per-layer-filtering
788 /// Registers a new callsite with this layer, returning whether or not
789 /// the layer is interested in being notified about the callsite, similarly
797 /// <code>Layer::enabled</code></a>) determine whether a span or event is
798 /// globally enabled, <em>not</em> whether the individual layer will be
810 /// with `Layer`s.
813 /// should be run once per callsite. If the layer wishes to use
822 /// [`self.enabled`]: Layer::enabled()
823 /// [`Layer::enabled`]: Layer::enabled()
824 /// [`on_event`]: Layer::on_event()
825 /// [`on_enter`]: Layer::on_enter()
826 /// [`on_exit`]: Layer::on_exit()
836 /// Returns `true` if this layer is interested in a span or event with the
845 /// <code>Layer::register_callsite</code></a>) determine whether a span or event is
846 /// globally enabled, <em>not</em> whether the individual layer will be
859 /// with `Layer`s.
863 /// [`Layer::register_callsite`]: Layer::register_callsite()
864 /// [`on_event`]: Layer::on_event()
865 /// [`on_enter`]: Layer::on_enter()
866 /// [`on_exit`]: Layer::on_exit()
873 /// Notifies this layer that a new span was constructed with the given
880 // filtering layers to a separate trait, we may no longer want `Layer`s to
887 /// Notifies this layer that a span with the given `Id` recorded the given
894 /// Notifies this layer that a span with the ID `span` recorded that it
907 /// *not* whether the individual `Layer` will be notified about the
908 /// event. This is intended to be used by `Layer`s that implement
909 /// filtering for the entire stack. `Layer`s which do not wish to be
916 /// with `Layer`s.
926 /// Notifies this layer that an event has occurred.
929 /// Notifies this layer that a span with the given ID was entered.
932 /// Notifies this layer that the span with the given ID was exited.
935 /// Notifies this layer that the span with the given ID has been closed.
938 /// Notifies this layer that a span ID has been cloned, and that the
942 /// Composes this layer around the given `Layer`, returning a `Layered`
943 /// struct implementing `Layer`.
945 /// The returned `Layer` will call the methods on this `Layer` and then
946 /// those of the new `Layer`, before calling the methods on the subscriber
950 /// # use tracing_subscriber::layer::Layer;
964 /// impl<S: Subscriber> Layer<S> for FooLayer {
968 /// impl<S: Subscriber> Layer<S> for BarLayer {
999 /// # use tracing_subscriber::layer::Layer;
1004 /// # impl<S: Subscriber> Layer<S> for FooLayer {}
1005 /// # impl<S: Subscriber> Layer<S> for BarLayer {}
1029 /// impl<S: Subscriber> Layer<S> for BazLayer {
1039 fn and_then<L>(self, layer: L) -> Layered<L, Self, S> in and_then()
1041 L: Layer<S>, in and_then()
1045 Layered::new(layer, self, inner_has_layer_filter) in and_then()
1048 /// Composes this `Layer` with the given [`Subscriber`], returning a
1051 /// The returned `Layered` subscriber will call the methods on this `Layer`
1056 /// # use tracing_subscriber::layer::Layer;
1066 /// impl<S: Subscriber> Layer<S> for FooLayer {
1100 /// Combines `self` with a [`Filter`], returning a [`Filtered`] layer.
1103 /// this layer. See [the trait-level documentation][plf] for details on
1104 /// per-layer filtering.
1107 /// [plf]: crate::layer#per-layer-filtering
1118 /// Erases the type of this [`Layer`], returning a [`Box`]ed `dyn
1119 /// Layer` trait object.
1121 /// This can be used when a function returns a `Layer` which may be of
1122 /// one of several types, or when a `Layer` subscriber has a very long type
1132 /// use tracing_subscriber::{Layer, filter::LevelFilter, prelude::*};
1145 /// // Depending on the config, construct a layer of one of several types.
1150 /// tracing_subscriber::fmt::layer()
1153 /// // Selecting the JSON logging format changes the layer's
1158 /// // layer's type again.
1163 /// LogConfig::Stdout => tracing_subscriber::fmt::layer()
1165 /// // layer's type!
1173 /// LogConfig::Stderr => tracing_subscriber::fmt::layer()
1174 /// // Changing the writer changes the layer's type
1177 /// // changes the layer's type to `Filtered<LevelFilter, ...>`.
1188 /// layer's type, so this code *does* compile:
1192 /// # use tracing_subscriber::{Layer, filter::LevelFilter, prelude::*};
1203 /// tracing_subscriber::fmt::layer()
1209 /// // Erase the type by boxing the layer
1213 /// LogConfig::Stdout => tracing_subscriber::fmt::layer()
1217 /// // Erase the type by boxing the layer
1220 /// LogConfig::Stderr => tracing_subscriber::fmt::layer()
1223 /// // Erase the type by boxing the layer
1234 fn boxed(self) -> Box<dyn Layer<S> + Send + Sync + 'static> in boxed()
1237 Self: Layer<S> + Send + Sync + 'static, in boxed()
1256 /// A per-[`Layer`] filter that determines whether a span or event is enabled
1257 /// for an individual layer.
1261 /// [plf]: crate::layer#per-layer-filtering
1264 /// Returns `true` if this layer is interested in a span or event with the
1269 /// wrapped [`Layer`]_. Unlike [`Layer::enabled`], the span or event will
1271 /// the layer [filtered] by this filter will skip recording that span or
1282 /// Returns an [`Interest`] indicating whether this layer will [always],
1304 /// *this* layer, the resulting behavior is somewhat different.
1310 /// [`Interest::never()`][never] for a callsite, _other_ [`Layer`]s may have
1321 /// - all [`Layer`]s that comprise the subscriber include `Filter`s
1343 /// use tracing_subscriber::layer;
1361 /// impl<S> layer::Filter<S> for MyFilter {
1362 /// fn enabled(&self, metadata: &Metadata<'_>, _: &layer::Context<'_, S>) -> bool {
1398 /// Called before the filtered [`Layer]'s [`on_event`], to determine if
1410 /// [`enabled`]: crate::layer::Filter::enabled
1411 /// [`on_event`]: crate::layer::Layer::on_event
1498 /// Extension trait adding a `with(Layer)` combinator to `Subscriber`s.
1500 /// Wraps `self` with the provided `layer`.
1501 fn with<L>(self, layer: L) -> Layered<L, Self> in with()
1503 L: Layer<Self>, in with()
1506 layer.with_subscriber(self) in with()
1510 /// A layer that does nothing.
1516 // === impl Layer ===
1522 /// Is a type implementing `Layer` `Option::<_>::None`?
1523 pub(crate) fn layer_is_none<L, S>(layer: &L) -> bool in layer_is_none()
1525 L: Layer<S>, in layer_is_none()
1532 // a crate-private type, and is only returned by the `Layer` impl in layer_is_none()
1533 // for `Option`s. However, even if the layer *does* decide to be in layer_is_none()
1536 layer.downcast_raw(TypeId::of::<NoneLayerMarker>()) in layer_is_none()
1550 // a crate-private type, and is only returned by the `Layer` impl in subscriber_is_none()
1559 impl<L, S> Layer<S> for Option<L>
1561 L: Layer<S>,
1565 if let Some(ref mut layer) = self { in on_layer()
1566 layer.on_layer(subscriber) in on_layer()
1598 // There is no inner layer, so this layer will in max_level_hint()
1760 impl<L, S> Layer<S> for Box<L>
1762 L: Layer<S>,
1768 impl<S> Layer<S> for Box<dyn Layer<S> + Send + Sync>
1777 impl<S, L> Layer<S> for Vec<L>
1779 L: Layer<S>,
1822 // NOTE(eliza): this is slightly subtle: if *any* layer
1824 // no max level hint, since that particular layer cannot
1875 // Someone is looking for per-layer filters. But, this `Vec`
1876 // might contain layers with per-layer filters *and*
1878 // per-layer-filtered layer if *all* its layers have
1879 // per-layer filters.
1902 impl<S: Subscriber> Layer<S> for Identity {}
1905 /// Returns a new `Identity` layer.