Skip to content

Commit

Permalink
subscriber: document boxed Layers (tokio-rs#2023)
Browse files Browse the repository at this point in the history 
Currently, there is an `impl<S: Subscriber> Layer for Box<dyn
Layer<S> + Send + Sync>` intended to allow type-erasing a subscriber.
This change improves the documentation on runtime configuration of
layers to include an example of using `Box` to type-erase a
layer.

Signed-off-by: Eliza Weisman <[email protected]>
  • Loading branch information
@hawkw @kaffarell
hawkw authored and kaffarell committed May 22, 2024
1 parent 2543581 commit 47378c7
Showing 1 changed file with 136 additions and 83 deletions.
219 changes: 136 additions & 83 deletions tracing-subscriber/src/layer/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
//! [`Subscriber`] behavior; it can _observe_ events and spans, but does not
//! assign IDs.
//!
//! ## Composing Layers
//! # 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
Expand Down Expand Up @@ -135,9 +135,140 @@
//! [`Layer::with_subscriber`] as an implementation detail, as `with_subscriber`
//! calls must be nested, leading to less clear code for the reader.
//!
//! ## Runtime Configuration With `Layer`s
//!
//! In some cases, a particular [`Layer`] may be enabled or disabled based on
//! runtime configuration. This can introduce challenges, because the type of a
//! layered [`Subscriber`] depends on which layers are added to it: if an `if`
//! or `match` expression adds some [`Layer`] implementation in one branch,
//! and other layers in another, the [`Subscriber`] values returned by those
//! branches will have different types. For example, the following _will not_
//! work:
//!
//! ```compile_fail
//! # fn docs() -> Result<(), Box<dyn std::error::Error + 'static>> {
//! # struct Config {
//! # is_prod: bool,
//! # path: &'static str,
//! # }
//! # let cfg = Config { is_prod: false, path: "debug.log" };
//! use std::fs::File;
//! use tracing_subscriber::{Registry, prelude::*};
//!
//! let stdout_log = tracing_subscriber::fmt::layer().pretty();
//! let subscriber = Registry::default().with(stdout_log);
//!
//! // The compile error will occur here because the if and else
//! // branches have different (and therefore incompatible) types.
//! let subscriber = if cfg.is_prod {
//! let file = File::create(cfg.path)?;
//! let layer = tracing_subscriber::fmt::layer()
//! .json()
//! .with_writer(Arc::new(file));
//! layer.with(subscriber)
//! } else {
//! layer
//! };
//!
//! tracing::subscriber::set_global_default(subscriber)
//! .expect("Unable to set global subscriber");
//! # Ok(()) }
//! ```
//!
//! However, a [`Layer`] wrapped in an [`Option`] [also implements the `Layer`
//! trait][option-impl]. This allows individual layers to be enabled or disabled at
//! runtime while always producing a [`Subscriber`] of the same type. For
//! example:
//!
//! ```
//! # fn docs() -> Result<(), Box<dyn std::error::Error + 'static>> {
//! # struct Config {
//! # is_prod: bool,
//! # path: &'static str,
//! # }
//! # let cfg = Config { is_prod: false, path: "debug.log" };
//! use std::fs::File;
//! use tracing_subscriber::{Registry, prelude::*};
//!
//! let stdout_log = tracing_subscriber::fmt::layer().pretty();
//! let subscriber = Registry::default().with(stdout_log);
//!
//! // if `cfg.is_prod` is true, also log JSON-formatted logs to a file.
//! let json_log = if cfg.is_prod {
//! let file = File::create(cfg.path)?;
//! let json_log = tracing_subscriber::fmt::layer()
//! .json()
//! .with_writer(file);
//! Some(json_log)
//! } else {
//! None
//! };
//!
//! // If `cfg.is_prod` is false, then `json` will be `None`, and this layer
//! // will do nothing. However, the subscriber will still have the same type
//! // regardless of whether the `Option`'s value is `None` or `Some`.
//! let subscriber = subscriber.with(json_log);
//!
//! tracing::subscriber::set_global_default(subscriber)
//! .expect("Unable to set global subscriber");
//! # Ok(()) }
//! ```
//!
//! If a [`Layer`] may be one of several different types, note that [`Box<dyn
//! Layer<C> + Send + Sync>` implements `Layer`][box-impl].
//! This may be used to erase the type of a [`Layer`].
//!
//! For example, a function that configures a [`Layer`] to log to one of
//! several outputs might return a `Box<dyn Layer<C> + Send + Sync + 'static>`:
//! ```
//! use tracing_subscriber::{
//! Layer,
//! registry::LookupSpan,
//! prelude::*,
//! };
//! use std::{path::PathBuf, fs::File, io};
//!
//! /// Configures whether logs are emitted to a file, to stdout, or to stderr.
//! pub enum LogConfig {
//! File(PathBuf),
//! Stdout,
//! Stderr,
//! }
//!
//! impl LogConfig {
//! pub fn layer<C>(self) -> Box<dyn Layer<C> + Send + Sync + 'static>
//! where
//! C: tracing_core::Subscriber + Send + Sync,
//! for<'a> C: LookupSpan<'a>,
//! {
//! // Shared configuration regardless of where logs are output to.
//! let fmt = tracing_subscriber::fmt::layer()
//! .with_target(true)
//! .with_thread_names(true);
//!
//! // Configure the writer based on the desired log target:
//! match self {
//! LogConfig::File(path) => {
//! let file = File::create(path).expect("failed to create log file");
//! Box::new(fmt.with_writer(file))
//! },
//! LogConfig::Stdout => Box::new(fmt.with_writer(io::stdout)),
//! LogConfig::Stderr => Box::new(fmt.with_writer(io::stderr)),
//! }
//! }
//! }
//!
//! let config = LogConfig::Stdout;
//! tracing_subscriber::registry()
//! .with(config.layer())
//! .init();
//! ```
//!
//! [prelude]: crate::prelude
//! [box-impl]: #impl-Layer<S>-for-Box<dyn Layer<S> + Send + Sync>
//! [prelude]: crate::prelude
//!
//! ## Recording Traces
//! # Recording Traces
//!
//! The [`Layer`] trait defines a set of methods for consuming notifications from
//! tracing instrumentation, which are generally equivalent to the similarly
Expand All @@ -146,7 +277,7 @@
//! information provided by the wrapped subscriber (such as [the current span])
//! to the layer.
//!
//! ## Filtering with `Layer`s
//! # 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
Expand All @@ -158,7 +289,7 @@
//! combined with _per-layer filters_ that control what spans and events are
//! recorded by those layers.
//!
//! ### Global Filtering
//! ## Global Filtering
//!
//! A `Layer` that implements a filtering strategy should override the
//! [`register_callsite`] and/or [`enabled`] methods. It may also choose to implement
Expand All @@ -179,7 +310,7 @@
//! [`Interest::never()`] from its [`register_callsite`] method, filter
//! evaluation will short-circuit and the span or event will be disabled.
//!
//! ### Per-Layer Filtering
//! ## Per-Layer Filtering
//!
//! **Note**: per-layer filtering APIs currently require the [`"registry"` crate
//! feature flag][feat] to be enabled.
Expand Down Expand Up @@ -393,84 +524,6 @@
//! # Ok(()) }
//! ```
//!
//! ## Runtime Configuration With Layers
//!
//! In some cases, a particular [`Layer`] may be enabled or disabled based on
//! runtime configuration. This can introduce challenges, because the type of a
//! layered [`Subscriber`] depends on which layers are added to it: if an `if`
//! or `match` expression adds some [`Layer`]s in one branch and other layers
//! in another, the [`Subscriber`] values returned by those branches will have
//! different types. For example, the following _will not_ work:
//!
//! ```compile_fail
//! # fn docs() -> Result<(), Box<dyn std::error::Error + 'static>> {
//! # struct Config {
//! # is_prod: bool,
//! # path: &'static str,
//! # }
//! # let cfg = Config { is_prod: false, path: "debug.log" };
//! use std::{fs::File, sync::Arc};
//! use tracing_subscriber::{Registry, prelude::*};
//!
//! let stdout_log = tracing_subscriber::fmt::layer().pretty();
//! let subscriber = Registry::default().with(stdout_log);
//!
//! // The compile error will occur here because the if and else
//! // branches have different (and therefore incompatible) types.
//! let subscriber = if cfg.is_prod {
//! let file = File::create(cfg.path)?;
//! let layer = tracing_subscriber::fmt::layer()
//! .json()
//! .with_writer(Arc::new(file));
//! subscriber.with(layer)
//! } else {
//! subscriber
//! };
//!
//! tracing::subscriber::set_global_default(subscriber)
//! .expect("Unable to set global subscriber");
//! # Ok(()) }
//! ```
//!
//! However, a [`Layer`] wrapped in an [`Option`] [also implements the `Layer`
//! trait][option-impl]. This allows individual layers to be enabled or disabled at
//! runtime while always producing a [`Subscriber`] of the same type. For
//! example:
//!
//! ```
//! # fn docs() -> Result<(), Box<dyn std::error::Error + 'static>> {
//! # struct Config {
//! # is_prod: bool,
//! # path: &'static str,
//! # }
//! # let cfg = Config { is_prod: false, path: "debug.log" };
//! use std::{fs::File, sync::Arc};
//! use tracing_subscriber::{Registry, prelude::*};
//!
//! let stdout_log = tracing_subscriber::fmt::layer().pretty();
//! let subscriber = Registry::default().with(stdout_log);
//!
//! // if `cfg.is_prod` is true, also log JSON-formatted logs to a file.
//! let json_log = if cfg.is_prod {
//! let file = File::create(cfg.path)?;
//! let json_log = tracing_subscriber::fmt::layer()
//! .json()
//! .with_writer(Arc::new(file));
//! Some(json_log)
//! } else {
//! None
//! };
//!
//! // If `cfg.is_prod` is false, then `json` will be `None`, and this layer
//! // will do nothing. However, the subscriber will still have the same type
//! // regardless of whether the `Option`'s value is `None` or `Some`.
//! let subscriber = subscriber.with(json_log);
//!
//! tracing::subscriber::set_global_default(subscriber)
//! .expect("Unable to set global subscriber");
//! # Ok(()) }
//! ```
//!
//! [`Subscriber`]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/trait.Subscriber.html
//! [span IDs]: https://docs.rs/tracing-core/latest/tracing_core/span/struct.Id.html
//! [the current span]: Context::current_span
Expand Down

0 comments on commit 47378c7

Please sign in to comment.