Rust 错误处理在 GreptimeDB 的实践

设计目标

enum Error{
    ReadSocket(hyper::Error),
    DecodeMessage(serde_json::Error),
    Operation(GreptimeError),
    EncodeMessage(serde_json::Error),
    WriteSocket(hyper::Error),
}

当发生错误时，一个可能得错误信息是：DecodeMessage(serde_json: invalid character at 1)。但是，在某个具体组件的逻辑里，可能有超过 10 个地方进行消息解码，每次解码都可能抛出解码错误！我们如何确定在哪一步发现了无效内容呢？很明显，仅仅依靠 Root Cause 是不足以断定的。

因此，尽管 Root Cause 告诉了我们发生了什么错误，但是如果我们想了解这个错误发生的具体位置，以及应该如何处理这个错误，我们就需要错误信息暴露更多的细节上下文。

比如，以下是一个 GreptimeDB 错误日志的示例：

Failed to handle protocol
0: Failed to handle incoming content, query: blabla, at src/protocol/handler.rs:89:22
1: Failed to reading next message at queue 5 of 10, at src/protocol/loop.rs:254:14
2: Failed to decode `01010001001010001` to ProtocolHeader, at src/protocol/codec.rs:90:14
3: serde_json(invalid character at position 1)

一个好的错误报告不仅能说明错误的根因，更重要的是，处理错误的人能够从错误中获取到什么信息。上面这个错误报告的模式，我们称之为错误堆栈。错误堆栈报告了错误发生的关键轨迹。这非常直观，而且你大概在其他地方，例如 Backtrace 的使用中，看到过类似的形式。

上面的日志准确全面地报告了错误发生的情况，包括用户最终看到的错误到失败的根本原因。此外，还有每个错误堆栈中错误实例确切的行号和列号。可以看到，这个错误是“来自查询 'blabla'，第五个包的头部已损坏”。这很可能是无效的用户输入，并且我们可能不需要在服务器端处理它。

这个示例显示了一个错误需要包含的关键信息：

• 根本原因：告诉我们发生了什么；

• 完整的上下文堆栈：用于调试或确定错误发生的位置；

• 从用户的角度看发生了什么：决定了我们是否需要向用户公开展示错误。

很多时候，只要我们使用的库或函数使用了正确实现的错误类型，如同前文展示的 DecodeMessage 示例，根本原因是清晰的。但是，只有 Root Cause 很多时候不足以让用户处理接收到的错误信息。

这里是一个来自 Databricks 所作的 Delta Lake 的示例^[5]，佐证了我们关于错误堆栈必要性的观点。

（Delta Lake 示例图）

在接下来的部分中，我们将关注上下文堆栈和展示错误的方式，并介绍我们是如何实现这些功能的。

标准库 Backtrace

回到 DecodeMessage 的例子。现在我们知道了错误发生的 Root Cause 是 DecodeMessage(serde_json: invalid character at 1)，但是，我们不清楚这个错误发生在哪一步：是解码 Header 时发生的？还是解码 Body 时发生的？

一个自然的想法是获取错误发生时的 Backtrace。.unwrap() 是第一个能想到的选择：当错误发生时，它将打印调用的 Backtrace（当然，这是一个坏的实践）。.unwrap() 使用的标准库 Backtrace 提供了完整的调用堆栈以及行号。然后，你会逐层检查源代码，跳过许多无关的系统调用堆栈、运行时堆栈和标准库堆栈，最终将看到错误相关的应用层代码。

如今的 Rust 生态中，许多库也提供在错误构建时捕获 Backtrace 的能力。然而，即使标准库 Backtrace 可以解决功能问题，它在实际运行中也会大量消耗 CPU（#1261^[6]）和内存（#1273^[7]）资源，从而推高 Backtrace 的使用成本。

捕获 Backtrace 会大大减慢程序的运行速度，因为它需要遍历调用堆栈并翻译指针。同时，为了能够翻译堆栈指针，程序需要在二进制文件中包含大量的 debuginfo，导致编译产物显著体积增加。在 GreptimeDB 中，使用这一策略将导致最终二进制文件大小增加 700MB 以上（比没有调试信息时的 170MB 增加了 4 倍）。

而且，捕获的标准库 Backtrace 中包含许多噪音，因为系统无法区分代码是来自标准库、第三方异步运行时还是我们的代码库。

标准库 Backtrace 跟我们最终实现的错误堆栈方案之间还有一个区别。标准库 Backtrace 告诉我们如何回到错误发生的位置，但是这个位置是由标准库提供的，应用没有办法更好的展示错误传播的逻辑轨迹。而错误堆栈则展示了错误是如何传播的。

async fn handle_request(req: Request) -> Result<Output> {
    let msg = decode_msg(&req.msg).context(DecodeMessage)?; // propagate error with new stack and context
    verify_msg(&msg)?; // pass error to the caller directly
    process_msg(msg).await? // pass error to the caller directly
}

