Crate rootcause_backtrace 

Stack backtrace attachment collector for rootcause error reports.

This crate provides functionality to automatically capture and attach stack backtraces to error reports. This is useful for debugging to see the call stack that led to an error.

Quick Start

Using Hooks (Automatic for All Errors)

Register a backtrace collector as a hook to automatically capture backtraces for all errors:

use rootcause::hooks::Hooks;
use rootcause_backtrace::BacktraceCollector;

// Capture backtraces for all errors
Hooks::new()
    .report_creation_hook(BacktraceCollector::new_from_env())
    .install()
    .expect("failed to install hooks");

// Now all errors automatically get backtraces!
fn example() -> rootcause::Report {
    rootcause::report!("something went wrong")
}
println!("{}", example().context("additional context"));

This will print a backtrace similar to the following:

 ● additional context
 ├ src/main.rs:12
 ├ Backtrace
 │ │ main - /build/src/main.rs:12
 │ │ note: 39 frame(s) omitted. For a complete backtrace, set RUST_BACKTRACE=full.
 │ ╰─
 │
 ● something went wrong
 ├ src/main.rs:10
 ╰ Backtrace
   │ example - /build/src/main.rs:10
   │ main    - /build/src/main.rs:12
   │ note: 40 frame(s) omitted. For a complete backtrace, set RUST_BACKTRACE=full.
   ╰─

Manual Attachment (Per-Error)

Attach backtraces to specific errors using the extension trait:

use std::io;

use rootcause::{Report, report};
use rootcause_backtrace::BacktraceExt;

fn operation() -> Result<(), Report> {
    Err(report!("operation failed"))
}

// Attach backtrace to the error in the Result
let result = operation().attach_backtrace();

Environment Variables

• RUST_BACKTRACE=full - Disables filtering and shows full paths
• ROOTCAUSE_BACKTRACE - Comma-separated options:
  • leafs - Only capture backtraces for leaf errors (errors without children)
  • full_paths - Show full file paths in backtraces

Path privacy

By default, backtrace paths are shortened paths for improved readability, but this may still expose private file system structure when a path is not recognized as belonging to a known prefix (e.g., RUST_SRC).

If exposing private file system paths is a concern, then we recommend using the --remap-path-prefix option of rustc to remap source paths to generic placeholders.

A good default way to handle this is to set the following environment variables when building your application for release:

export RUSTFLAGS="--remap-path-prefix=$HOME=/home/user --remap-path-prefix=$PWD=/build"

Debugging symbols in release builds

To ensure that backtraces contain useful symbol and source location information in release builds, make sure to enable debug symbols in your Cargo.toml:

[profile.release]
strip = false
# You can also set this to "line-tables-only" for smaller binaries
debug = true

Filtering

Control which frames appear in backtraces:

use rootcause_backtrace::{BacktraceCollector, BacktraceFilter};

let collector = BacktraceCollector {
    filter: BacktraceFilter {
        skipped_initial_crates: &["rootcause", "rootcause-backtrace"],  // Skip frames from rootcause at start
        skipped_middle_crates: &["tokio"],     // Skip tokio frames in middle
        skipped_final_crates: &["std"],        // Skip std frames at end
        max_entry_count: 15,                   // Limit to 15 frames
        show_full_path: false,                 // Show shortened paths
    },
    capture_backtrace_for_reports_with_children: false,  // Only leaf errors
};

Structs

Backtrace

Stack backtrace information.

BacktraceCollector

Attachment collector for capturing stack backtraces.

BacktraceFilter

Configuration for filtering frames from certain crates in a backtrace.

BacktraceHandler

Handler for formatting Backtrace attachments.

Frame

A single stack frame in a backtrace.

FramePath

File path information for a stack frame.

FramePrefix

A common prefix for a frame path.

Enums

BacktraceEntry

A single entry in a stack backtrace.

Traits

BacktraceExt

Extension trait for attaching backtraces to reports.