🛈 Note: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem.

For the release documentation, please see docs.rs, instead.

pub struct SpanTrace { /* private fields */ }
Expand description

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§

source§

impl SpanTrace

source

pub fn new(span: Span) -> Self

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

source

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(),
            // ...
        });
    }

    // ...
}
source

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.

source

pub fn status(&self) -> SpanTraceStatus

Returns the status of this SpanTrace.

The status indicates one of the following:

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

Trait Implementations§

source§

impl Clone for SpanTrace

source§

fn clone(&self) -> SpanTrace

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for SpanTrace

source§

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

Formats the value using the given formatter. Read more
source§

impl Display for SpanTrace

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

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

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

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

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

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

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

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

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

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

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

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

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

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.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithCollector for T

source§

fn with_collector<C>(self, collector: C) -> WithDispatch<Self>
where C: Into<Dispatch>,

Attaches the provided collector to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_collector(self) -> WithDispatch<Self>

Attaches the current default collector to this type, returning a WithDispatch wrapper. Read more