🛈 Note: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem.

For the release documentation, please see docs.rs, instead.

tracing/
collect.rs

1//! Collects and records trace data.
2pub use tracing_core::collect::*;
3
4#[cfg(feature = "std")]
5#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
6pub use tracing_core::dispatch::DefaultGuard;
7
8/// Sets this collector as the default for the current thread for the duration
9/// of a closure.
10///
11/// The default collector is used when creating a new [`Span`] or
12/// [`Event`].
13///
14/// [`Span`]: super::span::Span
15/// [`Event`]: tracing_core::Event
16#[cfg(feature = "std")]
17#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
18pub fn with_default<T, C>(collector: C, f: impl FnOnce() -> T) -> T
19where
20    C: Collect + Send + Sync + 'static,
21{
22    crate::dispatch::with_default(&crate::Dispatch::new(collector), f)
23}
24
25/// Sets this collector as the global default for the duration of the entire program.
26/// Will be used as a fallback if no thread-local collector has been set in a thread (using `with_default`.)
27///
28/// Can only be set once; subsequent attempts to set the global default will fail.
29/// Returns whether the initialization was successful.
30///
31/// Note: Libraries should *NOT* call `set_global_default()`! That will cause conflicts when
32/// executables try to set them later.
33#[cfg(feature = "alloc")]
34#[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))]
35pub fn set_global_default<C>(collector: C) -> Result<(), SetGlobalDefaultError>
36where
37    C: Collect + Send + Sync + 'static,
38{
39    crate::dispatch::set_global_default(crate::Dispatch::new(collector))
40}
41
42/// Sets the collector as the default for the current thread for the duration of
43/// the lifetime of the returned [`DefaultGuard`].
44///
45/// The default collector is used when creating a new [`Span`] or
46/// [`Event`].
47///
48/// [`Span`]: super::span::Span
49/// [`Event`]: tracing_core::Event
50#[cfg(feature = "std")]
51#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
52#[must_use = "Dropping the guard unregisters the collector."]
53pub fn set_default<C>(collector: C) -> DefaultGuard
54where
55    C: Collect + Send + Sync + 'static,
56{
57    crate::dispatch::set_default(&crate::Dispatch::new(collector))
58}
59
60pub use tracing_core::dispatch::SetGlobalDefaultError;