Skip to content

Commit 0a361de

Browse files
SwatinemSwatinem
authored
fix: Better document default integrations (#224)
1 parent 4eac764 commit 0a361de

File tree

9 files changed

+84
-62
lines changed

9 files changed

+84
-62
lines changed

‎sentry-core/src/api.rs‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
use crate::protocol::{Event, Level};
22
use crate::types::Uuid;
3-
use crate::{Hub, IntoBreadcrumbs, Scope};
3+
use crate::{Hub, Integration, IntoBreadcrumbs, Scope};
44

55
/// Captures an event on the currently active client if any.
66
///
@@ -200,6 +200,41 @@ where
200200
}
201201
}
202202

203+
/// Looks up an integration on the current Hub.
204+
///
205+
/// Calls the given function with the requested integration instance when it
206+
/// is active on the currently active client. When multiple instances of the
207+
/// same integration are added, the function will be called with the first one.
208+
///
209+
/// # Examples
210+
///
211+
/// ```
212+
/// use sentry::{ClientOptions, Integration};
213+
///
214+
/// struct MyIntegration(usize);
215+
/// impl Integration for MyIntegration {}
216+
///
217+
/// let options = ClientOptions::default()
218+
/// .add_integration(MyIntegration(10))
219+
/// .add_integration(MyIntegration(20));
220+
/// # let _options = options.clone();
221+
///
222+
/// let _sentry = sentry::init(options);
223+
///
224+
/// # sentry::test::with_captured_events_options(|| {
225+
/// let value = sentry::with_integration(|integration: &MyIntegration, _| integration.0);
226+
/// assert_eq!(value, 10);
227+
/// # }, _options);
228+
/// ```
229+
pub fn with_integration<I, F, R>(f: F) -> R
230+
where
231+
I: Integration,
232+
F: FnOnce(&I, &Hub) -> R,
233+
R: Default,
234+
{
235+
Hub::with_active(|hub| hub.with_integration(|i| f(i, hub)))
236+
}
237+
203238
/// Returns the last event ID captured.
204239
///
205240
/// This uses the current thread local [`Hub`], and will return `None` if no

‎sentry-core/src/constants.rs‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,6 @@ lazy_static::lazy_static! {
1212
name: "cargo:sentry".into(),
1313
version: VERSION.into(),
1414
}],
15-
integrations: {
16-
#[allow(unused_mut)]
17-
let mut rv = vec![];
18-
rv
19-
},
15+
integrations: vec![],
2016
};
2117
}

‎sentry-core/src/hub.rs‎

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -227,24 +227,8 @@ impl Hub {
227227
/// Calls the given function with the requested integration instance when it
228228
/// is active on the currently active client.
229229
///
230-
/// # Example
231-
/// ```
232-
/// # use std::sync::Arc;
233-
/// use sentry_core::{Client, ClientOptions, Hub, Integration};
234-
///
235-
/// #[derive(Debug)]
236-
/// struct MyIntegration(usize);
237-
/// impl Integration for MyIntegration {}
238-
///
239-
/// let client = Arc::new(Client::from(
240-
/// ClientOptions::default().add_integration(MyIntegration(10)),
241-
/// ));
242-
/// let hub = Hub::with(|hub| Hub::new_from_top(hub));
243-
/// hub.bind_client(Some(client));
244-
///
245-
/// let value = hub.with_integration(|integration: &MyIntegration| integration.0);
246-
/// assert_eq!(value, 10);
247-
/// ```
230+
/// See the global [`capture_event`](fn.capture_event.html)
231+
/// for more documentation.
248232
pub fn with_integration<I, F, R>(&self, f: F) -> R
249233
where
250234
I: Integration,

‎sentry-log/src/integration.rs‎

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
use std::sync::Once;
22

33
use log::{Level, LevelFilter, Record};
4-
use sentry_core::{ClientOptions, Hub, Integration};
4+
use sentry_core::{ClientOptions, Integration};
55

66
use crate::logger::Logger;
77

@@ -117,14 +117,6 @@ impl LogIntegration {
117117
}
118118
}
119119

