Error propagation tracing in Rust.
Being able to trace the cause of an error is critical for many types of software written in Rust. For easy diagnosis, errors should provide some sort of trace denoting source code locations that contributed to the error.
Crates such as
anyhow provide easy access to backtraces when creating errors. The Propagate crate provides something similar but more powerful, which I call propagation tracing: every time the
? operator is applied to an error result, the code location of that
? invocation is appended to a running "stack trace" stored in the result.
Propagation tracing differs from runtime backtracing in a few important ways. You should evaluate which approach is appropriate for your application.
Advantages of Propagation Tracing
A backtrace provides a single point-in-time capture of a call stack on a single thread. In complex software, error results may pass between multiple threads on their way up to their final consumers.
Propagate provides a true view into the path that an error takes through your code, even if it passes between multiple threads.
Low performance overhead
Runtime backtracing requires unwinding stacks and mapping addresses to source code locations symbols at runtime.
With Propagate, the information for each code location is compiled statically into your application's binary, and the stack trace is built up in real time as the error propagates from function to function.
Disadvantages of Propagation Tracing
Propagate stores the code location of every
? invocation in the static section of your application or library's binary.
Propagate results require a bit more attention to work with compared to using the standard library
Result type. Much of this can be avoided if you elect to use
See the crate docs for more details.
Try It Out
cargo +nightly build
See examples/ for some examples showing the usage of the Propagate crate. Run them as such:
cargo +nightly run --example usage
To run tests:
cargo +nightly test
The rustdocs may lag behind as changes are made to the code. The examples and tests should be your first stop for understanding how the crate works.
To view the rustdocs, use
cargo doc --open