Crate color_eyre

A custom context for the eyre crate for colorful error reports, suggestions, and tracing-error support.

Setup

Add the following to your toml file:

[dependencies]
eyre = "0.4"
color-eyre = "0.3"

And then import the type alias from color-eyre for eyre::Report or eyre::Result.

use color_eyre::Report;

// or

fn example() -> color_eyre::Result<()> {
    // ...
}

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]
eyre = "0.4"
color-eyre = { version = "0.3", default-features = false }

Example

use color_eyre::{Help, Report};
use eyre::WrapErr;
use tracing::{info, instrument};

#[instrument]
fn main() -> Result<(), Report> {
    #[cfg(feature = "capture-spantrace")]
    install_tracing();

    Ok(read_config()?)
}

#[cfg(feature = "capture-spantrace")]
fn install_tracing() {
    use tracing_error::ErrorLayer;
    use tracing_subscriber::prelude::*;
    use tracing_subscriber::{fmt, EnvFilter};

    let fmt_layer = fmt::layer().with_target(false);
    let filter_layer = EnvFilter::try_from_default_env()
        .or_else(|_| EnvFilter::try_new("info"))
        .unwrap();

    tracing_subscriber::registry()
        .with(filter_layer)
        .with(fmt_layer)
        .with(ErrorLayer::default())
        .init();
}

#[instrument]
fn read_file(path: &str) -> Result<(), Report> {
    info!("Reading file");
    Ok(std::fs::read_to_string(path).map(drop)?)
}

#[instrument]
fn read_config() -> Result<(), Report> {
    read_file("fake_file")
        .wrap_err("Unable to read config")
        .suggestion("try using a file that exists next time")
}

Minimal Report Format

Short Report Format (with RUST_LIB_BACKTRACE=1)

Full Report Format (with RUST_LIB_BACKTRACE=full)

Explanation

This crate works by defining a Context type which implements eyre::EyreContext and a pair of type aliases for setting this context type as the parameter of eyre::Report.

use color_eyre::Context;

pub type Report = eyre::Report<Context>;
pub type Result<T, E = Report> = core::result::Result<T, E>;

Please refer to the Context type's docs for more details about its feature set.

Features

• captures a backtrace::Backtrace and prints using color-backtrace
• captures a tracing_error::SpanTrace and prints using color-spantrace
• Only capture SpanTrace by default for better performance.
• display source lines when RUST_LIB_BACKTRACE=full is set
• store help text via Help trait and display after final report
• custom color-backtrace configuration via color_eyre::install, such as adding custom filters

Structs

BacktracePrinter	Pretty-printer for backtraces and PanicInfo structs.
Context	A custom context type for eyre::Report which provides colorful error reports and tracing-error support.

Traits

Help	A helper trait for attaching help text to errors to be displayed after the chain of errors

Functions

install

Override the global BacktracePrinter used by color_eyre::Context when printing captured backtraces.

Type Definitions

Report	A type alias for eyre::Report<color_eyre::Context>
Result	A type alias for Result<T, color_eyre::Report>