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//! # Features
56//!
57//! Additional functionality and integrations are enabled via feature flags. Some features require
58//! extra setup to function properly.
59//!
60//! | Feature | Default | Is Integration | Deprecated | Additional notes |
61//! | -------------- | ------- | -------------- | ---------- | ---------------------------------------------------------------------------------------- |
62//! | `backtrace` | ✅ | 🔌 | | |
63//! | `contexts` | ✅ | 🔌 | | |
64//! | `panic` | ✅ | 🔌 | | |
65//! | `transport` | ✅ | | | |
66//! | `anyhow` | | 🔌 | | |
67//! | `test` | | | | |
68//! | `debug-images` | ✅ | 🔌 | | |
69//! | `log` | | 🔌 | | Requires extra setup; See [`sentry-log`]'s documentation. |
70//! | `debug-logs` | | | ❗ | Requires extra setup; See [`sentry-log`]'s documentation. |
71//! | `slog` | | 🔌 | | Requires extra setup; See [`sentry-slog`]'s documentation. |
72//! | `reqwest` | ✅ | | | |
73//! | `native-tls` | ✅ | | | `reqwest` must be enabled. |
74//! | `rustls` | | | | `reqwest` must be enabled. `native-tls` must be disabled via `default-features = false`. |
75//! | `curl` | | | | |
76//! | `surf` | | | | |
77//! | `tower` | | 🔌 | | Requires extra setup; See [`sentry-tower`]'s documentation. |
78//! | `ureq` | | | | `ureq` transport support using `rustls` by default |
79//! | `ureq-native-tls` | | | | |
80//!
81//! [`sentry-log`]: https://crates.io/crates/sentry-log
82//! [`sentry-slog`]: https://crates.io/crates/sentry-slog
83//! [`sentry-tower`]: https://crates.io/crates/sentry-tower
84//!
85//! ## Default features
86//! - `backtrace`: Enables backtrace support.
87//! - `contexts`: Enables capturing device, OS, and Rust contexts.
88//! - `panic`: Enables support for capturing panics.
89//! - `transport`: Enables the default transport, which is currently `reqwest` with `native-tls`.
90//! - `debug-images`: Enables capturing metadata about the loaded shared libraries.
91//!
92//! ## Debugging/Testing
93//! - `anyhow`: Enables support for the `anyhow` crate.
94//! - `test`: Enables testing support.
95//!
96//! ## Logging
97//! - `log`: Enables support for the `log` crate.
98//! - `slog`: Enables support for the `slog` crate.
99//! - `debug-logs`: **Deprecated**. Uses the `log` crate for internal logging.
100//!
101//! ## Transports
102//! - `reqwest`: **Default**. Enables the `reqwest` transport.
103//! - `native-tls`: **Default**. Uses the `native-tls` crate. This only affects the `reqwest` transport.
104//! - `rustls`: Enables `rustls` support for `reqwest`. Please note that `native-tls` is a default
105//! feature, and `default-features = false` must be set to completely disable building `native-tls`
106//! dependencies.
107//! - `curl`: Enables the `curl` transport.
108//! - `surf`: Enables the `surf` transport.
109//! - `ureq`: Enables the `ureq` transport using `rustls`.
110//! - `ureq-native-tls`: Enables the `ureq` transport using `native-tls`.
111//!
112//! ## Integrations
113//! - `tower`: Enables support for the `tower` crate and those using it.
114
115#![doc(html_favicon_url = "https://sentry-brand.storage.googleapis.com/favicon.ico")]
116#![doc(html_logo_url = "https://sentry-brand.storage.googleapis.com/sentry-glyph-black.png")]
117#![warn(missing_docs)]
118// Only enables the `doc_cfg` feature when the `doc_cfg` configuration attribute
119// is defined. Used to expose docs for feature-locked integrations, and other
120// feature-gated documentation.
121#![cfg_attr(doc_cfg, feature(doc_cfg))]
122
123mod defaults;
124mod init;
125pub mod transports;
126
127// re-export from core
128#[doc(inline)]
129pub use sentry_core::*;
130
131// added public API
132pub use crate::defaults::apply_defaults;
133pub use crate::init::{init, ClientInitGuard};
134
135/// Available Sentry Integrations.
136///
137/// Integrations extend the functionality of the SDK for some common frameworks and
138/// libraries. There are two different kinds of integrations:
139/// - Event sources
140/// - Event processors
141///
142/// Integrations which are **event sources** such as
143/// [`sentry::integrations::anyhow`] typically provide one or more functions to
144/// create new events. These integrations will have an extension trait which exposes
145/// a new method on the [`Hub`].
146///
147/// Integrations which **process events** in some way usually implement the
148/// [`Integration`] trait and need to be installed when sentry is initialised.
149///
150/// # Installing Integrations
151///
152/// Processing integrations which implement [`Integration`] need to be installed
153/// when sentry is initialised. This can be accomplished by using
154/// [`ClientOptions::add_integration()`].
155///
156/// For example, if one were to disable the default integrations (see below) but
157/// still wanted to use [`sentry::integrations::debug_images`]:
158///
159/// ```
160/// # #[cfg(feature = "debug-images")] {
161/// use sentry::integrations::debug_images::DebugImagesIntegration;
162/// use sentry::ClientOptions;
163///
164/// let options = ClientOptions {
165/// default_integrations: false,
166/// ..Default::default()
167/// }
168/// .add_integration(DebugImagesIntegration::new());
169/// let _guard = sentry::init(options);
170/// # }
171/// ```
172///
173/// # Default Integrations
174///
175/// The [`ClientOptions::default_integrations`] option is a boolean field that
176/// when enabled will enable all of the default integrations via
177/// [`apply_defaults()`] **before** any integrations provided by
178/// [`ClientOptions::integrations`] are installed. Those interested in a list
179/// of default integrations and how they are applied are advised to visit
180/// [`apply_defaults()`]'s implementation.
181///
182/// [`sentry::integrations::anyhow`]: integrations::anyhow
183/// [`Integration`]: crate::Integration
184/// [`ClientOptions::add_integration()`]: crate::ClientOptions::add_integration
185/// [`sentry::integrations::debug_images`]: integrations::debug_images
186/// [`ClientOptions::default_integrations`]: crate::ClientOptions::default_integrations
187/// [`apply_defaults()`]: ../fn.apply_defaults.html
188pub mod integrations {
189 #[cfg(feature = "anyhow")]
190 #[cfg_attr(doc_cfg, doc(cfg(feature = "anyhow")))]
191 #[doc(inline)]
192 pub use sentry_anyhow as anyhow;
193 #[cfg(feature = "backtrace")]
194 #[cfg_attr(doc_cfg, doc(cfg(feature = "backtrace")))]
195 #[doc(inline)]
196 pub use sentry_backtrace as backtrace;
197 #[cfg(feature = "contexts")]
198 #[cfg_attr(doc_cfg, doc(cfg(feature = "contexts")))]
199 #[doc(inline)]
200 pub use sentry_contexts as contexts;
201 #[cfg(feature = "debug-images")]
202 #[cfg_attr(doc_cfg, doc(cfg(feature = "debug_images")))]
203 #[doc(inline)]
204 pub use sentry_debug_images as debug_images;
205 #[cfg(feature = "log")]
206 #[cfg_attr(doc_cfg, doc(cfg(feature = "log")))]
207 #[doc(inline)]
208 pub use sentry_log as log;
209 #[cfg(feature = "panic")]
210 #[cfg_attr(doc_cfg, doc(cfg(feature = "panic")))]
211 #[doc(inline)]
212 pub use sentry_panic as panic;
213 #[cfg(feature = "slog")]
214 #[cfg_attr(doc_cfg, doc(cfg(feature = "slog")))]
215 #[doc(inline)]
216 pub use sentry_slog as slog;
217 #[cfg(feature = "tower")]
218 #[cfg_attr(doc_cfg, doc(cfg(feature = "tower")))]
219 #[doc(inline)]
220 pub use sentry_tower as tower;
221 #[cfg(feature = "tracing")]
222 #[cfg_attr(doc_cfg, doc(cfg(feature = "tracing")))]
223 #[doc(inline)]
224 pub use sentry_tracing as tracing;
225}
226
227#[doc(inline)]
228pub use sentry_core::types::protocol::latest as protocol;