Dispatches trace events toSubscribers.

Thedispatcher is the component of the tracing system which is responsiblefor forwarding trace data from the instrumentation points that generate itto the subscriber that collects it.

§Using the Trace Dispatcher

Every thread in a program usingtracing has adefault subscriber. Whenevents occur, or spans are created, they are dispatched to the thread’scurrent subscriber.

§Setting the Default Subscriber

By default, the current subscriber is an empty implementation that doesnothing. To use a subscriber implementation, it must be set as the default.There are two methods for doing so:with_default andset_global_default.with_default sets the default subscriber for theduration of a scope, whileset_global_default sets a default subscriberfor the entire process.

To use either of these functions, we must first wrap our subscriber in aDispatch, a cloneable, type-erased reference to a subscriber. Forexample:

usedispatcher::Dispatch;letmy_subscriber = FooSubscriber::new();letmy_dispatch = Dispatch::new(my_subscriber);

Then, we can usewith_default to set ourDispatch as the default forthe duration of a block:

// no default subscriberdispatcher::with_default(&my_dispatch, || {// my_subscriber is the default});// no default subscriber again

It’s important to note thatwith_default will not propagate the currentthread’s default subscriber to any threads spawned within thewith_defaultblock. To propagate the default subscriber to new threads, either usewith_default from the new thread, or useset_global_default.

As an alternative towith_default, we can useset_global_default toset aDispatch as the default for all threads, for the lifetime of theprogram. For example:

// no default subscriberdispatcher::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 shoulduseset_global_defaultinstead.

§Accessing the Default Subscriber

A thread’s current default subscriber can be accessed using theget_default function, which executes a closure with a reference to thecurrently defaultDispatch. This is used primarily bytracinginstrumentation.