sentry_core/lib.rs
1//! This crate provides the core of the [Sentry] SDK, which can be used to log
2//! events and errors.
3//!
4//! `sentry-core` is meant for integration authors and third-party library authors
5//! that want to instrument their code for sentry.
6//!
7//! Regular users who wish to integrate sentry into their applications should
8//! instead use the [`sentry`] crate, which comes with a default transport and
9//! a large set of integrations for various third-party libraries.
10//!
11//! # Core Concepts
12//!
13//! This crate follows the [Unified API] guidelines and is centered around
14//! the concepts of [`Client`], [`Hub`] and [`Scope`], as well as the extension
15//! points via the [`Integration`], [`Transport`] and [`TransportFactory`] traits.
16//!
17//! # Parallelism, Concurrency and Async
18//!
19//! The main concurrency primitive is the [`Hub`]. In general, all concurrent
20//! code, no matter if multithreaded parallelism or futures concurrency, needs
21//! to run with its own copy of a [`Hub`]. Even though the [`Hub`] is internally
22//! synchronized, using it concurrently may lead to unexpected results up to
23//! panics.
24//!
25//! For threads or tasks that are running concurrently or outlive the current
26//! execution context, a new [`Hub`] needs to be created and bound for the computation.
27//!
28//! ```rust
29//! # let rt = tokio::runtime::Runtime::new().unwrap();
30//! # rt.block_on(async {
31//! use rayon::prelude::*;
32//! use sentry::{Hub, SentryFutureExt};
33//! use std::sync::Arc;
34//!
35//! // Parallel multithreaded code:
36//! let outer_hub = Hub::current();
37//! let results: Vec<_> = [1_u32, 2, 3]
38//! .into_par_iter()
39//! .map(|num| {
40//! let thread_hub = Arc::new(Hub::new_from_top(&outer_hub));
41//! Hub::run(thread_hub, || num * num)
42//! })
43//! .collect();
44//!
45//! assert_eq!(&results, &[1, 4, 9]);
46//!
47//! // Concurrent futures code:
48//! let futures = [1_u32, 2, 3]
49//! .into_iter()
50//! .map(|num| async move { num * num }.bind_hub(Hub::new_from_top(Hub::current())));
51//! let results = futures::future::join_all(futures).await;
52//!
53//! assert_eq!(&results, &[1, 4, 9]);
54//! # });
55//! ```
56//!
57//! For tasks that are not concurrent and do not outlive the current execution
58//! context, no *new* [`Hub`] needs to be created, but the current [`Hub`] has
59//! to be bound.
60//!
61//! ```rust
62//! # let rt = tokio::runtime::Runtime::new().unwrap();
63//! # rt.block_on(async {
64//! use sentry::{Hub, SentryFutureExt};
65//!
66//! // Spawned thread that is being joined:
67//! let hub = Hub::current();
68//! let result = std::thread::spawn(|| Hub::run(hub, || 1_u32)).join();
69//!
70//! assert_eq!(result.unwrap(), 1);
71//!
72//! // Spawned future that is being awaited:
73//! let result = tokio::spawn(async { 1_u32 }.bind_hub(Hub::current())).await;
74//!
75//! assert_eq!(result.unwrap(), 1);
76//! # });
77//! ```
78//!
79//! # Minimal API
80//!
81//! By default, this crate comes with a so-called "minimal" mode. This mode will
82//! provide all the APIs needed to instrument code with sentry, and to write
83//! sentry integrations, but it will blackhole a lot of operations.
84//!
85//! In minimal mode some types are restricted in functionality. For instance
86//! the [`Client`] is not available and the [`Hub`] does not retain all API
87//! functionality.
88//!
89//! # Features
90//!
91//! - `feature = "client"`: Activates the [`Client`] type and certain
92//! [`Hub`] functionality.
93//! - `feature = "test"`: Activates the [`test`] module, which can be used to
94//! write integration tests. It comes with a test transport which can capture
95//! all sent events for inspection.
96//! - `feature = "debug-logs"`: Uses the `log` crate for debug output, instead
97//! of printing to `stderr`. This feature is **deprecated** and will be
98//! replaced by a dedicated log callback in the future.
99//!
100//! [Sentry]: https://sentry.io/
101//! [`sentry`]: https://crates.io/crates/sentry
102//! [Unified API]: https://develop.sentry.dev/sdk/unified-api/
103//! [`test`]: test/index.html
104
105#![doc(html_favicon_url = "https://sentry-brand.storage.googleapis.com/favicon.ico")]
106#![doc(html_logo_url = "https://sentry-brand.storage.googleapis.com/sentry-glyph-black.png")]
107#![warn(missing_docs)]
108
109// macros; these need to be first to be used by other modules
110#[macro_use]
111mod macros;
112
113mod api;
114mod breadcrumbs;
115mod clientoptions;
116mod constants;
117mod error;
118mod futures;
119mod hub;
120mod integration;
121mod intodsn;
122mod performance;
123mod scope;
124mod transport;
125
126// public api or exports from this crate
127pub use crate::api::*;
128pub use crate::breadcrumbs::IntoBreadcrumbs;
129pub use crate::clientoptions::{BeforeCallback, ClientOptions, SessionMode};
130pub use crate::error::{capture_error, event_from_error, parse_type_from_debug};
131pub use crate::futures::{SentryFuture, SentryFutureExt};
132pub use crate::hub::Hub;
133pub use crate::integration::Integration;
134pub use crate::intodsn::IntoDsn;
135pub use crate::performance::*;
136pub use crate::scope::{Scope, ScopeGuard};
137pub use crate::transport::{Transport, TransportFactory};
138
139// client feature
140#[cfg(feature = "client")]
141mod client;
142#[cfg(feature = "client")]
143mod hub_impl;
144#[cfg(feature = "client")]
145mod session;
146
147#[cfg(feature = "client")]
148pub use crate::clientoptions::MaxRequestBodySize;
149
150#[cfg(feature = "client")]
151pub use crate::{client::Client, hub_impl::SwitchGuard as HubSwitchGuard};
152
153// test utilities
154#[cfg(feature = "test")]
155pub mod test;
156
157// public api from other crates
158#[doc(inline)]
159pub use sentry_types as types;
160pub use sentry_types::protocol::v7 as protocol;
161pub use sentry_types::protocol::v7::{Breadcrumb, Envelope, Level, User};