百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
R

rootcause

> 编程语言
开源

一个灵活、符合人体工程学要求且可检查的错误报告库,用于 Rust。

369 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

一个灵活、符合人体工程学要求且可检查的错误报告库,用于 Rust。

rootcause

A flexible, ergonomic, and inspectable error reporting library for Rust.

Overview

rootcause helps you build rich, structured error reports that capture not just what went wrong, but the full context and history.

Here's a simple example (from examples/basic.rs) showing how errors build up context as they propagate through your call stack:

…

When startup() fails, you get a chain showing the full story:

 ● Application startup failed
 ├ examples/basic.rs:76:10
 ├ Environment: production
 │
 ● Failed to load application configuration
 ├ examples/basic.rs:47:35
 ├ Config path: /nonexistent/config.toml
 ├ Expected format: TOML
 │
 ● No such file or directory (os error 2)
 ╰ examples/basic.rs:34:19

Each layer adds context and debugging information, building a trail from the high-level operation down to the root cause.

Core Concepts

At a high level, rootcause helps you build a tree of error reports. Each node in the tree represents a step in the error's history - you start with a root error, then add context and attachments as it propagates up through your code.

Most error reports are linear chains (just like anyhow), but the tree structure lets you collect multiple related errors when needed.

Project Goals

  • Ergonomic: The ? operator should work with most error types, even ones not designed for this library
  • Multi-failure tracking: When operations fail multiple times (retry attempts, batch processing, parallel execution), all failures should be captured and preserved in a single report
  • Inspectable: The objects in a Report should not be glorified strings. Inspecting and interacting with them should be easy
  • Optionally typed: Users should be able to (optionally) specify the type of the context in the root node
  • Beautiful: The default formatting should look pleasant—and if it doesn't match your style, the hook system lets you customize it
  • Cloneable: It should be possible to clone a Report when you need to
  • Self-documenting: Reports should automatically capture information (like backtraces and locations) that might be useful in debugging
  • Customizable: It should be possible to customize what data gets collected, or how reports are formatted
  • Lightweight: Report has a pointer-sized representation, keeping Result small and fast

Why rootcause?

Collecting Multiple Errors

When operations fail multiple times (retries, batch processing, parallel tasks), rootcause lets you gather all the failures into a single tree structure with readable output (from examples/retry_with_collection.rs):

…

The output from the above function will be a tree with data associated to each node:

 ● Unable to fetch document http://example.com
 ├ examples/retry_with_collection.rs:59:16
 │
 ├─ ● HTTP error: 500 Internal server error
 │  ├ examples/retry_with_collection.rs:42:9
 │  ╰ Attempt #1
 │
 ╰─ ● HTTP error: 404 Not found
    ├ examples/retry_with_collection.rs:42:9
    ╰ Attempt #2

For more tree examples, see retry_with_collection.rs and batch_processing.rs.

Inspecting Error Trees

Errors aren't just formatted strings—they're structured objects you can traverse and analyze programmatically. This enables analytics, custom error handling, and automated debugging (from examples/inspecting_errors.rs):

…

This lets you extract retry statistics, categorize errors, or build custom monitoring—not just display them. See inspecting_errors.rs for complete examples.

Supporting Advanced Use Cases

When you need to use the same error in multiple places—like sending to a logging backend and displaying to a user, potentially on different threads—you can make errors cloneable:

rust
use rootcause::prelude::*;

// Make the error cloneable so we can use it multiple times
let error = fetch_data().unwrap_err().into_cloneable();

// Send to background logging service
let log_error = error.clone();
tokio::spawn(async move {
    log_to_backend(log_error).await;
});

// Also display to user
display_error(error);

For the niche case where you're working with !Send errors from other libraries or need to attach thread-local data:

rust
// Include thread-local data in error reports
let report: Report = report!(MyError)
    .attach(Rc::new(expensive_data));

Most code uses the defaults, but these type parameters are available when you need them. See Report Type Parameters for details.

Type-Safe Error Handling

Libraries often need to preserve specific error types so callers can handle errors programmatically. Use Report to enable pattern matching without runtime type checks (simplified from examples/typed_reports.rs):

…

See typed_reports.rs for a complete example with retry logic.

Quick Start

Add this to your Cargo.toml:

toml
[dependencies]
rootcause = "0.13.0"

Use Report as your error type:

