在软件开发过程中，错误处理是至关重要的一环。清晰、详尽的错误信息能够帮助开发者快速定位问题根源，提高调试效率。而 tracing 作为 Rust 生态中强大的日志和诊断信息框架，为我们提供了结构化、异步感知的诊断信息收集能力。tracing-error 则更进一步，将 tracing 的强大功能与 Rust 的错误处理机制相结合，为错误类型注入丰富的诊断信息，从而极大地提升错误处理的效率和便利性。

核心组件

tracing-error 的核心组件包括：

1. SpanTrace：捕获当前 tracing span 上下文

SpanTrace 结构体用于捕获创建时的 tracing span 上下文，并支持在之后的时间点进行展示。

use std::{fmt, error::Error};
use tracing_error::SpanTrace;

#[derive(Debug)]
pub struct MyError {
    context: SpanTrace,
    // ...
}

impl fmt::Display for MyError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // ... 格式化错误的其他部分 ...

        self.context.fmt(f)?;

        // ... 格式化其他错误上下文信息、原因链等 ...
        # Ok(())
    }
}

impl Error for MyError {}

impl MyError {
    pub fn new() -> Self {
        Self {
            context: SpanTrace::capture(),
            // ... 其他错误信息 ...
        }
    }
}

2. TracedError：为已有错误附加 SpanTrace

TracedError 结构体用于将 SpanTrace 附加到现有的错误类型。我们可以使用 InstrumentResult 和 InstrumentError trait，或者 From/Into trait，方便地将错误包装到 TracedError 中。

use tracing_error::prelude::*;

std::fs::read_to_string("myfile.txt").in_current_span()?;

获取 TracedError 中的 SpanTrace 信息可以通过三种方式：

• 使用 TracedError 的 Display/Debug 实现
• 使用 ExtractSpanTrace trait

use std::error::Error;
use tracing_error::ExtractSpanTrace as _;

fn print_extracted_spantraces(error: &(dyn Error + 'static)) {
    let mut error = Some(error);
    let mut ind = 0;

    eprintln!("Error:");

    while let Some(err) = error {
        if let Some(spantrace) = err.span_trace() {
            eprintln!("found a spantrace:\n{}", spantrace);
        } else {
            eprintln!("{:>4}: {}", ind, err);
        }

        error = err.source();
        ind += 1;
    }
}

3. ErrorSubscriber：订阅并捕获 SpanTrace

ErrorSubscriber 是一个 tracing 订阅器层，用于启用 SpanTrace 的捕获功能。

use tracing_error::ErrorSubscriber;
use tracing_subscriber::prelude::*;

fn main() {
    let subscriber = tracing_subscriber::Registry::default()
        // 可以在 ErrorSubscriber 前后添加其他订阅器层
        .with(ErrorSubscriber::default());

    // 设置全局默认订阅器
    tracing::subscriber::set_global_default(subscriber);
}

特性开关

tracing-error 提供以下特性开关：

• traced-error：启用 TracedError 类型和相关 trait，包括：
  • InstrumentResult 和 InstrumentError 扩展 trait，提供 in_current_span() 方法，用于将错误与 SpanTrace 绑定。
  • ExtractSpanTrace 扩展 trait，用于从 dyn Error trait 对象中提取 SpanTrace。

总结

tracing-error 为 Rust 的错误处理机制注入了强大的诊断信息，使得开发者能够更轻松地定位和解决问题。通过 SpanTrace、TracedError 和 ErrorSubscriber 等核心组件，我们可以捕获、附加和展示丰富的上下文信息，从而显著提升错误处理的效率和便利性。