diff --git a/tracing-core/src/callsite.rs b/tracing-core/src/callsite.rs index 55728821f6..573125a89a 100644 --- a/tracing-core/src/callsite.rs +++ b/tracing-core/src/callsite.rs @@ -68,6 +68,22 @@ //! configuration changes infrequently, it may be more efficient than calling //! [`Subscriber::enabled`] frequently. //! +//! # Implementing Callsites +//! +//! In most cases, instrumenting code using `tracing` should *not* require +//! implementing the [`Callsite`] trait directly. When using the [`tracing` +//! crate's macros][macros] or the [`#[instrument]` attribute][instrument], a +//! `Callsite` is automatically generated. +//! +//! However, code which provides alternative forms of `tracing` instrumentation +//! may need to interact with the callsite system directly. If +//! instrumentation-side code needs to produce a `Callsite` to emit spans or +//! events, the [`DefaultCallsite`] struct provided in this module is a +//! ready-made `Callsite` implementation that is suitable for most uses. When +//! possible, the use of `DefaultCallsite` should be preferred over implementing +//! [`Callsite`] for user types, as `DefaultCallsite` may benefit from +//! additional performance optimizations. +//! //! [^1]: Returned by the [`Subscriber::register_callsite`][`register_callsite`] //! method. //! @@ -80,6 +96,8 @@ //! [sometimes]: crate::subscriber::Interest::sometimes //! [never]: crate::subscriber::Interest::never //! [`Dispatch`]: crate::dispatch::Dispatch +//! [macros]: https://docs.rs/tracing/latest/tracing/#macros +//! [instrument]: https://docs.rs/tracing/latest/tracing/attr.instrument.html use crate::stdlib::{ any::TypeId, fmt,