Provided Methods

fn instrument(self: 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 or Dropped.

Examples

Instrumenting a future:

use tracing::Instrument;

# async fn doc() {
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;
# mod tokio {
#     pub(super) fn spawn(_: impl std::future::Future) {}
# }

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:
# let my_future = async {};
tokio::spawn(
   my_future
        .instrument(tracing::debug_span!("my_future").or_current())
);

fn in_current_span(self: 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 or Dropped.

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

Examples

use tracing::Instrument;

# mod tokio {
#     pub(super) fn spawn(_: impl std::future::Future) {}
# }
# async fn doc() {
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());
# }