Crate extension_eyre

Crate extension_eyre 

Source
Expand description

ยงAbout this crate

Re-export of color-eyre crate that introduces Extensions.

See extensions module documentation to learn how to use Extension and ExtensionExt, .

Rest of the doc here is the same as in color-eyre.

ยงextension-eyre

An error report handler for panics and the eyre crate for colorful, consistent, and well formatted error reports for all kinds of errors.

ยงTLDR

extension_eyre helps you build error reports that look like this:

extension-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]
extension-eyre = "0.6"

And install the panic and error report handlers:

use extension_eyre::eyre::Result;

fn main() -> Result<()> {
    extension_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]
extension-eyre = { version = "0.6", default-features = false }

ยงDisabling SpanTrace capture by default

extension-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 extension-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 extension-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

extension-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:

extension-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 extension-eyre to use the short format, which additionally capture a backtrace::Backtrace:

extension-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/extension-eyre/examples/usage.rs:35
   7: usage::read_config::ha649ef4ec333524d
      at /home/jlusby/git/yaahc/extension-eyre/examples/usage.rs:40
   8: usage::main::hbe443b50eac38236
      at /home/jlusby/git/yaahc/extension-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 extension-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.

extension-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/extension-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/extension-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/extension-eyre/examples/usage.rs:11
         9 โ”‚     extension_eyre::install()?;
        10 โ”‚
        11 >     Ok(read_config()?)
        12 โ”‚ }
        13 โ”‚
                                โ‹ฎ 10 frames hidden โ‹ฎ                              

Suggestion: try using a file that exists next time

ยงCustom Sections 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 extension_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:

extension-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. extension-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 extension-eyre, but instead comes from its dependencies color-backtrace and color-spantrace. color-backtrace in particular has many more features than are exported by extension-eyre, such as customized color schemes, panic hooks, and custom frame filters. The custom frame filters are particularly useful when combined with extension-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 extensions::Extension;
pub use extensions::ExtensionExt;
pub use color_eyre::owo_colors;
pub use eyre;

Modulesยง

config
Configuration options for customizing the behavior of the provided panic and error reporting hooks
extensions
Helpers for adding custom data to error reports

Structsยง

Handler
A custom handler type for eyre::Report which provides colorful error reports and tracing-error support.
IndentedSection
An indented section with a header for an error report

Enumsยง

ErrorKindissue-url
The kind of type erased error being reported

Traitsยง

Section
A helper trait for attaching informational sections to error reports to be displayed after the chain of errors
SectionExt
Extension trait for constructing sections with commonly used formats

Functionsยง

install
Install the default panic and error report hooks