Skip to content

Commit b4b8763

Browse files
relaxolotlrelaxolotl
authored
docs: Provide more upfront info on features and integrations, nitpicky fixes (#345)
Some integrations do not work out of the box, but this isn't noted anywhere except in the integration's own documentation. Mentioning gotchas with features when they are introduced to the user should help out with this.
1 parent 970d9ba commit b4b8763

File tree

7 files changed

+122
-76
lines changed

7 files changed

+122
-76
lines changed

‎sentry-contexts/src/integration.rs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,19 @@ use crate::utils::{device_context, os_context, rust_context, server_name};
88

99
/// Adds Contexts to Sentry Events.
1010
///
11+
/// This integration is enabled by default in `sentry` and adds `device`, `os`
12+
/// and `rust` contexts to Events, and also sets a `server_name` if it is not
13+
/// already defined.
14+
///
1115
/// See the [Contexts Interface] documentation for more info.
1216
///
17+
/// # Examples
18+
///
19+
/// ```rust
20+
/// let integration = sentry_contexts::ContextIntegration::new().add_os(false);
21+
/// let _sentry = sentry::init(sentry::ClientOptions::new().add_integration(integration));
22+
/// ```
23+
///
1324
/// [Contexts Interface]: https://develop.sentry.dev/sdk/event-payloads/contexts/
1425
#[derive(Debug)]
1526
pub struct ContextIntegration {

‎sentry-contexts/src/lib.rs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
//! Adds Contexts to Sentry Events
1+
//! Adds Contexts to Sentry Events.
22
//!
33
//! This integration is enabled by default in `sentry` and adds `device`, `os`
4-
//! and `rust` contexts to Events, as well as sets a `server_name` if not
4+
//! and `rust` contexts to Events, and also sets a `server_name` if it is not
55
//! already defined.
66
//!
77
//! See the [Contexts Interface] documentation for more info.
88
//!
99
//! # Examples
1010
//!
11-
//! ```
11+
//! ```rust
1212
//! let integration = sentry_contexts::ContextIntegration::new().add_os(false);
1313
//! let _sentry = sentry::init(sentry::ClientOptions::new().add_integration(integration));
1414
//! ```

‎sentry-core/src/lib.rs‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
//! This crate provides the core of the [Sentry](https://sentry.io/) SDK, which
2-
//! can be used to log events and errors.
1+
//! This crate provides the core of the [Sentry] SDK, which can be used to log
2+
//! events and errors.
33
//!
4-
//! This crate is meant for integration authors and third party library authors
4+
//! `sentry-core` is meant for integration authors and third-party library authors
55
//! that want to instrument their code for sentry.
66
//!
77
//! Regular users who wish to integrate sentry into their applications should
8-
//! rather use the [`sentry`] crate, which comes with a default transport, and
8+
//! instead use the [`sentry`] crate, which comes with a default transport and
99
//! a large set of integrations for various third-party libraries.
1010
//!
1111
//! # Core Concepts
@@ -26,15 +26,16 @@
2626
//!
2727
//! # Features
2828
//!
29-
//! * `feature = "client"`: Activates the [`Client`] type and certain
29+
//! - `feature = "client"`: Activates the [`Client`] type and certain
3030
//! [`Hub`] functionality.
31-
//! * `feature = "test"`: Activates the [`test`] module, which can be used to
31+
//! - `feature = "test"`: Activates the [`test`] module, which can be used to
3232
//! write integration tests. It comes with a test transport which can capture
3333
//! all sent events for inspection.
34-
//! * `feature = "debug-logs"`: Uses the `log` crate for debug output, instead
34+
//! - `feature = "debug-logs"`: Uses the `log` crate for debug output, instead
3535
//! of printing to `stderr`. This feature is **deprecated** and will be
3636
//! replaced by a dedicated log callback in the future.
3737
//!
38+
//! [Sentry]: https://sentry.io/
3839
//! [`sentry`]: https://crates.io/crates/sentry
3940
//! [Unified API]: https://develop.sentry.dev/sdk/unified-api/
4041
//! [`Client`]: struct.Client.html

‎sentry-debug-images/src/lib.rs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
1-
//! The Sentry Debug Images Integration.
1+
//! The Sentry Debug Images integration.
22
//!
33
//! The [`DebugImagesIntegration`] adds metadata about the loaded shared
44
//! libraries to Sentry [`Event`]s.
55
//!
6-
//! This Integration only works on Unix-like OSs right now. Support for Windows
6+
//! This Integration only works on Unix-like OSes right now. Support for Windows
77
//! will be added in the future.
88
//!
99
//! # Configuration
1010
//!
1111
//! The integration by default attaches this information to all [`Event`]s, but
1212
//! a custom filter can be defined as well.
1313
//!
14-
//! ```
14+
//! ```rust
1515
//! use sentry_core::Level;
1616
//! let integration = sentry_debug_images::DebugImagesIntegration::new()
1717
//! .filter(|event| event.level >= Level::Warning);

‎sentry-log/src/lib.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
//!
33
//! The `log` crate is supported in two ways. First, logs can be captured as
44
//! breadcrumbs for later. Secondly, error logs can be captured as events to
5-
//! Sentry. By default anything above `Info` is recorded as breadcrumb and
5+
//! Sentry. By default anything above `Info` is recorded as a breadcrumb and
66
//! anything above `Error` is captured as error event.
77
//!
88
//! # Examples

‎sentry-panic/src/lib.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
//! The Sentry Panic handler Integration.
1+
//! The Sentry Panic handler integration.
22
//!
33
//! The `PanicIntegration`, which is enabled by default in `sentry`, installs a
44
//! panic handler that will automatically dispatch all errors to Sentry that

‎sentry/src/lib.rs‎

Lines changed: 95 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,49 @@
11
//! This crate provides support for logging events and errors / panics to the
2-
//! [Sentry](https://sentry.io/) error logging service. It integrates with the standard panic
2+
//! [Sentry] error logging service. It integrates with the standard panic
33
//! system in Rust as well as a few popular error handling setups.
44
//!
5+
//! [Sentry]: https://sentry.io/
6+
//!
57
//! # Quickstart
68
//!
7-
//! The most convenient way to use this library is the [`sentry::init`] function,
9+
//! The most convenient way to use this library is via the [`sentry::init`] function,
810
//! which starts a sentry client with a default set of integrations, and binds
911
//! it to the current [`Hub`].
1012
//!
1113
//! The [`sentry::init`] function returns a guard that when dropped will flush Events that were not
12-
//! yet sent to the sentry service. It has a two second deadline for this so shutdown of
13-
//! applications might slightly delay as a result of this. Keep the guard around or sending events
14+
//! yet sent to the sentry service. It has a two second deadline for this so shutdown of
15+
//! applications might slightly delay as a result of this. Keep the guard around or sending events
1416
//! will not work.
1517
//!
16-
//! ```
18+
//! ```rust
1719
//! let _guard = sentry::init("https://key@sentry.io/42");
1820
//! sentry::capture_message("Hello World!", sentry::Level::Info);
1921
//! // when the guard goes out of scope here, the client will wait up to two
2022
//! // seconds to send remaining events to the service.
2123
//! ```
2224
//!
25+
//! More complex examples on how to use sentry can also be found in [examples]. Extended instructions
26+
//! may also be found on [Sentry itself].
27+
//!
2328
//! [`sentry::init`]: fn.init.html
2429
//! [`Hub`]: struct.Hub.html
30+
//! [examples]: https://github.com/getsentry/sentry-rust/tree/master/sentry/examples
31+
//! [Sentry itself]: https://docs.sentry.io/platforms/rust
2532
//!
2633
//! # Integrations
2734
//!
28-
//! What makes this crate useful are the various integrations that exist. Some of them are enabled
29-
//! by default, some uncommon ones or for deprecated parts of the ecosystem a feature flag needs to
30-
//! be enabled. For the available integrations and how to use them see
31-
//! [integrations](integrations/index.html) and [apply_defaults](fn.apply_defaults.html).
35+
//! What makes this crate useful are its various integrations. Some of them are enabled by
36+
//! default; See [Features]. Uncommon integrations or integrations for deprecated parts of
37+
//! the ecosystem require a feature flag. For available integrations and how to use them, see
38+
//! [integrations] and [apply_defaults].
39+
//!
40+
//! [Features]: #features
41+
//! [integrations]: integrations/index.html
42+
//! [apply_defaults]: fn.apply_defaults.html
3243
//!
3344
//! # Minimal API
3445
//!
35-
//! This crate comes fully featured. If the goal is to instrument libraries for usage
46+
//! This crate comes fully-featured. If the goal is to instrument libraries for usage
3647
//! with sentry, or to extend sentry with a custom [`Integration`] or a [`Transport`],
3748
//! one should use the [`sentry-core`] crate instead.
3849
//!
@@ -42,34 +53,54 @@
4253
//!
4354
//! # Features
4455
//!
45-
//! Functionality of the crate can be turned on and off by feature flags. This is the current list
46-
//! of feature flags:
47-
//!
48-
//! Default features:
49-
//!
50-
//! * `backtrace`: Enables backtrace support.
51-
//! * `contexts`: Enables capturing device, os, and rust contexts.
52-
//! * `panic`: Enables support for capturing panics.
53-
//! * `transport`: Enables the default transport, which is currently `reqwest` with `native-tls`.
54-
//!
55-
//! Additional features:
56-
//!
57-
//! * `anyhow`: Enables support for the `anyhow` crate.
58-
//! * `debug-images`: Attaches a list of loaded libraries to events (currently only supported on unix).
59-
//! * `log`: Enables support for the `log` and `env_logger` crate.
60-
//! * `slog`: Enables support for the `slog` crate.
61-
//! * `tracing`: Enables support for the `tracing` crate.
62-
//! * `test`: Enables testing support.
63-
//! * `debug-logs`: Uses the `log` crate for internal logging.
64-
//! * `reqwest`: Enables the `reqwest` transport, which is currently the default.
65-
//! * `curl`: Enables the curl transport.
66-
//! * `surf`: Enables the surf transport.
67-
//! * `native-tls`: Uses the `native-tls` crate, which is currently the default.
68-
//! This only has an effect on the `reqwest` transport.
69-
//! * `rustls`: Enables the `rustls` support of the `reqwest` transport.
70-
//! Please note that `native-tls` is a default feature, and one needs to use
71-
//! `default-features = false` to completely disable building `native-tls` dependencies.
72-
56+
//! Additional functionality and integrations are enabled via feature flags. Some features require
57+
//! extra setup to function properly.
58+
//!
59+
//! | Feature | Default | Is Integration | Deprecated | Additional notes |
60+
//! | -------------- | ------- | -------------- | ---------- | ---------------------------------------------------------------------------------------- |
61+
//! | `backtrace` | ✅ | 🔌 | | |
62+
//! | `contexts` | ✅ | 🔌 | | |
63+
//! | `panic` | ✅ | 🔌 | | |
64+
//! | `transport` | ✅ | | | |
65+
//! | `anyhow` | | 🔌 | | |
66+
//! | `test` | | | | |
67+
//! | `debug-images` | | 🔌 | | |
68+
//! | `log` | | 🔌 | | Requires extra setup; See [`sentry-log`]'s documentation. |
69+
//! | `debug-logs` | | | ❗ | Requires extra setup; See [`sentry-log`]'s documentation. |
70+
//! | `slog` | | 🔌 | | Requires extra setup; See [`sentry-slog`]'s documentation. |
71+
//! | `reqwest` | ✅ | | | |
72+
//! | `native-tls` | ✅ | | | `reqwest` must be enabled. |
73+
//! | `rustls` | | | | `reqwest` must be enabled. `native-tls` must be disabled via `default-features = false`. |
74+
//! | `curl` | | | | |
75+
//! | `surf` | | | | |
76+
//!
77+
//! [`sentry-log`]: https://crates.io/crates/sentry-log
78+
//! [`sentry-slog`]: https://crates.io/crates/sentry-slog
79+
//!
80+
//! ## Default features
81+
//! - `backtrace`: Enables backtrace support.
82+
//! - `contexts`: Enables capturing device, OS, and Rust contexts.
83+
//! - `panic`: Enables support for capturing panics.
84+
//! - `transport`: Enables the default transport, which is currently `reqwest` with `native-tls`.
85+
//!
86+
//! ## Debugging/Testing
87+
//! - `anyhow`: Enables support for the `anyhow` crate.
88+
//! - `test`: Enables testing support.
89+
//! - `debug-images`: Attaches a list of loaded libraries to events (currently only supported on Unix).
90+
//!
91+
//! ## Logging
92+
//! - `log`: Enables support for the `log` crate.
93+
//! - `slog`: Enables support for the `slog` crate.
94+
//! - `debug-logs`: **Deprecated**. Uses the `log` crate for internal logging.
95+
//!
96+
//! ## Transports
97+
//! - `reqwest`: **Default**. Enables the `reqwest` transport.
98+
//! - `native-tls`: **Default**. Uses the `native-tls` crate. This only affects the `reqwest` transport.
99+
//! - `rustls`: Enables `rustls` support for `reqwest`. Please note that `native-tls` is a default
100+
//! feature, and `default-features = false` must be set to completely disable building `native-tls`
101+
//! dependencies.
102+
//! - `curl`: Enables the curl transport.
103+
//! - `surf`: Enables the surf transport.
73104
#![doc(html_favicon_url = "https://sentry-brand.storage.googleapis.com/favicon.ico")]
74105
#![doc(html_logo_url = "https://sentry-brand.storage.googleapis.com/sentry-glyph-black.png")]
75106
#![warn(missing_docs)]
@@ -89,28 +120,26 @@ pub use crate::init::{init, ClientInitGuard};
89120
/// Available Sentry Integrations.
90121
///
91122
/// Integrations extend the functionality of the SDK for some common frameworks and
92-
/// libraries. Integrations come two primary kinds: as event *sources* or as event
93-
/// *processors*.
123+
/// libraries. There are two different kinds of integrations:
124+
/// - Event sources
125+
/// - Event processors
94126
///
95-
/// Integrations which are *sources*, like e.g. the
96-
/// [`sentry::integrations::anyhow`](integrations::anyhow) integration, usually provide one
97-
/// or more functions to create new events. They will usually provide their own extension
98-
/// trait exposing a new method on the [`Hub`].
127+
/// Integrations which are **event sources** such as
128+
/// [`sentry::integrations::anyhow`] typically provide one or more functions to
129+
/// create new events. These integrations will have an extension trait which exposes
130+
/// a new method on the [`Hub`].
99131
///
100-
/// Integrations which *process* events in some way usually implement the
101-
/// [`Itegration`](crate::Integration) trait and need to be installed when sentry is
102-
/// initialised.
132+
/// Integrations which **process events** in some way usually implement the
133+
/// [`Integration`] trait and need to be installed when sentry is initialised.
103134
///
104135
/// # Installing Integrations
105136
///
106-
/// Processing integrations which implement [`Integration`](crate::Integration) need to be
107-
/// installed when sentry is initialised. This is done using the
108-
/// [`ClientOptions::add_integration`](crate::ClientOptions::add_integration) function, which you can
109-
/// use to add extra integrations.
137+
/// Processing integrations which implement [`Integration`] need to be installed
138+
/// when sentry is initialised. This can be accomplished by using
139+
/// [`ClientOptions::add_integration()`].
110140
///
111-
/// For example if you disabled the default integrations (see below) but still wanted the
112-
/// [`sentry::integrations::debug_images`](integrations::debug_images) integration enabled,
113-
/// you could do this as such:
141+
/// For example, if one were to disable the default integrations (see below) but
142+
/// still wanted to use [`sentry::integrations::debug_images`]:
114143
///
115144
/// ```
116145
/// # #[cfg(feature = "debug-images")] {
@@ -127,14 +156,19 @@ pub use crate::init::{init, ClientInitGuard};
127156
///
128157
/// # Default Integrations
129158
///
130-
/// The [`ClientOptions::default_integrations`](crate::ClientOptions::default_integrations)
131-
/// option is a boolean field that when enabled will enable a number of default integrations
132-
/// **before** any integrations provided by
133-
/// [`ClientOptions::integrations`](crate::ClientOptions::integrations) are installed. This
134-
/// is done using the [`apply_defaults`] function, which should be consulted for more
135-
/// details and the list of which integrations are enabled by default.
159+
/// The [`ClientOptions::default_integrations`] option is a boolean field that
160+
/// when enabled will enable all of the default integrations via
161+
/// [`apply_defaults()`] **before** any integrations provided by
162+
/// [`ClientOptions::integrations`] are installed. Those interested in a list
163+
/// of default integrations and how they are applied are advised to visit
164+
/// [`apply_defaults()`]'s implementation.
136165
///
137-
/// [`apply_defaults`]: ../fn.apply_defaults.html
166+
/// [`sentry::integrations::anyhow`]: integrations::anyhow
167+
/// [`Integration`]: crate::Integration
168+
/// [`ClientOptions::add_integration()`]: crate::ClientOptions::add_integration
169+
/// [`sentry::integrations::debug_images`]: integrations::debug_images
170+
/// [`ClientOptions::default_integrations`]: crate::ClientOptions::default_integrations
171+
/// [`apply_defaults()`]: ../fn.apply_defaults.html
138172
pub mod integrations {
139173
#[cfg(feature = "anyhow")]
140174
#[doc(inline)]

0 commit comments

Comments
 (0)