120-
pub fn with_integration<F, R>(f: F) -> R
121-
where
122-
F: FnOnce(&LogIntegration) -> R,
123-
R: Default,
124-
{
125-
Hub::with_active(|hub| hub.with_integration(f))
126-
}
127-
128120
#[test]
129121
fn test_filters() {
130122
let opt_warn = LogIntegration {

‎sentry-log/src/logger.rs‎

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,13 @@
1-
use sentry_core::{add_breadcrumb, Hub};
2-
31
use crate::converters::{breadcrumb_from_record, event_from_record};
4-
use crate::integration::with_integration;
2+
use crate::LogIntegration;
53

64
/// Provides a dispatching logger.
75
#[derive(Default)]
86
pub struct Logger;
97

108
impl log::Log for Logger {
119
fn enabled(&self, md: &log::Metadata<'_>) -> bool {
12-
with_integration(|integration| {
10+
sentry_core::with_integration(|integration: &LogIntegration, _| {
1311
if let Some(global_filter) = integration.global_filter {
1412
if md.level() > global_filter {
1513
return false;
@@ -24,14 +22,12 @@ impl log::Log for Logger {
2422
}
2523

2624
fn log(&self, record: &log::Record<'_>) {
27-
with_integration(|integration| {
25+
sentry_core::with_integration(|integration: &LogIntegration, hub| {
2826
if integration.create_issue_for_record(record) {
29-
Hub::with_active(|hub| {
30-
hub.capture_event(event_from_record(record, integration.attach_stacktraces))
31-
});
27+
hub.capture_event(event_from_record(record, integration.attach_stacktraces));
3228
}
3329
if integration.emit_breadcrumbs && record.level() <= integration.filter {
34-
add_breadcrumb(|| breadcrumb_from_record(record))
30+
sentry_core::add_breadcrumb(|| breadcrumb_from_record(record));
3531
}
3632
if let Some(ref log) = integration.dest_log {
3733
if log.enabled(record.metadata()) {
@@ -42,7 +38,7 @@ impl log::Log for Logger {
4238
}
4339

4440
fn flush(&self) {
45-
with_integration(|integration| {
41+
sentry_core::with_integration(|integration: &LogIntegration, _| {
4642
if let Some(ref log) = integration.dest_log {
4743
log.flush();
4844
}

‎sentry-panic/src/lib.rs‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,18 +24,16 @@ use std::sync::Once;
2424

2525
use sentry_backtrace::current_stacktrace;
2626
use sentry_core::protocol::{Event, Exception, Level};
27-
use sentry_core::{ClientOptions, Hub, Integration};
27+
use sentry_core::{ClientOptions, Integration};
2828

2929
/// A panic handler that sends to Sentry.
3030
///
3131
/// This panic handler reports panics to Sentry. It also attempts to prevent
3232
/// double faults in some cases where it's known to be unsafe to invoke the
3333
/// Sentry panic handler.
3434
pub fn panic_handler(info: &PanicInfo<'_>) {
35-
Hub::with_active(|hub| {
36-
hub.with_integration(|integration: &PanicIntegration| {
37-
hub.capture_event(integration.event_from_panic_info(info))
38-
})
35+
sentry_core::with_integration(|integration: &PanicIntegration, hub| {
36+
hub.capture_event(integration.event_from_panic_info(info))
3937
});
4038
}
4139

‎sentry-slog/src/drain.rs‎

Lines changed: 6 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
use crate::SlogIntegration;
2-
use sentry_core::Hub;
32
use slog::{Drain, OwnedKVList, Record};
43

54
/// A Drain which passes all Records to sentry.
@@ -14,27 +13,20 @@ impl<D: Drain> SentryDrain<D> {
1413
}
1514
}
1615

17-
// TODO: move this into `sentry-core`, as this is generally useful for more
18-
// integrations.
19-
fn with_integration<F, R>(f: F) -> R
20-
where
21-
F: Fn(&Hub, &SlogIntegration) -> R,
22-
R: Default,
23-
{
24-
Hub::with_active(|hub| hub.with_integration(|integration| f(hub, integration)))
25-
}
26-
2716
impl<D: Drain> slog::Drain for SentryDrain<D> {
2817
type Ok = D::Ok;
2918
type Err = D::Err;
3019

3120
fn log(&self, record: &Record, values: &OwnedKVList) -> Result<Self::Ok, Self::Err> {
32-
with_integration(|hub, integration| integration.log(hub, record, values));
21+
sentry_core::with_integration(|integration: &SlogIntegration, hub| {
22+
integration.log(hub, record, values)
23+
});
3324
self.drain.log(record, values)
3425
}
3526

3627
fn is_enabled(&self, level: slog::Level) -> bool {
37-
with_integration(|_, integration| integration.is_enabled(level))
38-
|| self.drain.is_enabled(level)
28+
sentry_core::with_integration(|integration: &SlogIntegration, _| {
29+
integration.is_enabled(level)
30+
}) || self.drain.is_enabled(level)
3931
}
4032
}

‎sentry/src/defaults.rs‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,22 @@ use crate::{ClientOptions, Integration};
1212
/// also sets the `dsn`, `release`, `environment`, and proxy settings based on
1313
/// environment variables.
1414
///
15+
/// When the `default_integrations` option is set to `true` (by default), the
16+
/// following integrations will be added *before* any manually defined
17+
/// integrations, depending on enabled feature flags:
18+
///
19+
/// 1. [`AttachStacktraceIntegration`] (`feature = "backtrace"`)
20+
/// 2. [`DebugImagesIntegration`] (`feature = "debug-images"`)
21+
/// 3. [`ErrorChainIntegration`] (`feature = "error-chain"`)
22+
/// 4. [`ContextIntegration`] (`feature = "contexts"`)
23+
/// 5. [`FailureIntegration`] (`feature = "failure"`)
24+
/// 6. [`PanicIntegration`] (`feature = "panic"`)
25+
/// 7. [`ProcessStacktraceIntegration`] (`feature = "backtrace"`)
26+
///
27+
/// Some integrations can be used multiple times, however, the
28+
/// [`PanicIntegration`] can not, and it will not pick up custom panic
29+
/// extractors when it is defined multiple times.
30+
///
1531
/// # Examples
1632
/// ```
1733
/// std::env::set_var("SENTRY_RELEASE", "release-from-env");
@@ -24,6 +40,14 @@ use crate::{ClientOptions, Integration};
2440
/// assert_eq!(options.release, Some("release-from-env".into()));
2541
/// assert!(options.transport.is_some());
2642
/// ```
43+
///
44+
/// [`AttachStacktraceIntegration`]: integrations/backtrace/struct.AttachStacktraceIntegration.html
45+
/// [`DebugImagesIntegration`]: integrations/debug_images/struct.DebugImagesIntegration.html
46+
/// [`ErrorChainIntegration`]: integrations/error_chain/struct.ErrorChainIntegration.html
47+
/// [`ContextIntegration`]: integrations/contexts/struct.ContextIntegration.html
48+
/// [`FailureIntegration`]: integrations/failure/struct.FailureIntegration.html
49+
/// [`PanicIntegration`]: integrations/panic/struct.PanicIntegration.html
50+
/// [`ProcessStacktraceIntegration`]: integrations/backtrace/struct.ProcessStacktraceIntegration.html
2751
pub fn apply_defaults(mut opts: ClientOptions) -> ClientOptions {
2852
if opts.transport.is_none() {
2953
opts.transport = Some(Arc::new(DefaultTransportFactory));

‎sentry/src/lib.rs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,11 @@ pub use crate::defaults::apply_defaults;
115115
pub use crate::init::{init, ClientInitGuard};
116116

117117
/// Available Sentry Integrations.
118+
///
119+
/// See the [`defaults`] function for more information on which integrations are
120+
/// used by default.
121+
///
122+
/// [`defaults`]: fn.defaults.html
118123
pub mod integrations {
119124
#[cfg(feature = "anyhow")]
120125
#[doc(inline)]

0 commit comments

Comments
 (0)