Module tracing_core::dispatcher

Dispatches trace events to Subscribers.

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 use set_global_default instead.

Finally, tokio users should note that versions of tokio >= 0.1.22 support an experimental-tracing feature flag. When this flag is enabled, the tokio runtime's thread pool will automatically propagate the default subscriber. This means that if tokio::runtime::Runtime::new() or tokio::run() are invoked when a default subscriber is set, it will also be set by all worker threads created by that runtime.

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	Dispatch trace data to a Subscriber.
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.)
with_default	Sets this dispatch as the default for the duration of a closure.