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

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

tracing_core::dispatch

Struct Dispatch

Source
pub struct Dispatch { /* private fields */ }
Expand description

Dispatch trace data to a Collect.

Implementations§

Source§

impl Dispatch

Source

pub fn none() -> Self

Returns a new Dispatch that discards events and spans.

Source

pub fn new<C>(collector: C) -> Self
where C: Collect + Send + Sync + 'static,

Available on crate features std or alloc only.

Returns a Dispatch that forwards to the given Collect.

Source

pub fn from_static(collector: &'static (dyn Collect + Send + Sync)) -> Self

Returns a Dispatch that forwards to the given static collector.

Unlike Dispatch::new, this function is always available on all platforms, even when the std or alloc features are disabled.

In order to use from_static, the Collector itself must be stored in a static. For example:

struct MyCollector {
   // ...
}

impl tracing_core::Collect for MyCollector {
    // ...
}

static COLLECTOR: MyCollector = MyCollector {
    // ...
};

fn main() {
    use tracing_core::dispatch::{self, Dispatch};

    let dispatch = Dispatch::from_static(&COLLECTOR);

    dispatch::set_global_default(dispatch)
        .expect("no global default collector should have been set previously!");
}

Constructing the collector in a static initializer may make some forms of runtime configuration more challenging. If this is the case, users with access to liballoc or the Rust standard library are encouraged to use Dispatch::new rather than from_static. no_std users who cannot allocate or do not have access to liballoc may want to consider the once_cell crate, or another library which allows lazy initialization of statics.

Source

pub fn downgrade(&self) -> WeakDispatch

Creates a WeakDispatch from this Dispatch.

A WeakDispatch is similar to a Dispatch, but it does not prevent the underlying collector from being dropped. Instead, it only permits access while other references to the collector exist. This is equivalent to the standard library’s Arc::downgrade method, but for Dispatch rather than Arc.

The primary use for creating a WeakDispatch is to allow a collector to hold a cyclical reference to itself without creating a memory leak. See here for details.

Source

pub fn register_callsite( &self, metadata: &'static Metadata<'static>, ) -> Interest

Registers a new callsite with this collector, returning whether or not the collector is interested in being notified about the callsite.

This calls the register_callsite function on the Collect that this Dispatch forwards to.

Source

pub fn new_span(&self, span: &Attributes<'_>) -> Id

Record the construction of a new span, returning a new ID for the span being constructed.

This calls the new_span function on the Collect that this Dispatch forwards to.

Source

pub fn record(&self, span: &Id, values: &Record<'_>)

Record a set of values on a span.

This calls the record function on the Collect that this Dispatch forwards to.

Source

pub fn record_follows_from(&self, span: &Id, follows: &Id)

Adds an indication that span follows from the span with the id follows.

This calls the record_follows_from function on the Collect that this Dispatch forwards to.

Source

pub fn enabled(&self, metadata: &Metadata<'_>) -> bool

Returns true if a span with the specified metadata would be recorded.

This calls the enabled function on the Collect that this Dispatch forwards to.

Source

pub fn event(&self, event: &Event<'_>)

Records that an Event has occurred.

This calls the event function on the Collect that this Dispatch forwards to.

Source

pub fn enter(&self, span: &Id)

Records that a span has been can_enter.

This calls the enter function on the Collect that this Dispatch forwards to.

Source

pub fn exit(&self, span: &Id)

Records that a span has been exited.

This calls the exit function on the Collect that this Dispatch forwards to.

Source

pub fn clone_span(&self, id: &Id) -> Id

Notifies the collector that a span ID has been cloned.

This function must only be called with span IDs that were returned by this Dispatch’s new_span function. The tracing crate upholds this guarantee and any other libraries implementing instrumentation APIs must as well.

This calls the clone_span function on the Collect that this Dispatch forwards to.

Source

pub fn drop_span(&self, id: Id)

👎Deprecated since 0.1.2: use Dispatch::try_close instead

Notifies the collector that a span ID has been dropped.

This function must only be called with span IDs that were returned by this Dispatch’s new_span function. The tracing crate upholds this guarantee and any other libraries implementing instrumentation APIs must as well.

This calls the drop_span function on the Collect that this Dispatch forwards to.

Deprecated: The try_close method is functionally identical, but returns true if the span is now closed. It should be used instead of this method.

Source

pub fn try_close(&self, id: Id) -> bool

Notifies the collector that a span ID has been dropped, and returns true if there are now 0 IDs referring to that span.

This function must only be called with span IDs that were returned by this Dispatch’s new_span function. The tracing crate upholds this guarantee and any other libraries implementing instrumentation APIs must as well.

This calls the try_close function on the Collect trait that this Dispatch forwards to.

Source

pub fn current_span(&self) -> Current

Returns a type representing this collector’s view of the current span.

This calls the current function on the Collect that this Dispatch forwards to.

Source

pub fn is<T: Any>(&self) -> bool

Returns true if this Dispatch forwards to a collector of type T.

Source

pub fn downcast_ref<T: Any>(&self) -> Option<&T>

Returns some reference to the Collect this Dispatch forwards to if it is of type T, or None if it isn’t.

Trait Implementations§

Source§

impl Clone for Dispatch

Source§

fn clone(&self) -> Dispatch

Returns a copy of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Dispatch

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for Dispatch

Source§

fn default() -> Self

Returns the current default dispatcher

Source§

impl<C> From<C> for Dispatch
where C: Collect + Send + Sync + 'static,

Source§

fn from(collector: C) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit #126799)
Performs copy-assignment from self to dst. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.