subscriber: add example of Option<Layer>

tracing-subscriber/src/layer/mod.rs

@@ -395,40 +395,80 @@
 //!
 //! ## Runtime Configuration With 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:
+//! 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>> {
+//! # use std::path::PathBuf;
+//! # struct Config {
+//! #    is_prod: bool,
+//! #    path: PathBuf,
+//! # }
+//! # let cfg = Config { is_prod: false, path: PathBuf::from("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(()) }
 //! ```
-//! # // wrap this in a function so we don't actually create `debug.log` when
-//! # // running the doctests..
+//!
+//! 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:
+//!
+//! ```
+//! # use std::path::PathBuf;
 //! # fn docs() -> Result<(), Box<dyn std::error::Error + 'static>> {
+//! # struct Config {
+//! #    is_prod: bool,
+//! #    path: PathBuf,
+//! # }
+//! # let cfg = Config { is_prod: false, path: PathBuf::from("debug.log") };
+//! use std::{fs::File, sync::Arc};
 //! use tracing_subscriber::{Registry, prelude::*};
-//! use std::{fs::File, sync::Arc, path::PathBuf};
-//! let stdout_log = tracing_subscriber::fmt::layer()
-//!     .pretty();
 //!
-//! // If the LOG_PATH environment variable is set, also log events
-//! // to that file. If the environment variable is not set, then `debug_log`
-//! // will be `None`.
-//! let debug_log = match std::env::var("LOG_PATH") {
-//!     Ok(path) => {
-//!         let mut path = PathBuf::from(path);
-//!         path.push("debug.log");
-//!         let file = File::create(path)?;
-//!         let layer = tracing_subscriber::fmt::layer()
-//!             .with_writer(Arc::new(file));
-//!         Some(layer)
-//!     },
-//!     Err(_) => None,
+//! let stdout_log = tracing_subscriber::fmt::layer().pretty();
+//! let subscriber = Registry::default().with(stdout_log);
+//!
+//! // if cfg.is_prod is true, also log JSON-based logs to a file.
+//! // note: in reality, https://crates.io/crates/tracing-appender should
+//! // be used instead of the example below.
+//! 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
 //! };
 //!
-//! let subscriber = Registry::default()
-//!     .with(stdout_log)
-//!     // If the log file is not enabled, `debug_log` 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`.
-//!     .with(debug_log);
+//! // If cfg.is_prod file 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");
@@ -444,6 +484,7 @@
 //! [`Layer::register_callsite`]: Layer::register_callsite
 //! [`Layer::enabled`]: Layer::enabled
 //! [`Interest::never()`]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/struct.Interest.html#method.never
+//! [option-impl]: crate::layer::Layer#impl-Layer<S>-for-Option<L>
 //! [`Filtered`]: crate::filter::Filtered
 //! [`filter`]: crate::filter
 //! [`Targets`]: crate::filter::Targets