async fn decode_msg(msg: &RawMessage) -> Result<Message> {
    serde_json::from_slice(&msg).context(SerdeJson) // propagate error with new stack and context
}

   1: <alloc::boxed::Box<F,A> as core::ops::function::Fn<Args>>::call
             at /rustc/3f28fe133475ec5faf3413b556bf3cfb0d51336c/library/alloc/src/boxed.rs:2029:9
      std::panicking::rust_panic_with_hook
             at /rustc/3f28fe133475ec5faf3413b556bf3cfb0d51336c/library/std/src/panicking.rs:783:13
    ... many lines for std's internal traces

  22: tokio::runtime::task::raw::RawTask::poll
             at /home/wayne/.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.35.1/src/runtime/task/raw.rs:201:18
    ... many lines for tokio's internal traces

  32: std::thread::Builder::spawn_unchecked_::{{closure}}::{{closure}}
             at /rustc/3f28fe133475ec5faf3413b556bf3cfb0d51336c/library/std/src/thread/mod.rs:529:17
    ... many lines for std's internal traces

可以看到，这包括了大量你不关心的代码路径，例如标准库、tokio 运行时和系统调用等堆栈。

我们实现的错误堆栈方案，只在显式调用 .context 添加上下文时包含参数提供的上一层错误的堆栈。

对于其他复杂处理逻辑，如批处理，如果其中某一步产生了错误，这个错误可能不会立即传播，而是暂时保留。错误堆栈方案中的虚拟堆栈可以合并这些错误上下文，而标准库 Backtrace 在错误生成时立即捕获的。这导致后者的信息可能残缺不全。例如，标准库 Backtrace 将捕获 map-reduce 逻辑的中间步骤。但虚拟堆栈可以支持我们将捕获时间推迟到 reduce 之后。这样，你就有了更多关于整个任务的信息。

虚拟用户堆栈

0: Failed to handle incoming content, query: blabla, at src/protocol/handler.rs:89:22
1: Failed to reading next message at queue 5 of 10, at src/protocol/loop.rs:254:14
2: Failed to decode `01010001001010001` to ProtocolHeader, at src/protocol/codec.rs:90:14
3: serde_json(invalid character at position 1)

堆栈层由 3 部分组成：[STACK_NUM]: [MSG], at [FILE_LOCATION]

• Stack num 代表堆栈的编号。更小的数字意味着更外层的错误，这个数字从 0 开始计数；

• Message 对应与某一层相关的消息。这是调用错误的 std::fmt::Display^[8] 实现获得的。开发者可以在这里附加有用的上下文，如查询字符串或循环计数器；

• File location 是错误生成（以及传播，对于中间错误层而言）的位置。Rust 提供了 file!^[9]、line!^[10] 和 column!^[11] 宏来帮助获取这些信息。我们展示它的方式也是经过考虑的，大多数编辑器可以直接跳转到对应的位置。

在实践中，我们使用 snafu::Location^[12] 来收集代码位置。因此，每个位置都能精准指向错误构建的地方。通过这一链条，我们知道这个错误是如何生成并传播到最上层的。

#[derive(Snafu)]
pub enum Error {
    #[snafu(display("General catalog error: "))] // <-- the `Display` impl derive
    Catalog {
        location: Location, // <-- the `location`
        source: catalog::error::Error, // <-- inner cause
    }
}

pub trait StackError: std::error::Error {
    fn debug_fmt(&self, layer: usize, buf: &mut Vec<String>);
    fn next(&self) -> Option<&dyn StackError>;
    fn last(&self) -> &dyn StackError where Self: Sized { ... }
}

stack_trace_debug 过程宏主要做两件事：

• 生成实现 StackError^[15] 的代码；

• 基于 debug_fmt() 实现 std::fmt::Debug^[16]。

顺带一提，我们已经在 GreptimeDB 的所有错误中添加了 Location 和 display。这是实践错误堆栈方法论所需的必要劳动时间。

过程宏的实现要点

错误是一个单向链表，像洋葱一样从外层到内层。因此，我们可以在最外层捕获一个错误并逐层深入。

我们在这里需要处理的一个棘手问题是如何区分系统内部错误和外部错误，因为外部错误并不总是带有堆栈信息，实际上将成为错误堆栈的最内层。

内部错误都实现了同一个特性 ErrorExt ^[17]，可以用作标记。但是依赖实现 ErrorExt trait 进行判断，需要重复调用 downcast 测试，这会明显提高错误处理花费的时间。所以，我们选择简单地为通过命名来区分内外部错误。

#[derive(Snafu)]
#[stack_trace_debug]
pub enum Error {
    #[snafu(display("Failed to deserialize value"))]
    ValueDeserialize {
        #[snafu(source)]
        error: serde_json::error::Error, // <-- external source
        location: Location,
    },

    #[snafu(display("Table engine not found: {}", engine_name))]
    TableEngineNotFound {
        engine_name: String,
        location: Location,
        source: table::error::Error,    // <-- internal source
    }
}

StackError::debug_fmt^[19] 方法用于渲染错误堆栈。它会在生成的代码中递归调用。每层错误都会向可变缓冲区写入自己的调试消息。内容将包含从 #[snafu(display)]属性捕获的错误描述、像 TableEngineNotFound 这样的变体类型和来自枚举的位置。

鉴于我们已经以这种方式定义了我们的错误类型，采用堆栈错误不需要太多工作，只需向每种错误类型添加属性宏 #[stack_trace_debug] 即可。

向终端用户展示错误

到目前为止，我们已经完成了大部分工作。这是关于如何向用户展示错误的最后一部分。

不同于系统开发者，用户可能不关心行号甚至是堆栈。那么，什么信息对终端用户有帮助呢？