[−][src]Crate tracing_error
Utilities for enriching error handling with tracing
diagnostic
information.
Overview
tracing
is a framework for instrumenting Rust programs to collect
scoped, structured, and async-aware diagnostics. This crate provides
integrations between tracing
instrumentation and Rust error handling. It
enables enriching error types with diagnostic information from tracing
span contexts, formatting those contexts when errors are displayed, and
automatically generate tracing
[events] when errors occur.
The crate provides the following:
-
SpanTrace
, a captured trace of the currenttracing
span context -
ErrorLayer
, a subscriber layer which enables capturingSpanTrace
s
Note: This crate is currently experimental.
Compiler support: requires rustc
1.39+
Usage
Currently, tracing-error
provides the SpanTrace
type, which captures
the current tracing
span context when it is constructed and allows it to
be displayed at a later time.
This crate does not currently provide any actual error types implementing
std::error::Error
. Instead, user-constructed errors or libraries
implementing error types may capture a SpanTrace
and include it as part
of their error types.
For example:
use std::{fmt, error::Error}; use tracing_error::SpanTrace; #[derive(Debug)] pub struct MyError { context: SpanTrace, // ... } impl fmt::Display for MyError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { // ... format other parts of the error ... self.context.fmt(f)?; // ... format other error context information, cause chain, etc ... } } impl Error for MyError {} impl MyError { pub fn new() -> Self { Self { context: SpanTrace::capture(), // ... other error information ... } } }
In the future, this crate may also provide its own Error
types as well,
for users who do not wish to use other error-handling libraries.
Applications that wish to use tracing-error
-enabled errors should
construct an ErrorLayer
and add it to their [Subscriber
] in order to
enable capturing SpanTrace
s. For example:
use tracing_error::ErrorLayer; use tracing_subscriber::prelude::*; fn main() { let subscriber = tracing_subscriber::Registry::default() // any number of other subscriber layers may be added before or // after the `ErrorLayer`... .with(ErrorLayer::default()); // set the subscriber as the default for the application tracing::subscriber::set_global_default(subscriber); }
Structs
ErrorLayer | |
SpanTrace | A captured trace of |