Crate await_tree

Generate accurate and informative tree dumps of asynchronous tasks.

Example

Below is a basic example of how to trace asynchronous tasks with the global registry of the await-tree crate.

async fn bar(i: i32) {
    // `&'static str` span
    baz(i).instrument_await("baz in bar").await
}

async fn baz(i: i32) {
    // runtime `String` span is also supported
    work().instrument_await(span!("working in baz {i}")).await
}

async fn foo() {
    // spans of joined futures will be siblings in the tree
    join(
        bar(3).instrument_await("bar"),
        baz(2).instrument_await("baz"),
    )
    .await;
}

// Init the global registry to start tracing the tasks.
await_tree::init_global_registry(Default::default());
// Spawn a task with root span "foo" and key "foo".
await_tree::spawn("foo", "foo", foo());
// Let the tasks run for a while.
sleep(Duration::from_secs(1)).await;
// Get the tree of the task with key "foo".
let tree = Registry::current().get("foo").unwrap();

// foo [1.006s]
//   bar [1.006s]
//     baz in bar [1.006s]
//       working in baz 3 [1.006s]
//   baz [1.006s]
//     working in baz 2 [1.006s]
println!("{tree}");

Macros

span

Creates a new span with formatted name.

Structs

AnyKey

Type-erased key for the Registry.

Config

Configuration for an await-tree registry, which affects the behavior of all await-trees in the registry.

ConfigBuilder

Builder for Config.

Instrumented

The future for InstrumentAwait.

Registry

The registry of multiple await-trees.

Span

A cheaply cloneable span in the await-tree.

Tree

An await-tree for a task.

TreeRoot

The root of an await-tree.

Enums

ConfigBuilderError

Error type for ConfigBuilder

Traits

InstrumentAwait

Attach spans to a future to be traced in the await-tree.

Key

A key that can be used to identify a task and its await-tree in the Registry.

SpanExt

Convert a value into a span and set attributes.

Functions

current_tree

Get the await-tree of current task. Returns None if we’re not instrumented.

init_global_registry

Initialize the global registry with the given configuration. Panics if the global registry has already been initialized.