foundations_sentry/lib.rs
1#![allow(clippy::needless_doctest_main, reason = "for illustration")]
2//! [`foundations`] companion crate with Sentry integrations. Includes rate limiting
3//! of sentry events and tracking them with [`foundations`] metrics.
4//!
5//! This crate provides a sentry hook that increments the
6//! `sentry_events_total{level=<...>}` metric for each sentry event. If a
7//! previous `before_send` hook exists, it will be executed after rate limiting
8//! and before the metric is incremented. Only unfiltered events are counted.
9//!
10//! For rate-limiting, we group events by fingerprint. Each group has a separate
11//! rate limiter. The fingerprint of a sentry event is the first out of the following
12//! attributes that is present and not defaulted:
13//!
14//! 1. Explicit `event.fingerprint`
15//! 2. Event message
16//! 3. First exception value, or exception type if no value is set
17//! 4. Fallback: event level name (e.g., `error`)
18//!
19//! **note**: a clone of a client's [`sentry_core::ClientOptions`] will have the
20//! hook installed. This means "child" sentry clients will inherit the hook. A
21//! reinstall is only required if the [`sentry_core::ClientOptions::before_send`]
22//! field is overwritten.
23//!
24//! # Usage
25//!
26//! To install the hook:
27//!
28//! ```rust
29//! fn main() {
30//! let mut client_opts = sentry_core::ClientOptions::default();
31//! let sentry_settings = foundations_sentry::SentrySettings::default();
32//! foundations_sentry::install_hook_with_settings(&mut client_opts, &sentry_settings);
33//! // sentry::init(client_opts);
34//! }
35//! ```
36//!
37//! # Server-side symbolication
38//!
39//! Stacktraces are symbolicated locally by default. To capture instruction addresses
40//! without loading debug information, replace Sentry's automatic stacktrace integration
41//! with [`backtrace::UnresolvedStacktraceIntegration`] and enable
42//! [`panic::NoFlushPanicIntegration::with_unresolved_stacktraces`].
43//!
44//! Also install `sentry_debug_images::DebugImagesIntegration` (available through Sentry's
45//! `debug-images` feature) to attach loaded-image addresses and build IDs. The Sentry
46//! server must have access to the matching debug information, for example via debuginfod.
47//! These capture integrations alone do not provide the image metadata or debug files.
48//!
49//! Configure the capture integrations with:
50//!
51//! ```rust
52//! use std::sync::Arc;
53//! use foundations_sentry::backtrace::UnresolvedStacktraceIntegration;
54//! use foundations_sentry::panic::NoFlushPanicIntegration;
55//! use sentry_core::ClientOptions;
56//!
57//! let options = ClientOptions {
58//! attach_stacktrace: true,
59//! default_integrations: false,
60//! integrations: vec![
61//! Arc::new(UnresolvedStacktraceIntegration),
62//! Arc::new(NoFlushPanicIntegration::new().with_unresolved_stacktraces()),
63//! ],
64//! ..Default::default()
65//! };
66//! ```
67//!
68//! Other integrations and previously installed panic hooks can still resolve their own
69//! stacktraces. Existing stacktraces on events are preserved, not replaced or resolved.
70
71pub mod backtrace;
72pub mod metrics;
73pub mod panic;
74
75mod hook;
76mod settings;
77
78pub use self::hook::install_hook_with_settings;
79pub use self::settings::SentrySettings;