Lib.rs

color-eyre

一种用于处理panic和eyre crate的错误报告处理器，旨在为所有类型的错误提供丰富多彩、一致且格式良好的错误报告。

简单来说

color_eyre 帮助你构建如下所示的错误报告

设置

将以下内容添加到你的toml文件中

[dependencies]
color-eyre = "0.6"

并安装panic和错误报告处理器

use color_eyre::eyre::Result;

fn main() -> Result<()> {
    color_eyre::install()?;

    // ...
    # Ok(())
}

禁用跟踪支持

如果你不打算使用 tracing_error 和 SpanTrace，你可以禁用跟踪集成以减少未使用的依赖项

[dependencies]
color-eyre = { version = "0.6", default-features = false }

默认禁用SpanTrace捕获

color-eyre默认会捕获span跟踪信息。这是因为与 Backtrace 捕获相比，SpanTrace 捕获的成本要低得多。然而，与回溯一样，span跟踪信息对于调试应用程序最有用，并且通常希望默认禁用span跟踪捕获以减少开发者的噪音。

要禁用span跟踪捕获，必须显式设置控制 SpanTrace 捕获的env变量之一为 "0"

if std::env::var("RUST_SPANTRACE").is_err() {
    std::env::set_var("RUST_SPANTRACE", "0");
}

提高调试构建的性能

在调试模式下，color-eyre 的表现明显不如 eyre。这是由于 eyre 使用 std::backtrace::Backtrace 而不是 backtrace::Backtrace 的原因。std版本的后端跟踪是预编译的，这意味着你处于调试模式与否并不重要，后端跟踪捕获的成本始终在数十毫秒内，它将始终在数十毫秒内捕获。然而，backtrace::Backtrace 的调试版本却不幸，捕获回溯所需的时间是其std版本的一个数量级。

通过使用配置文件覆盖，可以缓解这个问题。通过配置项目始终使用优化来构建 backtrace，您应该能够获得与使用 eyre 时相同的 color-eyre 性能。为此，请将以下内容添加到您的 Cargo.toml 文件中：

[profile.dev.package.backtrace]
opt-level = 3

特性

多种报告格式详细级别

color-eyre 提供了三种不同的报告格式，用于格式化捕获的 SpanTrace 和 Backtrace：最小化、简短和完整。以下是从 examples/usage.rs 生成的输出片段：

在不设置 RUST_LIB_BACKTRACE 的情况下运行 cargo run --example usage 将产生一个最小化报告，如下所示：

运行 RUST_LIB_BACKTRACE=1 cargo run --example usage 告诉 color-eyre 使用简短格式，该格式还会额外捕获 backtrace::Backtrace

最后，运行 RUST_LIB_BACKTRACE=full cargo run --example usage 告诉 color-eyre 使用完整格式，除了上述内容外，还会尝试包含错误起源的源代码行，假设它能在磁盘上找到它们。

通过 Section 特性实现错误报告的定制 Section

section 模块提供了向错误报告添加额外部分的辅助工具。部分与错误消息不同，并且独立于错误链显示。以下是一个添加部分以包含来自失败命令的 stderr 和 stdout 的示例，取自 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())
        }
    }
}

这里有一个函数，如果命令执行不成功，则创建一个指示失败并附加两个部分的报告，一个用于 stdout，另一个用于 stderr。

运行 cargo run --example custom_section 显示了这些部分是如何包含在输出中的

只有 Stderr: 部分实际上被包含。由于 cat 命令失败，所以 stdout 最终为空，并在最终报告中被跳过。这给我们提供了一个简短且简洁的错误报告，确切地说明了尝试了什么以及它如何失败。

将多个错误聚合到一个报告中

对于批处理任务运行程序或解析器之类的程序，返回具有多个来源的错误并不罕见。当前版本的错误特性并不很好地支持此用例，尽管正在进行改进。

然而，目前可以通过在错误特性之外组合错误来解决此问题。color-eyre 通过 Section 特性支持其错误报告中的此类组合。

要查看如何聚合错误的示例，请参阅examples/multiple_errors.rs。

为color-backtrace设置自定义过滤器和其他配置的自定义配置

后迹和跨度迹的格式化打印实际上不是由color-eyre提供的，而是来自其依赖项color-backtrace和color-spantrace。特别是，color-backtrace比color-eyre导出的功能更多，例如自定义颜色方案、panic钩子和自定义帧过滤器。当与color-eyre结合使用时，自定义帧过滤器特别有用，因此为了启用它们的用法，我们提供了install fn来设置带有自定义过滤器的自定义BacktracePrinter。

要查看如何设置自定义过滤器的示例，请参阅examples/custom_filter.rs。

许可协议