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