Crate color_eyre
source ·Expand description
An error report handler for panics and the eyre
crate for colorful, consistent, and well
formatted error reports for all kinds of errors.
§TLDR
color_eyre
helps you build error reports that look like this:
color-eyre on hooked [$!] is 📦 v0.5.0 via 🦀 v1.44.0 ❯ cargo run --example custom_section Finished dev [unoptimized + debuginfo] target(s) in 0.04s Running `target/debug/examples/custom_section` Error: 0: Unable to read config 1: cmd exited with non-zero status code Stderr: cat: fake_file: No such file or directory ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SPANTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0: custom_section::output2 with self="cat" "fake_file" at examples/custom_section.rs:14 1: custom_section::read_file with path="fake_file" at examples/custom_section.rs:58 2: custom_section::read_config at examples/custom_section.rs:63 Suggestion: try using a file that exists next time
§Setup
Add the following to your toml file:
[dependencies]
color-eyre = "0.6"
And install the panic and error report handlers:
use color_eyre::eyre::Result;
fn main() -> Result<()> {
color_eyre::install()?;
// ...
}
§Disabling tracing support
If you don’t plan on using tracing_error
and SpanTrace
you can disable the
tracing integration to cut down on unused dependencies:
[dependencies]
color-eyre = { version = "0.6", 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
developer.
To disable span trace capture you must explicitly set one of the env variables
that regulate SpanTrace
capture to "0"
:
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
by the fact that eyre
uses std::backtrace::Backtrace
instead of
backtrace::Backtrace
. The std version of backtrace is precompiled with
optimizations, this means that whether or not you’re in debug mode doesn’t
matter much for how expensive backtrace capture is, it will always be in the
10s of milliseconds to capture. A debug version of backtrace::Backtrace
however isn’t so lucky, and can take an order of magnitude more time to capture
a backtrace compared to its std counterpart.
Cargo profile
overrides
can be used to mitigate this problem. By configuring your project to always
build backtrace
with optimizations you should get the same performance from
color-eyre
that you’re used to with eyre
. To do so add the following to
your Cargo.toml:
[profile.dev.package.backtrace]
opt-level = 3
§Features
§Multiple report format verbosity levels
color-eyre
provides 3 different report formats for how it formats the captured SpanTrace
and Backtrace
, minimal, short, and full. Take the below snippets of the output produced by examples/usage.rs
:
Running cargo run --example usage
without RUST_LIB_BACKTRACE
set will produce a minimal
report like this:
color-eyre on hooked [$!] is 📦 v0.5.0 via 🦀 v1.44.0 took 2s ❯ cargo run --example usage Finished dev [unoptimized + debuginfo] target(s) in 0.04s Running `target/debug/examples/usage` Jul 05 19:15:58.026 INFO read_config:read_file{path="fake_file"}: Reading file Error: 0: Unable to read config 1: No such file or directory (os error 2) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SPANTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0: usage::read_file with path="fake_file" at examples/usage.rs:32 1: usage::read_config at examples/usage.rs:38 Suggestion: try using a file that exists next time
Running RUST_LIB_BACKTRACE=1 cargo run --example usage
tells color-eyre
to use the short
format, which additionally capture a backtrace::Backtrace
:
color-eyre on hooked [$!] is 📦 v0.5.0 via 🦀 v1.44.0 ❯ RUST_LIB_BACKTRACE=1 cargo run --example usage Finished dev [unoptimized + debuginfo] target(s) in 0.04s Running `target/debug/examples/usage` Jul 05 19:16:02.853 INFO read_config:read_file{path="fake_file"}: Reading file Error: 0: Unable to read config 1: No such file or directory (os error 2) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SPANTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0: usage::read_file with path="fake_file" at examples/usage.rs:32 1: usage::read_config at examples/usage.rs:38 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ BACKTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⋮ 5 frames hidden ⋮ 6: usage::read_file::haee210cb22460af3 at /home/jlusby/git/yaahc/color-eyre/examples/usage.rs:35 7: usage::read_config::ha649ef4ec333524d at /home/jlusby/git/yaahc/color-eyre/examples/usage.rs:40 8: usage::main::hbe443b50eac38236 at /home/jlusby/git/yaahc/color-eyre/examples/usage.rs:11 ⋮ 10 frames hidden ⋮ Suggestion: try using a file that exists next time
Finally, running RUST_LIB_BACKTRACE=full cargo run --example usage
tells color-eyre
to use
the full format, which in addition to the above will attempt to include source lines where the
error originated from, assuming it can find them on the disk.
color-eyre on hooked [$!] is 📦 v0.5.0 via 🦀 v1.44.0 ❯ RUST_LIB_BACKTRACE=full cargo run --example usage Finished dev [unoptimized + debuginfo] target(s) in 0.05s Running `target/debug/examples/usage` Jul 05 19:16:06.335 INFO read_config:read_file{path="fake_file"}: Reading file Error: 0: Unable to read config 1: No such file or directory (os error 2) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SPANTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0: usage::read_file with path="fake_file" at examples/usage.rs:32 30 │ } 31 │ 32 > #[instrument] 33 │ fn read_file(path: &str) -> Result<(), Report> { 34 │ info!("Reading file"); 1: usage::read_config at examples/usage.rs:38 36 │ } 37 │ 38 > #[instrument] 39 │ fn read_config() -> Result<(), Report> { 40 │ read_file("fake_file") ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ BACKTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⋮ 5 frames hidden ⋮ 6: usage::read_file::haee210cb22460af3 at /home/jlusby/git/yaahc/color-eyre/examples/usage.rs:35 33 │ fn read_file(path: &str) -> Result<(), Report> { 34 │ info!("Reading file"); 35 > Ok(std::fs::read_to_string(path).map(drop)?) 36 │ } 37 │ 7: usage::read_config::ha649ef4ec333524d at /home/jlusby/git/yaahc/color-eyre/examples/usage.rs:40 38 │ #[instrument] 39 │ fn read_config() -> Result<(), Report> { 40 > read_file("fake_file") 41 │ .wrap_err("Unable to read config") 42 │ .suggestion("try using a file that exists next time") 8: usage::main::hbe443b50eac38236 at /home/jlusby/git/yaahc/color-eyre/examples/usage.rs:11 9 │ color_eyre::install()?; 10 │ 11 > Ok(read_config()?) 12 │ } 13 │ ⋮ 10 frames hidden ⋮ Suggestion: try using a file that exists next time
§Custom Section
s for error reports via Section
trait
The section
module provides helpers for adding extra sections to error
reports. Sections are disinct from error messages and are displayed
independently from the chain of errors. Take this example of adding sections
to contain stderr
and stdout
from a failed command, taken from
examples/custom_section.rs
:
use color_eyre::{eyre::eyre, SectionExt, Section, eyre::Report};
use std::process::Command;
use tracing::instrument;
trait Output {
fn output2(&mut self) -> Result<String, Report>;
}
impl Output for Command {
#[instrument]
fn output2(&mut self) -> Result<String, Report> {
let output = self.output()?;
let stdout = String::from_utf8_lossy(&output.stdout);
if !output.status.success() {
let stderr = String::from_utf8_lossy(&output.stderr);
Err(eyre!("cmd exited with non-zero status code"))
.with_section(move || stdout.trim().to_string().header("Stdout:"))
.with_section(move || stderr.trim().to_string().header("Stderr:"))
} else {
Ok(stdout.into())
}
}
}
Here we have an function that, if the command exits unsuccessfully, creates a
report indicating the failure and attaches two sections, one for stdout
and
one for stderr
.
Running cargo run --example custom_section
shows us how these sections are
included in the output:
color-eyre on hooked [$!] is 📦 v0.5.0 via 🦀 v1.44.0 took 2s ❯ cargo run --example custom_section Finished dev [unoptimized + debuginfo] target(s) in 0.04s Running `target/debug/examples/custom_section` Error: 0: Unable to read config 1: cmd exited with non-zero status code Stderr: cat: fake_file: No such file or directory ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SPANTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0: custom_section::output2 with self="cat" "fake_file" at examples/custom_section.rs:14 1: custom_section::read_file with path="fake_file" at examples/custom_section.rs:58 2: custom_section::read_config at examples/custom_section.rs:63 Suggestion: try using a file that exists next time
Only the Stderr:
section actually gets included. The cat
command fails,
so stdout ends up being empty and is skipped in the final report. This gives
us a short and concise error report indicating exactly what was attempted and
how it failed.
§Aggregating multiple errors into one report
It’s not uncommon for programs like batched task runners or parsers to want to return an error with multiple sources. The current version of the error trait does not support this use case very well, though there is work being done to improve this.
For now however one way to work around this is to compose errors outside the
error trait. color-eyre
supports such composition in its error reports via
the Section
trait.
For an example of how to aggregate errors check out examples/multiple_errors.rs
.
§Custom configuration for color-backtrace
for setting custom filters and more
The pretty printing for backtraces and span traces isn’t actually provided by
color-eyre
, but instead comes from its dependencies color-backtrace
and
color-spantrace
. color-backtrace
in particular has many more features
than are exported by color-eyre
, such as customized color schemes, panic
hooks, and custom frame filters. The custom frame filters are particularly
useful when combined with color-eyre
, so to enable their usage we provide
the install
fn for setting up a custom BacktracePrinter
with custom
filters installed.
For an example of how to setup custom filters, check out examples/custom_filter.rs
.
Re-exports§
pub use section::IndentedSection;
pub use section::Section;
pub use section::SectionExt;
pub use eyre;
pub use owo_colors;
Modules§
- Configuration options for customizing the behavior of the provided panic and error reporting hooks
- Helpers for adding custom sections to error reports
Structs§
- A custom handler type for
eyre::Report
which provides colorful error reports andtracing-error
support.
Enums§
- ErrorKind
issue-url
The kind of type erased error being reported
Functions§
- Install the default panic and error report hooks