Error propagation tracing in Rust.

Related tags

propagate
Overview

Propagate

Error propagation tracing in Rust.

Why Propagate?

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

Multithreaded 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

Code size

Propagate stores the code location of every ? invocation in the static section of your application or library's binary.

Boilerplate

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 try blocks.

See the crate docs for more details.

Try It Out

Building

Propagate requires #[feature(try_trait_v2)] and #[feature(control_flow_enum)]. Build with Rust nightly:

cargo +nightly build

Examples

See examples/ for some examples showing the usage of the Propagate crate. Run them as such:

cargo +nightly run --example usage

Tests

To run tests:

cargo +nightly test

Documentation

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:

cargo doc --open
Issues
  • propagate API review

    propagate API review

    null

    opened by yaahc 0
  • Make `Result` a wrapper, not a re-implementation.

    Make `Result` a wrapper, not a re-implementation.

    Previously, propagate::Result was mostly a copy of std::result::Result, with a different Err type and modified FromResidual implementations.

    Because of this, users would have to to use propagate::Result::{Ok, Err} to construct results (unless they used try blocks).

    This changes propagate::Result<T, E, S> to be a minimal wrapper around a std::result::Result<T, TracedError<E, S>>. If users want to get to the wrapped result, they can call .unpack(), which will also return the traced stack if there is one.

    With this change, users no longer need to (nor have the ability to) shadow the standard library's Ok and Err. Now, there should be much less confusion about what a propagate::Result really is. It no longer pretends to be the same thing as a std::result::Result.

    opened by BGR360 1
Owner
Ben Reeves
haha Rust go brr
Ben Reeves
A library to compile USDT probes into a Rust library

sonde sonde is a library to compile USDT probes into a Rust library, and to generate a friendly Rust idiomatic API around it. Userland Statically Defi

Ivan Enderlin 29 Aug 31, 2021
Simple ray tracer written in Rust

Simple ray tracer written in Rust from scratch I've just finished my first semester at the Faculty of Applied Mathematics and Computer Science at the

Vladislav 191 Aug 20, 2021
Add nice user-facing diagnostics to your errors without being weird about it.

thisdiagnostic is a Rust library for adding rich diagnostic metadata to errors, for some really fancy and customizable error reporting!

Kat Marchán 12 Aug 24, 2021
CLI & Utilities for fractional.art

fractional-rs CLI & Utilities for fractional.art CLI Usage The CLI uses Flashbots' relay to submit the transactions. No bribe is required as you pay v

Georgios Konstantopoulos 14 Aug 30, 2021
hado-rshado — A little macro for writing haskell-like do expressions without too much ceremony

hado Monadic haskell-like expressions brought to rust via the hado! macro What? A little macro for writing haskell-like do expressions without too muc

Lucas David Traverso 43 Jul 3, 2021
Basically a KrabsETW rip-off written in Rust

FerrisETW ?? Basically a KrabsETW rip-off written in Rust, hence the name Ferris ?? All credits go to the team at Microsoft who develop KrabsEtw, with

n4r1B 10 Sep 16, 2021
Rusoto is an AWS SDK for Rust

Rusoto is an AWS SDK for Rust You may be looking for: An overview of Rusoto AWS services supported by Rusoto API documentation Getting help with Rusot

null 2.4k Sep 11, 2021
Rust experiments involving Haskell-esque do notation, state, failure and Nom parsers!

Introduction As a long time Haskell developer recently delving into Rust, something I've really missed is monads and do notation. One thing monadic do

Kerfuffle 22 Jul 2, 2021
A fancy diagnostics & error reporting crate

A fancy diagnostics & error reporting crate

Joshua Barretto 335 Sep 14, 2021
Rust mid-level IR Abstract Interpreter

MIRAI MIRAI is an abstract interpreter for the Rust compiler's mid-level intermediate representation (MIR). It is intended to become a widely used sta

Facebook Experimental 567 Sep 10, 2021
Lintje is an opinionated linter for Git.

Lintje Lintje is an opinionated linter for Git. It lints commit messages based on a preconfigured set of rules focussed on promoting communication bet

Tom de Bruijn 13 Aug 25, 2021
Make ELF formatted apps configurable

elfredo `elfredo` is a library that allows you to patch executables after they were compiled. It utilize an extra embedded section to store data/confi

Asaf Fisher 7 Sep 5, 2021
Utilities and tools based around Amazon S3 to provide convenience APIs in a CLI

s3-utils Utilities and tools based around Amazon S3 to provide convenience APIs in a CLI. This tool contains a small set of command line utilities for

Isaac Whitfield 35 Sep 13, 2021
A simplified but faster version of Routerify

Routerify lite Routerify-lite is a simplified but faster version of Routerify. It only provides below functions: path matching error handling Why not

jinhua luo 6 Aug 24, 2021
notify Node.js binding via napi-rs.

@napi-rs/notify notify Node.js binding via napi-rs. Install this package yarn add

LongYinan 7 Jul 20, 2021
Doku is a framework for building documentation with code-as-data methodology in mind.

Doku is a framework for building documentation with code-as-data methodology in mind. Say goodbye to stale, hand-written documentation - with D

ANIXE 37 Aug 24, 2021
A low-level I/O ownership and borrowing library

This library introduces OwnedFd, BorrowedFd, and supporting types and traits, and corresponding features for Windows, which implement safe owning and

Dan Gohman 43 Sep 12, 2021
Detects orphan configmaps and secrets in a Kubernetes cluster

KubExplorer Warning: Proof of concept. Feedback is much welcome. Discovers and prints out any Configmaps and Secrets not linked to any of the followin

Pavel Pscheidl 15 Aug 25, 2021
wasm actor system based on lunatic

Wactor WASM actor system based on lunatic. Actors run on isolated green threads. They cannot share memory, and communicate only through input and outp

Noah Corona 22 Jun 30, 2021