tokio-rs · hawkw · Sep 29, 2021 · Sep 24, 2021 · Sep 24, 2021 · Sep 24, 2021
@@ -118,7 +118,7 @@ use tracing_core::{Interest, Metadata, Subscriber};
 /// };
 /// use tracing_core::Level;
 /// use std::{sync::Arc, fs::File};
-/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+/// # fn docs() -> Result<(), Box<dyn std::error::Error>> {
 ///
 /// // A layer that logs events to stdout using the human-readable "pretty"
 /// // format.

@@ -393,6 +393,38 @@
 //! # Ok(()) }
 //! ```
 //!
+//! ## Runtime-configurable Layers
+//!
+//! Conditionally enabling/disabling layers at runtime can be challenging due to the generics
+//! used Layers implementations. However, A Layer wrapped in an `Option` is also Layers, which
+//! allows some runtime configuration:
-//! Conditionally enabling/disabling layers at runtime can be challenging due to the generics
-//! used Layers implementations. However, A Layer wrapped in an `Option` is also Layers, which
-//! allows some runtime configuration:
+//! 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.
+//!
+//! 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:
+//!
+//! [option-impl]: crate::layer::Layer#impl-Layer<S>-for-Option<L>
-//! Conditionally enabling/disabling layers at runtime can be challenging due to the generics
-//! used Layers implementations. However, A Layer wrapped in an `Option` is also Layers, which
-//! allows some runtime configuration:
+//! 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.
+//!
+//! 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:
+//!
+//! [option-impl]: crate::layer::Layer#impl-Layer<S>-for-Option<L>
+//!
+//! ```
+//! // wrap this in a function so we don't actually create `debug.log` when
+//! // running the doctests..
+//! # fn docs() -> Result<(), Box<dyn std::error::Error + 'static>> {
+//! use tracing_subscriber::{Registry, prelude::*};
+//! use std::{fs::File, sync::Arc};
+//! let stdout_log = tracing_subscriber::fmt::layer()
-//! use std::{fs::File, sync::Arc};
-//! let stdout_log = tracing_subscriber::fmt::layer()
+//! use std::{fs::File, sync::Arc};
+//!
+//! let stdout_log = tracing_subscriber::fmt::layer()
-//! use std::{fs::File, sync::Arc};
-//! let stdout_log = tracing_subscriber::fmt::layer()
+//! use std::{fs::File, sync::Arc};
+//!
+//! // Always log to stdout in a human-readable format.
+//! let stdout_log = tracing_subscriber::fmt::layer()
-//! use std::{fs::File, sync::Arc};
-//! let stdout_log = tracing_subscriber::fmt::layer()
+//! use std::{fs::File, sync::Arc};
+//!
+//! let stdout_log = tracing_subscriber::fmt::layer()
-//! use std::{fs::File, sync::Arc};
-//! let stdout_log = tracing_subscriber::fmt::layer()
+//! use std::{fs::File, sync::Arc};
+//!
+//! // Always log to stdout in a human-readable format.
+//! let stdout_log = tracing_subscriber::fmt::layer()
+//!     .pretty();
+//!
+//! let debug_log = match std::env::var("LOG_PATH") {
+//!     Ok(path) => {
+//!         let file = File::create("debug.log")?;
+//!         let layer = tracing_subscriber::fmt::layer()
+//!             .with_writer(Arc::new(file));
+//!         Some(layer)
+//!     },
+//!     Err(_) => None,
+//! };
+//!
+//! let subscriber = Registry::default()
+//!     .with(stdout_log)
+//!     .with(debug_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