[−][src]Module tracing::dispatcher
Dispatches trace events to Subscriber
s.
The dispatcher is the component of the tracing system which is responsible for forwarding trace data from the instrumentation points that generate it to the subscriber that collects it.
Using the Trace Dispatcher
Every thread in a program using tracing
has a default subscriber. When
events occur, or spans are created, they are dispatched to the thread's
current subscriber.
Setting the Default Subscriber
By default, the current subscriber is an empty implementation that does
nothing. To use a subscriber implementation, it must be set as the default.
There are two methods for doing so: with_default
and
set_global_default
. with_default
sets the default subscriber for the
duration of a scope, while set_global_default
sets a default subscriber
for the entire process.
To use either of these functions, we must first wrap our subscriber in a
Dispatch
, a cloneable, type-erased reference to a subscriber. For
example:
use dispatcher::Dispatch; let my_subscriber = FooSubscriber::new(); let my_dispatch = Dispatch::new(my_subscriber);
Then, we can use with_default
to set our Dispatch
as the default for
the duration of a block:
// no default subscriber dispatcher::with_default(&my_dispatch, || { // my_subscriber is the default }); // no default subscriber again
It's important to note that with_default
will not propagate the current
thread's default subscriber to any threads spawned within the with_default
block. To propagate the default subscriber to new threads, either use
with_default
from the new thread, or use set_global_default
.
As an alternative to with_default
, we can use set_global_default
to
set a Dispatch
as the default for all threads, for the lifetime of the
program. For example:
// no default subscriber dispatcher::set_global_default(my_dispatch) // `set_global_default` will return an error if the global default // subscriber has already been set. .expect("global default was already set!"); // `my_subscriber` is now the default
Note: The thread-local scoped dispatcher (with_default
) requires the Rust standard library.no_std
users should useset_global_default
instead.
Accessing the Default Subscriber
A thread's current default subscriber can be accessed using the
get_default
function, which executes a closure with a reference to the
currently default Dispatch
. This is used primarily by tracing
instrumentation.
Structs
DefaultGuard | A guard that resets the current default dispatcher to the prior default dispatcher when dropped. |
Dispatch |
|
SetGlobalDefaultError | Returned if setting the global dispatcher fails. |
Functions
get_default | Executes a closure with a reference to this thread's current dispatcher. |
set_default | Sets the dispatch as the default dispatch for the duration of the lifetime of the returned DefaultGuard |
set_global_default | Sets this dispatch as the global default for the duration of the entire program.
Will be used as a fallback if no thread-local dispatch has been set in a thread
(using |
with_default | Sets this dispatch as the default for the duration of a closure. |