add support for conditional capture of span traces (#33)

* add support for conditional capture of span traces

* document how to disable spantraces

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "color-eyre"
-version = "0.4.1"
+version = "0.4.2"
 authors = ["Jane Lusby <jlusby@yaah.dev>"]
 edition = "2018"
 license = "MIT OR Apache-2.0"

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

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() {
+        let span_trace =
-            Some(SpanTrace::capture())
+            if Self::should_capture_spantrace() && get_deepest_spantrace(error).is_none() {
-        } else {
+                Some(SpanTrace::capture())
-            None
+            } 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() {