Module dispatch

Dispatches trace events to Collects.

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 collector that collects it.

Using the Trace Dispatcher

Every thread in a program using tracing has a default collector. When events occur, or spans are created, they are dispatched to the thread’s current collector.

Setting the Default Collector

By default, the current collector is an empty implementation that does nothing. Trace data provided to this “do nothing” implementation is immediately discarded, and is not available for any purpose.

To use another collector 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 collector for the duration of a scope, while set_global_default sets a default collector for the entire process.

To use either of these functions, we must first wrap our collector in a Dispatch, a cloneable, type-erased reference to a collector. For example:

use dispatch::Dispatch;

let my_collector = FooCollector::new();
let my_dispatch = Dispatch::new(my_collector);

Then, we can use with_default to set our Dispatch as the default for the duration of a block:

// no default collector

dispatch::with_default(&my_dispatch, || {
    // my_collector is the default
});

// no default collector again

It’s important to note that with_default will not propagate the current thread’s default collector to any threads spawned within the with_default block. To propagate the default collector 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 collector

dispatch::set_global_default(my_dispatch)
    // `set_global_default` will return an error if the global default
    // collector has already been set.
    .expect("global default was already set!");

// `my_collector` 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.

Accessing the Default Collector

A thread’s current default collector 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

• DefaultGuardstd
  A guard that resets the current default dispatcher to the prior default dispatcher when dropped.
• Dispatch
  Dispatch trace data to a Collect.
• SetGlobalDefaultError
  Returned if setting the global dispatcher fails.
• WeakDispatch
  WeakDispatch is a version of Dispatch that holds a non-owning reference to a collector.

Functions

• get_default
  Executes a closure with a reference to this thread’s current dispatcher.
• set_defaultstd
  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_defaultstd
  Sets this dispatch as the default for the duration of a closure.