Struct SpanTrace

pub struct SpanTrace { /* private fields */ }

A captured trace of tracing spans.

This type can be thought of as a relative of std::backtrace::Backtrace. However, rather than capturing the current call stack when it is constructed, a SpanTrace instead captures the current span and its parents.

In many cases, span traces may be as useful as stack backtraces useful in pinpointing where an error occurred and why, if not moreso:

• A span trace captures only the user-defined, human-readable tracing spans, rather than every frame in the call stack, often cutting out a lot of noise.
• Span traces include the fields recorded by each span in the trace, as well as their names and source code location, so different invocations of a function can be distinguished,
• In asynchronous code, backtraces for errors that occur in futures often consist not of the stack frames that spawned a future, but the stack frames of the executor that is responsible for running that future. This means that if an async fn calls another async fn which generates an error, the calling async function will not appear in the stack trace (and often, the callee won’t either!). On the other hand, when the tracing-futures crate is used to instrument async code, the span trace will represent the logical application context a future was running in, rather than the stack trace of the executor that was polling a future when an error occurred.

Finally, unlike stack Backtraces, capturing a SpanTrace is fairly lightweight, and the resulting struct is not large. The SpanTrace struct is formatted lazily; instead, it simply stores a copy of the current span, and allows visiting the spans in that span’s trace tree by calling the with_spans method.

Formatting

The SpanTrace type implements fmt::Display, formatting the span trace similarly to how Rust formats panics. For example:

   0: custom_error::do_another_thing
        with answer=42 will_succeed=false
          at examples/examples/custom_error.rs:42
   1: custom_error::do_something
        with foo="hello world"
          at examples/examples/custom_error.rs:37

Additionally, if custom formatting is desired, the with_spans method can be used to visit each span in the trace, formatting them in order.

Implementations

impl SpanTrace

pub fn new(span: Span) -> Self

Create a new span trace with the given span as the innermost span.

pub fn capture() -> Self

Capture the current span trace.

Examples

use tracing_error::SpanTrace;

pub struct MyError {
    span_trace: SpanTrace,
    // ...
}


#[tracing::instrument]
pub fn my_function(arg: &str) -> Result<(), MyError> {
    if some_error_condition() {
        return Err(MyError {
            span_trace: SpanTrace::capture(),
            // ...
        });
    }

    // ...
}

pub fn with_spans( &self, f: impl FnMut(&'static Metadata<'static>, &str) -> bool, )

Apply a function to all captured spans in the trace until it returns false.

This will call the provided function with a reference to the Metadata and a formatted representation of the fields of each span captured in the trace, starting with the span that was current when the trace was captured. The function may return true or false to indicate whether to continue iterating over spans; if it returns false, no additional spans will be visited.

pub fn status(&self) -> SpanTraceStatus

Returns the status of this SpanTrace.

The status indicates one of the following:

• the current subscriber does not support capturing SpanTraces
• there was no current span, so a trace was not captured
• a span trace was successfully captured

Trait Implementations

impl Clone for SpanTrace

fn clone(&self) -> SpanTrace

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SpanTrace

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for SpanTrace

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.