sentry_anyhow/
lib.rs

1//! Adds support for capturing Sentry errors from [`anyhow::Error`].
2//!
3//! This integration adds a new event *source*, which allows you to create events directly
4//! from an [`anyhow::Error`] struct.  As it is only an event source it only needs to be
5//! enabled using the `anyhow` cargo feature, it does not need to be enabled in the call to
6//! [`sentry::init`](https://docs.rs/sentry/*/sentry/fn.init.html).
7//!
8//! This integration does not need to be installed, instead it provides an extra function to
9//! capture [`anyhow::Error`], optionally exposing it as a method on the
10//! [`sentry::Hub`](https://docs.rs/sentry/*/sentry/struct.Hub.html) using the
11//! [`AnyhowHubExt`] trait.
12//!
13//! Like a plain [`std::error::Error`] being captured, [`anyhow::Error`] is captured with a
14//! chain of all error sources, if present.  See
15//! [`sentry::capture_error`](https://docs.rs/sentry/*/sentry/fn.capture_error.html) for
16//! details of this.
17//!
18//! # Example
19//!
20//! ```no_run
21//! use sentry_anyhow::capture_anyhow;
22//!
23//! fn function_that_might_fail() -> anyhow::Result<()> {
24//!     Err(anyhow::anyhow!("some kind of error"))
25//! }
26//!
27//! if let Err(err) = function_that_might_fail() {
28//!     capture_anyhow(&err);
29//! }
30//! ```
31//!
32//! # Features
33//!
34//! The `backtrace` feature will enable the corresponding feature in anyhow and allow you to
35//! capture backtraces with your events.  It is enabled by default.
36//!
37//! [`anyhow::Error`]: https://docs.rs/anyhow/*/anyhow/struct.Error.html
38
39#![doc(html_favicon_url = "https://sentry-brand.storage.googleapis.com/favicon.ico")]
40#![doc(html_logo_url = "https://sentry-brand.storage.googleapis.com/sentry-glyph-black.png")]
41#![warn(missing_docs)]
42#![deny(unsafe_code)]
43
44use sentry_core::protocol::Event;
45use sentry_core::types::Uuid;
46use sentry_core::Hub;
47
48/// Captures an [`anyhow::Error`].
49///
50/// This will capture an anyhow error as a sentry event if a
51/// [`sentry::Client`](../../struct.Client.html) is initialised, otherwise it will be a
52/// no-op.  The event is dispatched to the thread-local hub, with semantics as described in
53/// [`Hub::current`].
54///
55/// See [module level documentation](index.html) for more information.
56///
57/// [`anyhow::Error`]: https://docs.rs/anyhow/*/anyhow/struct.Error.html
58pub fn capture_anyhow(e: &anyhow::Error) -> Uuid {
59    Hub::with_active(|hub| hub.capture_anyhow(e))
60}
61
62/// Helper function to create an event from a `anyhow::Error`.
63pub fn event_from_error(err: &anyhow::Error) -> Event<'static> {
64    let dyn_err: &dyn std::error::Error = err.as_ref();
65
66    // It's not mutated for not(feature = "backtrace")
67    #[allow(unused_mut)]
68    let mut event = sentry_core::event_from_error(dyn_err);
69
70    #[cfg(feature = "backtrace")]
71    {
72        // exception records are sorted in reverse
73        if let Some(exc) = event.exception.iter_mut().last() {
74            let backtrace = err.backtrace();
75            if matches!(
76                backtrace.status(),
77                std::backtrace::BacktraceStatus::Captured
78            ) {
79                exc.stacktrace = sentry_backtrace::parse_stacktrace(&format!("{backtrace:#}"));
80            }
81        }
82    }
83
84    event
85}
86
87/// Hub extension methods for working with [`anyhow`].
88pub trait AnyhowHubExt {
89    /// Captures an [`anyhow::Error`] on a specific hub.
90    fn capture_anyhow(&self, e: &anyhow::Error) -> Uuid;
91}
92
93impl AnyhowHubExt for Hub {
94    fn capture_anyhow(&self, anyhow_error: &anyhow::Error) -> Uuid {
95        let event = event_from_error(anyhow_error);
96        self.capture_event(event)
97    }
98}
99
100#[cfg(all(feature = "backtrace", test))]
101mod tests {
102    use super::*;
103
104    #[test]
105    fn test_event_from_error_with_backtrace() {
106        std::env::set_var("RUST_BACKTRACE", "1");
107
108        let event = event_from_error(&anyhow::anyhow!("Oh jeez"));
109
110        let stacktrace = event.exception[0].stacktrace.as_ref().unwrap();
111        let found_test_fn = stacktrace
112            .frames
113            .iter()
114            .find(|frame| match &frame.function {
115                Some(f) => f.contains("test_event_from_error_with_backtrace"),
116                None => false,
117            });
118
119        assert!(found_test_fn.is_some());
120    }
121
122    #[test]
123    fn test_capture_anyhow_uses_event_from_error_helper() {
124        std::env::set_var("RUST_BACKTRACE", "1");
125
126        let err = &anyhow::anyhow!("Oh jeez");
127
128        let event = event_from_error(err);
129        let events = sentry::test::with_captured_events(|| {
130            capture_anyhow(err);
131        });
132
133        assert_eq!(event.exception, events[0].exception);
134    }
135}
sentry_anyhow/lib.rs

sentry_anyhow/
lib.rs
