tracing-error

使用 tracing 诊断信息丰富错误处理的实用工具。

文档（发布版） | 文档（master） | 聊天

概览

tracing 是一个用于收集范围、结构和异步感知诊断的 Rust 程序的框架。此代码包提供了 tracing 仪器和 Rust 错误处理之间的集成。它允许通过 span 上下文丰富错误类型，在显示错误时格式化这些上下文，并在发生错误时自动生成 events。

代码包提供以下内容

• SpanTrace，当前 tracing span 上下文的捕获跟踪

• ErrorLayer，一个 订阅者层，允许捕获 SpanTrace

注意：此代码包目前为实验性。

编译器支持：需要 rustc 1.42+

使用

tracing-error 提供了 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 {
        // ... format other parts of the error ...

        self.context.fmt(f)?;

        // ... format other error context information, cause chain, etc ...
        # Ok(())
    }
}

impl Error for MyError {}

impl MyError {
    pub fn new() -> Self {
        Self {
            context: SpanTrace::capture(),
            // ... other error information ...
        }
    }
}

这个crate还提供了TracedError，用于将SpanTrace附加到现有错误。将错误封装在TracedError中最简单的方法是使用InstrumentResult和InstrumentError特质，或者使用From/Into特质。

use tracing_error::prelude::*;

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

一旦错误被封装为TracedError，可以通过以下三种方式之一提取SpanTrace：通过TracedError的Display/Debug实现，或者通过ExtractSpanTrace特质。

例如，以下是如何打印错误，并在错误是SpanTrace占位符时特别化打印。

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;
    }
}

而在这里，我们可以在错误链中简单地打印所有错误，无需特殊处理，就可以显示SpanTraces的内容。

use std::error::Error;

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

    eprintln!("Error:");

    while let Some(err) = error {
        eprintln!("{:>4}: {}", ind, err);
        error = err.source();
        ind += 1;
    }
}

希望使用启用了tracing-error的错误的应用程序应构建一个ErrorLayer并将其添加到它们的Subscriber中，以启用捕获SpanTrace。例如

use tracing_error::ErrorLayer;
use tracing_subscriber::prelude::*;

fn main() {
    let subscriber = tracing_subscriber::Registry::default()
        // any number of other subscriber layers may be added before or
        // after the `ErrorLayer`...
        .with(ErrorLayer::default());

    // set the subscriber as the default for the application
    tracing::subscriber::set_global_default(subscriber);
}

特性标志

• traced-error - 启用TracedError类型和相关特质
  • InstrumentResult和InstrumentError扩展特质，它们提供了一个in_current_span()方法，用于将错误与SpanTrace捆绑。
  • ExtractSpanTrace扩展特质，用于从dyn Error特质对象中提取SpanTrace。

支持的Rust版本

Tracing基于最新的稳定版本构建。最低支持版本是1.42。当前Tracing版本不保证在低于最低支持版本的Rust版本上构建。

Tracing遵循Tokio项目中的其他部分的编译器支持策略。当前稳定Rust编译器和其之前的三个最小版本将始终得到支持。例如，如果当前稳定编译器版本是1.45，则最低支持版本不会提高到1.42之前三个小版本。只要这样做符合此策略，提高最低支持编译器版本不被视为semver破坏性变更。

相关Crates

除了这个存储库外，还有一些由tokio项目维护的第三方crates。这些包括

• color-spantrace提供了一个用于以color-backtrace样式渲染SpanTrace的格式化程序。
• color-eyre 提供了一个针对 eyre::Report 的定制版本，用于捕获带有新错误的范围跟踪和回溯，并在错误报告中以美观的格式打印。

许可证

本项目遵循 MIT 许可证。

贡献

除非你明确说明，否则你提交给 Tracing 的任何有意贡献都将按照 MIT 许可证授权，不附加任何额外条款或条件。