diff --git a/tracing-subscriber/src/filter/mod.rs b/tracing-subscriber/src/filter/mod.rs index 3ceb9f33f9..3e011327e1 100644 --- a/tracing-subscriber/src/filter/mod.rs +++ b/tracing-subscriber/src/filter/mod.rs @@ -1,8 +1,10 @@ //! [`Layer`]s that control which spans and events are enabled by the wrapped //! subscriber. //! -//! For details on filtering spans and events using [`Layer`]s, see the [`layer` -//! module documentation]. +//! This module contains a number of types that provide implementations of +//! various strategies for filtering which spans and events are enabled. For +//! details on filtering spans and events using [`Layer`]s, see the +//! [`layer` module's documentation]. //! //! [`layer` module documentation]: crate::layer#filtering-with-layers //! [`Layer`]: crate::layer diff --git a/tracing-subscriber/src/layer/mod.rs b/tracing-subscriber/src/layer/mod.rs index bbd1756815..90b9ec4728 100644 --- a/tracing-subscriber/src/layer/mod.rs +++ b/tracing-subscriber/src/layer/mod.rs @@ -202,6 +202,14 @@ //! potentially record them. The [`Layer::with_filter`] method combines a //! `Layer` with a [`Filter`], returning a [`Filtered`] layer. //! +//! This crate's [`filter`] module provides a number of types which implement +//! the [`Filter`] trait, such as [`LevelFilter`], [`Targets`], and +//! [`FilterFn`]. These [`Filter`]s provide ready-made implementations of +//! common forms of filtering. For custom filtering policies, the [`FilterFn`] +//! and [`DynFilterFn`] types allow implementing a [`Filter`] with a closure or +//! function pointer. In addition, when more control is required, the [`Filter`] +//! trait may also be implemented for user-defined types. +//! //!
//!
 //!     Warning: Currently, the 
@@ -396,6 +404,10 @@
 //! [`Layer::enabled`]: Layer::enabled
 //! [`Interest::never()`]: https://docs.rs/tracing-core/latest/tracing_core/subscriber/struct.Interest.html#method.never
 //! [`Filtered`]: crate::filter::Filtered
+//! [`filter`]: crate::filter
+//! [`Targets`]: crate::filter::Targets
+//! [`FilterFn`]: crate::filter::FilterFn
+//! [`DynFilterFn`]: crate::filter::DynFilterFn
 //! [level]: tracing_core::Level
 //! [`INFO`]: tracing_core::Level::INFO
 //! [`DEBUG`]: tracing_core::Level::DEBUG
diff --git a/tracing-subscriber/src/lib.rs b/tracing-subscriber/src/lib.rs
index 67fa24b0fa..a9059071b7 100644
--- a/tracing-subscriber/src/lib.rs
+++ b/tracing-subscriber/src/lib.rs
@@ -14,6 +14,30 @@
 //!
 //! [msrv]: #supported-rust-versions
 //!
+//! ## `Layer`s and `Filter`s
+//!
+//! The most important component of the `tracing-subscriber` API is the
+//! [`Layer`] trait, which provides a composable abstraction for building
+//! [`Subscriber`]s. Like the [`Subscriber`] trait, a [`Layer`] defines a
+//! particular behavior for collecting trace data. Unlike [`Subscriber`]s,
+//! which implement a *complete* strategy for how trace data is collected,
+//! [`Layer`]s provide *modular* implementations of specific behaviors.
+//! Therefore, they can be [composed together] to form a [`Subscriber`] which is
+//! capable of recording traces in a variety of ways. See the [`layer` module's
+//! documentation][layer] for details on using [`Layer`]s.
+//!
+//! In addition, the [`Filter`] trait defines an interface for filtering what
+//! spans and events are recorded by a particular layer. This allows different
+//! [`Layer`]s to handle separate subsets of the trace data emitted by a
+//! program. See the [documentation on per-layer filtering][plf] for more
+//! information on using [`Filter`]s.
+//!
+//! [`Layer`]: crate::layer::Layer
+//! [composed together]: crate::layer#composing-layers
+//! [layer]: crate::layer
+//! [`Filter`]: crate::layer::Filter
+//! [plf]: crate::layer#per-layer-filtering
+//!
 //! ## Included Subscribers
 //!
 //! The following `Subscriber`s are provided for application authors: