timeout-tracing allows executing an async function with a timeout (much like tokio::time::timeout). When the timeout elapses it returns the exact location where the async code was awaiting at that specific moment.

Basic usage

The basic usage looks as follows:

use std::time::Duration;

use timeout_tracing::{CaptureSpanTrace, timeout};
use tokio::time::sleep;
use tracing::instrument;
use tracing_error::ErrorLayer;
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

#[tokio::main]
async fn main() {
    // (1)
    tracing_subscriber::registry()
        .with(ErrorLayer::default())
        .init();

    // (2)
    match timeout(Duration::from_secs(1), CaptureSpanTrace, computation(25)).await {
        Ok(()) => println!("Completed"),
        Err(elapsed) => println!("{elapsed}"), // (4)
    }
}

// (5)
#[instrument]
async fn computation(n: i32) {
    for i in 0..n {
        step(i).await;
    }
}

#[instrument]
async fn step(i: i32) {
    sleep(Duration::from_millis(100)).await;
}

This prints out:

timeout elapsed at:
trace 0:
   0: basic::step
           with i=9
             at examples/basic.rs:31
   1: basic::computation
           with n=25
             at examples/basic.rs:24

1. tracing-error must be initialized, as it is used (by default) to gather span traces.
2. timeout_tracing::timeout executes the future with a timeout
3. CaptureSpanTrace is the object that captures the stack. The default implementation captures span trace (via tracing-error). It is also possible to capture a stack trace as well using CaptureSpanAndStackTrace (via Rust standard library; the RUST_BACKTRACE=1 environment variable must be set for stack trace capture to work)
4. If the future does not complete within the given time limit, an error is returned. It contains a set of traces for each active leaf await point within the future.
5. The executed functions should be instrumented with tokio-tracing spans (for example, by using the #[tokio-tracing::instrument] macro) for span trace to work.