Crate timeout_tracing

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::{DefaultTraceCapturer, 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_tracing::timeout(
        Duration::from_secs(1),
        DefaultTraceCapturer, // (3)
        computation(25),
    )
    .await
    {
        Ok(()) => println!("Completed"),
        Err(elapsed) => println!("Timed out at \n{}", elapsed.active_traces[0].span_trace()), // (4)
    }
}

#[instrument] // (5)
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:

Timed out at
   0: basic::step
           with i=9
             at examples/basic.rs:34
   1: basic::computation
           with n=25
             at examples/basic.rs:27

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. DefaultTraceCapturer is the object that captures the stack. The default implementation captures span trace (via tracing-error) and stack trace (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.

Structs

DefaultTraceCapturer

StackAndSpanTrace

TimeoutElapsed

TimeoutFuture

Traits

CaptureTrace

Functions

timeout