[][src]Struct tracing_error::SpanTrace

pub struct SpanTrace { /* fields omitted */ }

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.


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.


impl SpanTrace[src]

pub fn capture() -> Self[src]

Capture the current span trace.


use tracing_error::SpanTrace;

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

pub fn my_function(arg: &str) -> Result<(), MyError> {
    if some_error_condition() {
        return Err(MyError {
            span_trace: SpanTrace::capture(),
            // ...

    // ...

pub fn with_spans(
    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[src]

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[src]

impl Debug for SpanTrace[src]

impl Display for SpanTrace[src]

Auto Trait Implementations

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized

impl<T> Borrow<T> for T where
    T: ?Sized

impl<T> BorrowMut<T> for T where
    T: ?Sized

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 

impl<T> ToOwned for T where
    T: Clone

type Owned = T

The resulting type after obtaining ownership.

impl<T> ToString for T where
    T: Display + ?Sized

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.