1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
//! 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 current `tracing` [span] context
//!
//! * [`ErrorLayer`], a [subscriber layer] which enables capturing `SpanTrace`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:
//!
//! ```rust
//! 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 ...
//! # Ok(())
//! }
//! }
//!
//! 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:
//!
//! ```rust
//! 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);
//! }
//! ```
//!
//! [`SpanTrace`]: struct.SpanTrace.html
//! [`ErrorLayer`]: struct.ErrorLayer.html
//! [span]: https://docs.rs/tracing/latest/tracing/span/index.html
//! [event]: https://docs.rs/tracing/latest/tracing/struct.Event.html
//! [subscriber layer]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/layer/trait.Layer.html
//! [`tracing`]: https://docs.rs/tracing
pub use SpanTrace;
pub use ErrorLayer;