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::{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.

Structs

CaptureSpanAndStackTrace

Implementation of CaptureTrace that captures both a span trace using tracing_error::SpanTrace and a stack trace. tracing must be initialized with tracing_error::ErrorLayer for the span trace to be captured successfully and RUST_BACKTRACE environment variable must be set for the stack trace to be captured.

CaptureSpanTrace

Implementation of CaptureTrace that captures span trace using tracing_error::SpanTrace. tracing must be initialized with tracing_error::ErrorLayer for the trace to be captured successfully.

StackAndSpanTrace

TimeoutElapsed

TimeoutFuture

Traits

CaptureTrace

A trait to support custom implementations of traces

Functions

timeout

Drive the future fut to completion, while limiting its run time to duration. If fut fails to finish within furation, returns span traces for all active await points within fut. Use capture to specify which kind of trace should be captured.