rust
use rootcause::prelude::*;

fn your_function() -> Result {
    // Your existing code with ? already works
    std::fs::read_to_string("/path/to/file")?;
    Ok(())
}

That's it! The ? operator automatically converts any error type to Report.

Ready to learn more? See examples/basic.rs for a hands-on tutorial covering .context(), .attach(), and composing error chains.

Ecosystem

rootcause is designed to be lightweight and extensible. The core library provides essential error handling functionality, while optional companion crates add specialized capabilities:

  • rootcause-backtrace - Automatic stack trace capture for debugging. Install hooks to attach backtraces to all errors, or use the extension trait to add them selectively.
  • rootcause-tracing - Tracing span capture for error reports. Automatically capture and display the active tracing spans when errors occur, providing operation context especially useful in async code.
  • rootcause-preformat - Extension traits for preformatting reports and attachments. Most useful when you need to go from a Local report to a SendSync one, or to freeze the rendered output before the original types/hooks go out of scope.

Next Steps

  • New to rootcause? See examples/basic.rs for a hands-on introduction
  • More examples: Browse the examples/ directory for common patterns
  • Full API documentation: docs.rs/rootcause

Features

  • std (default): Enable standard library support

Coming from other libraries?

Feature anyhow error-stack rootcause
Error structure Linear chain Opaque attachment model Explicit tree
Type safety No Required Optional
Adding context .context() .change_context() .context()
Structured attachments No Yes (.attach_printable()) Yes (.attach())
Tree navigation Linear (.chain()) Limited iterators Full tree access
Cloneable errors No No Yes (Report)
Thread-local errors No No Yes (Report)
Location tracking Single backtrace ? Multiple backtraces supported
Customization hooks No Formatting only Creation + formatting

See the retry example in "Why rootcause?" for how the tree structure enables collecting multiple related errors with ReportCollection.

Advanced Features

Once you're comfortable with the basics, rootcause offers powerful features for complex scenarios. See the examples directory for patterns including:

  • retry_with_collection.rs - Collecting multiple retry attempts
  • batch_processing.rs - Gathering errors from parallel operations
  • inspecting_errors.rs - Programmatic tree traversal and data extraction for analytics
  • following_error_sources.rs - Displaying full error source chains for debugging third-party library errors
  • custom_handler.rs - Customizing error formatting and data collection
  • formatting_hooks.rs - Advanced formatting customization

Architecture

The rootcause ecosystem consists of multiple crates:

Core:

  • rootcause - The main user-facing API with type-safe abstractions. Uses type markers to ensure the underlying data structures are used safely.
  • rootcause-internals - Low-level data structures and memory management. Handles the actual report storage, allocations, and pointer manipulation.

Extensions:

  • rootcause-backtrace - Optional backtrace capture support. Provides hooks for automatic stack trace collection.
  • rootcause-tracing - Optional tracing span capture. Provides hooks to attach active tracing spans to error reports.
  • rootcause-preformat - Provides extension traits for preformatting a report in order to go from Local objects to a SendSync ones.

The split between rootcause and rootcause-internals provides a clean API boundary: internals define how data is stored, while the main crate ensures that storage is accessed safely through Rust's type system. This makes it easy to understand the underlying representation while keeping the safe API ergonomic. Extensions integrate via the hook system without requiring changes to core.

Stability and Roadmap

Current status: Pre-1.0 (v0.13.0)

rootcause follows semantic versioning. As a 0.x library, breaking changes may occur in minor version bumps (0.x → 0.x+1). We're actively refining the API based on real-world usage and focused on reaching 1.0.

When to adopt:

  • ✅ Now: If you value the inspection capabilities and can tolerate occasional breaking changes during 0.x
  • ⏳ Wait for 1.0: If you need long-term API stability guarantees

We're committed to reaching 1.0, but we want to get the API right first.

Minimum Supported Rust Version (MSRV)

Our current Minimum Supported Rust Version is 1.89.0. When adding features, we will follow these guidelines:

  • We will always support the latest five minor Rust versions (or more). This gives you a 6 month window to upgrade your compiler.
  • Any change to the MSRV will be accompanied with a minor version bump.

Acknowledgements

This library was inspired by and draws ideas from several existing error handling libraries in the Rust ecosystem, including anyhow, thiserror, and error-stack.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rust

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言