diff --git a/tracing-subscriber/src/filter/mod.rs b/tracing-subscriber/src/filter/mod.rs index ffb2c26c47..3c7e99cccf 100644 --- a/tracing-subscriber/src/filter/mod.rs +++ b/tracing-subscriber/src/filter/mod.rs @@ -1,11 +1,13 @@ //! [`Subscriber`]s that control which spans and events are enabled by the wrapped -//! subscriber. +//! collector. //! -//! For details on filtering spans and events using [`Subscribe`]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 [`Subscriber`]s, see the +//! [`subscriber` module's documentation]. //! -//! [`layer` module documentation]: crate::layer#filtering-with-layers -//! [`Layer`]: crate::layer +//! [`subscriber` module documentation]: crate::subscribe#filtering-with-layers +//! [`Subscriber`]: crate::subscriber #[cfg(feature = "env-filter")] mod env; mod level; diff --git a/tracing-subscriber/src/lib.rs b/tracing-subscriber/src/lib.rs index a372b3abc7..20039ff6c9 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 `Collector`s are provided for application authors: diff --git a/tracing-subscriber/src/subscribe/mod.rs b/tracing-subscriber/src/subscribe/mod.rs index 13c0ab1527..475d138b76 100644 --- a/tracing-subscriber/src/subscribe/mod.rs +++ b/tracing-subscriber/src/subscribe/mod.rs @@ -204,6 +204,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 
@@ -398,6 +406,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