diff --git a/Cargo.toml b/Cargo.toml index 1231c13..eb7ddc0 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "color-eyre" -version = "0.4.1" +version = "0.4.2" authors = ["Jane Lusby "] edition = "2018" license = "MIT OR Apache-2.0" diff --git a/README.md b/README.md index 64e5223..491160a 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,24 @@ tracing integration to cut down on unused dependencies: color-eyre = { version = "0.4", default-features = false } ``` +### Disabling SpanTrace capture by default + +color-eyre defaults to capturing span traces. This is because `SpanTrace` +capture is significantly cheaper than `Backtrace` capture. However, like +backtraces, span traces are most useful for debugging applications, and it's +not uncommon to want to disable span trace capture by default to keep noise out +of error messages intended for users of an application rather than the +developer. + +To disable span trace capture you must explicitly set one of the env variables +that regulate `SpanTrace` capture to `"0"`: + +```rust +if std::env::var("RUST_SPANTRACE").is_err() { + std::env::set_var("RUST_SPANTRACE", "0"); +} +``` + ### Improving perf on debug builds In debug mode `color-eyre` behaves noticably worse than `eyre`. This is caused diff --git a/src/lib.rs b/src/lib.rs index cdccc48..7962619 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -39,6 +39,24 @@ //! color-eyre = { version = "0.4", default-features = false } //! ``` //! +//! ### Disabling SpanTrace capture by default +//! +//! color-eyre defaults to capturing span traces. This is because `SpanTrace` +//! capture is significantly cheaper than `Backtrace` capture. However, like +//! backtraces, span traces are most useful for debugging applications, and it's +//! not uncommon to want to disable span trace capture by default to keep noise out +//! of error messages intended for users of an application rather than the +//! developer. +//! +//! To disable span trace capture you must explicitly set one of the env variables +//! that regulate `SpanTrace` capture to `"0"`: +//! +//! ```rust +//! if std::env::var("RUST_SPANTRACE").is_err() { +//! std::env::set_var("RUST_SPANTRACE", "0"); +//! } +//! ``` +//! //! ### Improving perf on debug builds //! //! In debug mode `color-eyre` behaves noticably worse than `eyre`. This is caused @@ -199,7 +217,7 @@ //! [`examples/custom_filter.rs`]: https://github.com/yaahc/color-eyre/blob/master/examples/custom_filter.rs //! [`examples/custom_section.rs`]: https://github.com/yaahc/color-eyre/blob/master/examples/custom_section.rs //! [`examples/multiple_errors.rs`]: https://github.com/yaahc/color-eyre/blob/master/examples/multiple_errors.rs -#![doc(html_root_url = "https://docs.rs/color-eyre/0.4.1")] +#![doc(html_root_url = "https://docs.rs/color-eyre/0.4.2")] #![cfg_attr(docsrs, feature(doc_cfg))] #![warn( missing_debug_implementations, @@ -364,6 +382,13 @@ impl Handler { pub fn span_trace(&self) -> Option<&SpanTrace> { self.span_trace.as_ref() } + + // Check if spantrace capture is explicitly disabled + fn should_capture_spantrace() -> bool { + std::env::var("RUST_SPANTRACE") + .map(|val| val != "0") + .unwrap_or(true) + } } impl eyre::EyreHandler for Handler { @@ -376,11 +401,12 @@ impl eyre::EyreHandler for Handler { }; #[cfg(feature = "capture-spantrace")] - let span_trace = if get_deepest_spantrace(error).is_none() { - Some(SpanTrace::capture()) - } else { - None - }; + let span_trace = + if Self::should_capture_spantrace() && get_deepest_spantrace(error).is_none() { + Some(SpanTrace::capture()) + } else { + None + }; Self { backtrace, @@ -439,13 +465,13 @@ impl eyre::EyreHandler for Handler { #[cfg(feature = "capture-spantrace")] { - let span_trace = self + if let Some(span_trace) = self .span_trace .as_ref() .or_else(|| get_deepest_spantrace(error)) - .expect("SpanTrace capture failed"); - - write!(&mut separated.ready(), "{}", FormattedSpanTrace(span_trace))?; + { + write!(&mut separated.ready(), "{}", FormattedSpanTrace(span_trace))?; + } } if let Some(backtrace) = self.backtrace.as_ref() {