Trait tracing::Instrument

pub trait Instrument: Sized {
    // Provided methods
    fn instrument(self, span: Span) -> Instrumented<Self>  { ... }
    fn in_current_span(self) -> Instrumented<Self>  { ... }
}

Attaches spans to a std::future::Future.

Extension trait allowing futures to be instrumented with a tracing span.

Provided Methods

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper.

The attached Span will be entered every time the instrumented Future is polled.

Examples

Instrumenting a future:

use tracing::Instrument;

let my_future = async {
    // ...
};

my_future
    .instrument(tracing::info_span!("my_future"))
    .await

The Span::or_current combinator can be used in combination with instrument to ensure that the current span is attached to the future if the span passed to instrument is disabled:

use tracing::Instrument;

let my_future = async {
    // ...
};

let outer_span = tracing::info_span!("outer").entered();

// If the "my_future" span is enabled, then the spawned task will
// be within both "my_future" *and* "outer", since "outer" is
// "my_future"'s parent. However, if "my_future" is disabled,
// the spawned task will *not* be in any span.
tokio::spawn(
    my_future
        .instrument(tracing::debug_span!("my_future"))
);

// Using `Span::or_current` ensures the spawned task is instrumented
// with the current span, if the new span passed to `instrument` is
// not enabled. This means that if the "my_future"  span is disabled,
// the spawned task will still be instrumented with the "outer" span:
tokio::spawn(
   my_future
        .instrument(tracing::debug_span!("my_future").or_current())
);

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper.

The attached Span will be entered every time the instrumented Future is polled.

This can be used to propagate the current span when spawning a new future.

Examples

use tracing::Instrument;

let span = tracing::info_span!("my_span");
let _enter = span.enter();

// ...

let future = async {
    tracing::debug!("this event will occur inside `my_span`");
    // ...
};
tokio::spawn(future.in_current_span());

Object Safety

This trait is not object safe.

Implementors

impl<T: Sized> Instrument for T