sentry/lib.rs
1//! This crate provides support for logging events and errors / panics to the
2//! [Sentry] error logging service. It integrates with the standard panic
3//! system in Rust as well as a few popular error handling setups.
4//!
5//! [Sentry]: https://sentry.io/
6//!
7//! # Quickstart
8//!
9//! The most convenient way to use this library is via the [`sentry::init`] function,
10//! which starts a sentry client with a default set of integrations, and binds
11//! it to the current [`Hub`]. More Information on how to use Sentry in parallel,
12//! concurrent and async scenarios can be found on the [`Hub`] docs as well.
13//!
14//! The [`sentry::init`] function returns a guard that when dropped will flush Events that were not
15//! yet sent to the sentry service. It has a two second deadline for this so shutdown of
16//! applications might slightly delay as a result of this. Keep the guard around or sending events
17//! will not work.
18//!
19//! ```rust
20//! let _guard = sentry::init("https://key@sentry.io/42");
21//! sentry::capture_message("Hello World!", sentry::Level::Info);
22//! // when the guard goes out of scope here, the client will wait up to two
23//! // seconds to send remaining events to the service.
24//! ```
25//!
26//! More complex examples on how to use sentry can also be found in [examples]. Extended instructions
27//! may also be found on [Sentry itself].
28//!
29//! [`sentry::init`]: fn.init.html
30//! [`Hub`]: struct.Hub.html
31//! [examples]: https://github.com/getsentry/sentry-rust/tree/master/sentry/examples
32//! [Sentry itself]: https://docs.sentry.io/platforms/rust
33//!
34//! # Integrations
35//!
36//! What makes this crate useful are its various integrations. Some of them are enabled by
37//! default; See [Features]. Uncommon integrations or integrations for deprecated parts of
38//! the ecosystem require a feature flag. For available integrations and how to use them, see
39//! [integrations] and [apply_defaults].
40//!
41//! [Features]: #features
42//! [integrations]: integrations/index.html
43//! [apply_defaults]: fn.apply_defaults.html
44//!
45//! # Minimal API
46//!
47//! This crate comes fully-featured. If the goal is to instrument libraries for usage
48//! with sentry, or to extend sentry with a custom [`Integration`] or a [`Transport`],
49//! one should use the [`sentry-core`] crate instead.
50//!
51//! [`Integration`]: trait.Integration.html
52//! [`Transport`]: trait.Transport.html
53//! [`sentry-core`]: https://crates.io/crates/sentry-core
54//!
55//!
56//! # Features
57//!
58//! Additional functionality and integrations are enabled via feature flags. Some features require
59//! extra setup to function properly.
60//!
61//! | Feature | Default | Is Integration | Deprecated | Additional notes |
62//! | -------------- | ------- | -------------- | ---------- | ---------------------------------------------------------------------------------------- |
63//! | `backtrace` | ✅ | 🔌 | | |
64//! | `contexts` | ✅ | 🔌 | | |
65//! | `panic` | ✅ | 🔌 | | |
66//! | `transport` | ✅ | | | |
67//! | `anyhow` | | 🔌 | | |
68//! | `test` | | | | |
69//! | `debug-images` | ✅ | 🔌 | | |
70//! | `log` | | 🔌 | | Requires extra setup; See [`sentry-log`]'s documentation. |
71//! | `debug-logs` | | | ❗ | Requires extra setup; See [`sentry-log`]'s documentation. |
72//! | `slog` | | 🔌 | | Requires extra setup; See [`sentry-slog`]'s documentation. |
73//! | `reqwest` | ✅ | | | |
74//! | `native-tls` | ✅ | | | `reqwest` must be enabled. |
75//! | `rustls` | | | | `reqwest` must be enabled. `native-tls` must be disabled via `default-features = false`. |
76//! | `ureq` | | | | `ureq` transport support using `rustls` by default |
77//! | `ureq-native-tls` | | | | |
78//! | `curl` | | | | |
79//! | `actix` | | 🔌 | | Requires extra setup; See [`sentry-actix`]'s documentation. |
80//! | `tower` | | 🔌 | | Requires extra setup; See [`sentry-tower`]'s documentation. |
81//! | `tracing` | | 🔌 | | Requires extra setup; See [`sentry-tracing`]'s documentation. |
82//! | `opentelemetry` | | 🔌 | | Requires extra setup; See [`sentry-opentelemetry`]'s documentation. |
83//!
84//! [`sentry-log`]: https://crates.io/crates/sentry-log
85//! [`sentry-slog`]: https://crates.io/crates/sentry-slog
86//! [`sentry-actix`]: https://crates.io/crates/sentry-actix
87//! [`sentry-tower`]: https://crates.io/crates/sentry-tower
88//! [`sentry-tracing`]: https://crates.io/crates/sentry-tracing
89//! [`sentry-opentelemetry`]: https://crates.io/crates/sentry-opentelemetry
90//!
91//! ## Default features
92//! - `backtrace`: Enables backtrace support.
93//! - `contexts`: Enables capturing device, OS, and Rust contexts.
94//! - `panic`: Enables support for capturing panics.
95//! - `transport`: Enables the default transport, which is currently `reqwest` with `native-tls`.
96//! - `debug-images`: Enables capturing metadata about the loaded shared libraries.
97//!
98//! ## Debugging/Testing
99//! - `anyhow`: Enables support for the `anyhow` crate.
100//! - `test`: Enables testing support.
101//!
102//! ## Logging
103//! - `log`: Enables support for the `log` crate.
104//! - `slog`: Enables support for the `slog` crate.
105//! - `debug-logs`: **Deprecated**. Uses the `log` crate for internal logging.
106//!
107//! ## Transports
108//! - `reqwest`: **Default**. Enables the `reqwest` transport.
109//! - `native-tls`: **Default**. Uses the `native-tls` crate. This only affects the `reqwest` transport.
110//! - `rustls`: Enables `rustls` support for `reqwest`. Please note that `native-tls` is a default
111//! feature, and `default-features = false` must be set to completely disable building `native-tls`
112//! dependencies.
113//! - `curl`: Enables the `curl` transport.
114//! - `ureq`: Enables the `ureq` transport using `rustls`.
115//! - `ureq-native-tls`: Enables the `ureq` transport using `native-tls`.
116//!
117//! ## Integrations
118//! - `actix`: Enables support for the `actix-web` crate.
119//! - `tower`: Enables support for the `tower` crate and those using it.
120//! - `tracing`: Enables support for the `tracing` crate and those using it.
121//! - `opentelemetry`: Enables support for the `opentelemetry` and `opentelemetry-sdk` crates.
122
123#![doc(html_favicon_url = "https://sentry-brand.storage.googleapis.com/favicon.ico")]
124#![doc(html_logo_url = "https://sentry-brand.storage.googleapis.com/sentry-glyph-black.png")]
125#![warn(missing_docs)]
126// Only enables the `doc_cfg` feature when the `doc_cfg` configuration attribute
127// is defined. Used to expose docs for feature-locked integrations, and other
128// feature-gated documentation.
129#![cfg_attr(doc_cfg, feature(doc_cfg))]
130
131mod defaults;
132mod init;
133pub mod transports;
134
135// re-export from core
136#[doc(inline)]
137pub use sentry_core::*;
138
139// added public API
140pub use crate::defaults::apply_defaults;
141pub use crate::init::{init, ClientInitGuard};
142
143/// Available Sentry Integrations.
144///
145/// Integrations extend the functionality of the SDK for some common frameworks and
146/// libraries. There are two different kinds of integrations:
147/// - Event sources
148/// - Event processors
149///
150/// Integrations which are **event sources** such as
151/// [`sentry::integrations::anyhow`] typically provide one or more functions to
152/// create new events. These integrations will have an extension trait which exposes
153/// a new method on the [`Hub`].
154///
155/// Integrations which **process events** in some way usually implement the
156/// [`Integration`] trait and need to be installed when sentry is initialised.
157///
158/// # Installing Integrations
159///
160/// Processing integrations which implement [`Integration`] need to be installed
161/// when sentry is initialised. This can be accomplished by using
162/// [`ClientOptions::add_integration()`].
163///
164/// For example, if one were to disable the default integrations (see below) but
165/// still wanted to use [`sentry::integrations::debug_images`]:
166///
167/// ```
168/// # #[cfg(feature = "debug-images")] {
169/// use sentry::integrations::debug_images::DebugImagesIntegration;
170/// use sentry::ClientOptions;
171///
172/// let options = ClientOptions {
173/// default_integrations: false,
174/// ..Default::default()
175/// }
176/// .add_integration(DebugImagesIntegration::new());
177/// let _guard = sentry::init(options);
178/// # }
179/// ```
180///
181/// # Default Integrations
182///
183/// The [`ClientOptions::default_integrations`] option is a boolean field that
184/// when enabled will enable all of the default integrations via
185/// [`apply_defaults()`] **before** any integrations provided by
186/// [`ClientOptions::integrations`] are installed. Those interested in a list
187/// of default integrations and how they are applied are advised to visit
188/// [`apply_defaults()`]'s implementation.
189///
190/// [`sentry::integrations::anyhow`]: integrations::anyhow
191/// [`Integration`]: crate::Integration
192/// [`ClientOptions::add_integration()`]: crate::ClientOptions::add_integration
193/// [`sentry::integrations::debug_images`]: integrations::debug_images
194/// [`ClientOptions::default_integrations`]: crate::ClientOptions::default_integrations
195/// [`apply_defaults()`]: ../fn.apply_defaults.html
196pub mod integrations {
197 #[cfg(feature = "actix")]
198 #[cfg_attr(doc_cfg, doc(cfg(feature = "actix")))]
199 #[doc(inline)]
200 pub use sentry_actix as actix;
201 #[cfg(feature = "anyhow")]
202 #[cfg_attr(doc_cfg, doc(cfg(feature = "anyhow")))]
203 #[doc(inline)]
204 pub use sentry_anyhow as anyhow;
205 #[cfg(feature = "backtrace")]
206 #[cfg_attr(doc_cfg, doc(cfg(feature = "backtrace")))]
207 #[doc(inline)]
208 pub use sentry_backtrace as backtrace;
209 #[cfg(feature = "contexts")]
210 #[cfg_attr(doc_cfg, doc(cfg(feature = "contexts")))]
211 #[doc(inline)]
212 pub use sentry_contexts as contexts;
213 #[cfg(feature = "debug-images")]
214 #[cfg_attr(doc_cfg, doc(cfg(feature = "debug_images")))]
215 #[doc(inline)]
216 pub use sentry_debug_images as debug_images;
217 #[cfg(feature = "log")]
218 #[cfg_attr(doc_cfg, doc(cfg(feature = "log")))]
219 #[doc(inline)]
220 pub use sentry_log as log;
221 #[cfg(feature = "opentelemetry")]
222 #[cfg_attr(doc_cfg, doc(cfg(feature = "opentelemetry")))]
223 #[doc(inline)]
224 pub use sentry_opentelemetry as opentelemetry;
225 #[cfg(feature = "panic")]
226 #[cfg_attr(doc_cfg, doc(cfg(feature = "panic")))]
227 #[doc(inline)]
228 pub use sentry_panic as panic;
229 #[cfg(feature = "slog")]
230 #[cfg_attr(doc_cfg, doc(cfg(feature = "slog")))]
231 #[doc(inline)]
232 pub use sentry_slog as slog;
233 #[cfg(feature = "tower")]
234 #[cfg_attr(doc_cfg, doc(cfg(feature = "tower")))]
235 #[doc(inline)]
236 pub use sentry_tower as tower;
237 #[cfg(feature = "tracing")]
238 #[cfg_attr(doc_cfg, doc(cfg(feature = "tracing")))]
239 #[doc(inline)]
240 pub use sentry_tracing as tracing;
241}
242
243#[doc(inline)]
244pub use sentry_core::types::protocol::latest as protocol;