From 16c784c0d43c51bf19d2d64676669ae63460fe82 Mon Sep 17 00:00:00 2001 From: Betty Da Date: Thu, 17 Jun 2021 23:27:16 -0400 Subject: [PATCH 01/11] docs: Provide more info about features upfront 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. --- sentry-log/README.md | 2 +- sentry/README.md | 101 +++++++++++++++++++++++++++---------------- 2 files changed, 64 insertions(+), 39 deletions(-) diff --git a/sentry-log/README.md b/sentry-log/README.md index 25e804bcf..dd462d75e 100644 --- a/sentry-log/README.md +++ b/sentry-log/README.md @@ -10,7 +10,7 @@ Adds support for automatic Breadcrumb and Event capturing from logs. The `log` crate is supported in two ways. First, logs can be captured as breadcrumbs for later. Secondly, error logs can be captured as events to -Sentry. By default anything above `Info` is recorded as breadcrumb and +Sentry. By default anything above `Info` is recorded as a breadcrumb and anything above `Error` is captured as error event. ## Examples diff --git a/sentry/README.md b/sentry/README.md index 0aa6f147f..8fa82c074 100644 --- a/sentry/README.md +++ b/sentry/README.md @@ -7,18 +7,20 @@ # Sentry Rust SDK: sentry This crate provides support for logging events and errors / panics to the -[Sentry](https://sentry.io/) error logging service. It integrates with the standard panic +[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 the [`sentry::init`] function, +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`]. 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 +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 @@ -33,14 +35,15 @@ sentry::capture_message("Hello World!", sentry::Level::Info); ## Integrations -What makes this crate useful are the various integrations that exist. Some of them are enabled -by default, some uncommon ones or for deprecated parts of the ecosystem a feature flag needs to -be enabled. For the available integrations and how to use them see -[integrations](https://docs.rs/sentry/0.21.0/sentry/integrations/index.html) and [apply_defaults](https://docs.rs/sentry/0.21.0/sentry/fn.apply_defaults.html). +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](https://docs.rs/sentry/0.21.0/sentry/integrations/index.html) and +[apply_defaults](https://docs.rs/sentry/0.21.0/sentry/fn.apply_defaults.html). ## Minimal API -This crate comes fully featured. If the goal is to instrument libraries for usage +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. @@ -50,35 +53,57 @@ one should use the [`sentry-core`] crate instead. ## Features -Functionality of the crate can be turned on and off by feature flags. This is the current list -of feature flags: - -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`. - -Additional features: - -* `anyhow`: Enables support for the `anyhow` crate. -* `debug-images`: Attaches a list of loaded libraries to events (currently only supported on unix). -* `error-chain`: Enables support for the `error-chain` crate. -* `failure`: Enables support for the `failure` crate. -* `log`: Enables support for the `log` crate. -* `env_logger`: Enables support for the `log` crate with additional `env_logger` support. -* `slog`: Enables support for the `slog` crate. -* `test`: Enables testing support. -* `debug-logs`: Uses the `log` crate for internal logging. -* `reqwest`: Enables the `reqwest` transport, which is currently the default. -* `curl`: Enables the curl transport. -* `surf`: Enables the surf transport. -* `native-tls`: Uses the `native-tls` crate, which is currently the default. - This only has an effect on the `reqwest` transport. -* `rustls`: Enables the `rustls` support of the `reqwest` transport. - Please note that `native-tls` is a default feature, and one needs to use - `default-features = false` to completely disable building `native-tls` dependencies. +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 additional setup; See [`sentry-log`]'s documentation. | +| `debug-logs` | | | ✂️ | | Requires additional setup; See [`sentry-log`]'s documentation. | +| `slog` | | 🔌 | | | Requires additional 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` | | | | | + +[`sentry-log`]: https://docs.rs/sentry-log +[`sentry-slog`]: https://docs.rs/sentry-slog + +Descriptions of all features, grouped by an arbitrary set of categories, sorted in a similarly +arbitrary order: + +### 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`. + +### Debugging/Testing +- `anyhow`: Enables support for the `anyhow` crate. +- `test`: Enables testing support. +- `debug-images`: Attaches a list of loaded libraries to events (currently only supported on Unix). + +### 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. ## Resources From d4fbc42fca664367096678fce8ecbf4c7c1cda02 Mon Sep 17 00:00:00 2001 From: Betty Da Date: Thu, 17 Jun 2021 23:33:46 -0400 Subject: [PATCH 02/11] nits --- README.md | 3 ++- sentry-contexts/README.md | 2 +- sentry-core/README.md | 15 ++++++++------- sentry-debug-images/README.md | 4 ++-- sentry-panic/README.md | 2 +- sentry/README.md | 3 +++ 6 files changed, 17 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index fc1c80550..79513c690 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,8 @@ This workspace contains various crates that provide support for logging events a - [sentry](./sentry) [![crates.io](https://img.shields.io/crates/v/sentry.svg)](https://crates.io/crates/sentry) [![docs.rs](https://docs.rs/sentry/badge.svg)](https://docs.rs/sentry) - The main `sentry` crate aimed at application users that want to log events to sentry. + The main `sentry` crate aimed at application users that want to log events to sentry. You'll want + to start here if you're trying to use sentry in your application. - [sentry-actix](./sentry-actix) [![crates.io](https://img.shields.io/crates/v/sentry-actix.svg)](https://crates.io/crates/sentry-actix) diff --git a/sentry-contexts/README.md b/sentry-contexts/README.md index c2d58763d..23e27469a 100644 --- a/sentry-contexts/README.md +++ b/sentry-contexts/README.md @@ -9,7 +9,7 @@ Adds Contexts to Sentry Events This integration is enabled by default in `sentry` and adds `device`, `os` -and `rust` contexts to Events, as well as sets a `server_name` if not +and `rust` contexts to Events, and also sets a `server_name` if it is not already defined. See the [Contexts Interface] documentation for more info. diff --git a/sentry-core/README.md b/sentry-core/README.md index bec12a526..c983b612e 100644 --- a/sentry-core/README.md +++ b/sentry-core/README.md @@ -6,14 +6,14 @@ # Sentry Rust SDK: sentry-core -This crate provides the core of the [Sentry](https://sentry.io/) SDK, which -can be used to log events and errors. +This crate provides the core of the [Sentry] SDK, which can be used to log +events and errors. -This crate is meant for integration authors and third party library authors +`sentry-core` is meant for integration authors and third-party library authors that want to instrument their code for sentry. Regular users who wish to integrate sentry into their applications should -rather use the [`sentry`] crate, which comes with a default transport, and +instead use the [`sentry`] crate, which comes with a default transport and a large set of integrations for various third-party libraries. ## Core Concepts @@ -34,15 +34,16 @@ functionality. ## Features -* `feature = "client"`: Activates the [`Client`] type and certain +- `feature = "client"`: Activates the [`Client`] type and certain [`Hub`] functionality. -* `feature = "test"`: Activates the [`test`] module, which can be used to +- `feature = "test"`: Activates the [`test`] module, which can be used to write integration tests. It comes with a test transport which can capture all sent events for inspection. -* `feature = "debug-logs"`: Uses the `log` crate for debug output, instead +- `feature = "debug-logs"`: Uses the `log` crate for debug output, instead of printing to `stderr`. This feature is **deprecated** and will be replaced by a dedicated log callback in the future. +[Sentry]: https://sentry.io/ [`sentry`]: https://crates.io/crates/sentry [Unified API]: https://develop.sentry.dev/sdk/unified-api/ [`Client`]: https://docs.rs/sentry-core/0.21.0/sentry_core/struct.Client.html diff --git a/sentry-debug-images/README.md b/sentry-debug-images/README.md index c005176b6..7429dc657 100644 --- a/sentry-debug-images/README.md +++ b/sentry-debug-images/README.md @@ -6,12 +6,12 @@ # Sentry Rust SDK: sentry-debug-images -The Sentry Debug Images Integration. +The Sentry Debug Images integration. The [`DebugImagesIntegration`] adds metadata about the loaded shared libraries to Sentry [`Event`]s. -This Integration only works on Unix-like OSs right now. Support for Windows +This Integration only works on Unix-like OSes right now. Support for Windows will be added in the future. ## Configuration diff --git a/sentry-panic/README.md b/sentry-panic/README.md index 836996878..2d28cf80a 100644 --- a/sentry-panic/README.md +++ b/sentry-panic/README.md @@ -6,7 +6,7 @@ # Sentry Rust SDK: sentry-panic -The Sentry Panic handler Integration. +The Sentry Panic handler integration. The `PanicIntegration`, which is enabled by default in `sentry`, installs a panic handler that will automatically dispatch all errors to Sentry that diff --git a/sentry/README.md b/sentry/README.md index 8fa82c074..a2b42e618 100644 --- a/sentry/README.md +++ b/sentry/README.md @@ -30,8 +30,11 @@ sentry::capture_message("Hello World!", sentry::Level::Info); // seconds to send remaining events to the service. ``` +More complex examples on how to use sentry can also be found in [examples]. + [`sentry::init`]: https://docs.rs/sentry/0.21.0/sentry/fn.init.html [`Hub`]: https://docs.rs/sentry/0.21.0/sentry/struct.Hub.html +[examples]: https://github.com/getsentry/sentry-rust/tree/master/sentry/examples ## Integrations From 8237a07995b25b066b7ff5bb23bddd8f1c917876 Mon Sep 17 00:00:00 2001 From: Betty Da Date: Sat, 19 Jun 2021 00:13:43 -0400 Subject: [PATCH 03/11] link to sentry docs --- sentry/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/sentry/README.md b/sentry/README.md index a2b42e618..64cab854c 100644 --- a/sentry/README.md +++ b/sentry/README.md @@ -30,11 +30,13 @@ sentry::capture_message("Hello World!", sentry::Level::Info); // seconds to send remaining events to the service. ``` -More complex examples on how to use sentry can also be found in [examples]. +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`]: https://docs.rs/sentry/0.21.0/sentry/fn.init.html [`Hub`]: https://docs.rs/sentry/0.21.0/sentry/struct.Hub.html [examples]: https://github.com/getsentry/sentry-rust/tree/master/sentry/examples +[Sentry itself]: https://docs.sentry.io/platforms/rust ## Integrations From ead1bfada20a4d61cf0f8a0a5e74e642b667ad88 Mon Sep 17 00:00:00 2001 From: Betty Da Date: Mon, 21 Jun 2021 16:45:39 -0400 Subject: [PATCH 04/11] update the rustdocs themselves instead of the READMEs --- sentry-contexts/src/integration.rs | 11 ++ sentry-contexts/src/lib.rs | 6 +- sentry-core/src/lib.rs | 15 +-- sentry-debug-images/src/lib.rs | 6 +- sentry-log/src/lib.rs | 2 +- sentry-panic/src/lib.rs | 2 +- sentry/src/lib.rs | 155 ++++++++++++++++++----------- sentry/src/transports/reqwest.rs | 1 + 8 files changed, 125 insertions(+), 73 deletions(-) diff --git a/sentry-contexts/src/integration.rs b/sentry-contexts/src/integration.rs index e86eb2502..6f3d842d1 100644 --- a/sentry-contexts/src/integration.rs +++ b/sentry-contexts/src/integration.rs @@ -8,8 +8,19 @@ use crate::utils::{device_context, os_context, rust_context, server_name}; /// Adds Contexts to Sentry Events. /// +/// This integration is enabled by default in `sentry` and adds `device`, `os` +/// and `rust` contexts to Events, and also sets a `server_name` if it is not +/// already defined. +/// /// See the [Contexts Interface] documentation for more info. /// +/// # Examples +/// +/// ```rust +/// let integration = sentry_contexts::ContextIntegration::new().add_os(false); +/// let _sentry = sentry::init(sentry::ClientOptions::new().add_integration(integration)); +/// ``` +/// /// [Contexts Interface]: https://develop.sentry.dev/sdk/event-payloads/contexts/ #[derive(Debug)] pub struct ContextIntegration { diff --git a/sentry-contexts/src/lib.rs b/sentry-contexts/src/lib.rs index cbdcd17e4..f48b0bfdf 100644 --- a/sentry-contexts/src/lib.rs +++ b/sentry-contexts/src/lib.rs @@ -1,14 +1,14 @@ -//! Adds Contexts to Sentry Events +//! Adds Contexts to Sentry Events. //! //! This integration is enabled by default in `sentry` and adds `device`, `os` -//! and `rust` contexts to Events, as well as sets a `server_name` if not +//! and `rust` contexts to Events, and also sets a `server_name` if it is not //! already defined. //! //! See the [Contexts Interface] documentation for more info. //! //! # Examples //! -//! ``` +//! ```rust //! let integration = sentry_contexts::ContextIntegration::new().add_os(false); //! let _sentry = sentry::init(sentry::ClientOptions::new().add_integration(integration)); //! ``` diff --git a/sentry-core/src/lib.rs b/sentry-core/src/lib.rs index d098f934f..e16a9cb29 100644 --- a/sentry-core/src/lib.rs +++ b/sentry-core/src/lib.rs @@ -1,11 +1,11 @@ -//! This crate provides the core of the [Sentry](https://sentry.io/) SDK, which -//! can be used to log events and errors. +//! This crate provides the core of the [Sentry] SDK, which can be used to log +//! events and errors. //! -//! This crate is meant for integration authors and third party library authors +//! `sentry-core` is meant for integration authors and third-party library authors //! that want to instrument their code for sentry. //! //! Regular users who wish to integrate sentry into their applications should -//! rather use the [`sentry`] crate, which comes with a default transport, and +//! instead use the [`sentry`] crate, which comes with a default transport and //! a large set of integrations for various third-party libraries. //! //! # Core Concepts @@ -26,15 +26,16 @@ //! //! # Features //! -//! * `feature = "client"`: Activates the [`Client`] type and certain +//! - `feature = "client"`: Activates the [`Client`] type and certain //! [`Hub`] functionality. -//! * `feature = "test"`: Activates the [`test`] module, which can be used to +//! - `feature = "test"`: Activates the [`test`] module, which can be used to //! write integration tests. It comes with a test transport which can capture //! all sent events for inspection. -//! * `feature = "debug-logs"`: Uses the `log` crate for debug output, instead +//! - `feature = "debug-logs"`: Uses the `log` crate for debug output, instead //! of printing to `stderr`. This feature is **deprecated** and will be //! replaced by a dedicated log callback in the future. //! +//! [Sentry]: https://sentry.io/ //! [`sentry`]: https://crates.io/crates/sentry //! [Unified API]: https://develop.sentry.dev/sdk/unified-api/ //! [`Client`]: struct.Client.html diff --git a/sentry-debug-images/src/lib.rs b/sentry-debug-images/src/lib.rs index 715361578..e3b5124ba 100644 --- a/sentry-debug-images/src/lib.rs +++ b/sentry-debug-images/src/lib.rs @@ -1,9 +1,9 @@ -//! The Sentry Debug Images Integration. +//! The Sentry Debug Images integration. //! //! The [`DebugImagesIntegration`] adds metadata about the loaded shared //! libraries to Sentry [`Event`]s. //! -//! This Integration only works on Unix-like OSs right now. Support for Windows +//! This Integration only works on Unix-like OSes right now. Support for Windows //! will be added in the future. //! //! # Configuration @@ -11,7 +11,7 @@ //! The integration by default attaches this information to all [`Event`]s, but //! a custom filter can be defined as well. //! -//! ``` +//! ```rust //! use sentry_core::Level; //! let integration = sentry_debug_images::DebugImagesIntegration::new() //! .filter(|event| event.level >= Level::Warning); diff --git a/sentry-log/src/lib.rs b/sentry-log/src/lib.rs index 68dc3000b..bbf667767 100644 --- a/sentry-log/src/lib.rs +++ b/sentry-log/src/lib.rs @@ -2,7 +2,7 @@ //! //! The `log` crate is supported in two ways. First, logs can be captured as //! breadcrumbs for later. Secondly, error logs can be captured as events to -//! Sentry. By default anything above `Info` is recorded as breadcrumb and +//! Sentry. By default anything above `Info` is recorded as a breadcrumb and //! anything above `Error` is captured as error event. //! //! # Examples diff --git a/sentry-panic/src/lib.rs b/sentry-panic/src/lib.rs index 1dfbb4fad..55c9bea97 100644 --- a/sentry-panic/src/lib.rs +++ b/sentry-panic/src/lib.rs @@ -1,4 +1,4 @@ -//! The Sentry Panic handler Integration. +//! The Sentry Panic handler integration. //! //! The `PanicIntegration`, which is enabled by default in `sentry`, installs a //! panic handler that will automatically dispatch all errors to Sentry that diff --git a/sentry/src/lib.rs b/sentry/src/lib.rs index f93597d22..34785fcbf 100644 --- a/sentry/src/lib.rs +++ b/sentry/src/lib.rs @@ -1,38 +1,49 @@ //! This crate provides support for logging events and errors / panics to the -//! [Sentry](https://sentry.io/) error logging service. It integrates with the standard panic +//! [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 the [`sentry::init`] function, +//! 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`]. //! //! 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 +//! 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 the various integrations that exist. Some of them are enabled -//! by default, some uncommon ones or for deprecated parts of the ecosystem a feature flag needs to -//! be enabled. For the available integrations and how to use them see -//! [integrations](integrations/index.html) and [apply_defaults](fn.apply_defaults.html). +//! 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 +//! 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. //! @@ -42,34 +53,58 @@ //! //! # Features //! -//! Functionality of the crate can be turned on and off by feature flags. This is the current list -//! of feature flags: -//! -//! 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`. -//! -//! Additional features: -//! -//! * `anyhow`: Enables support for the `anyhow` crate. -//! * `debug-images`: Attaches a list of loaded libraries to events (currently only supported on unix). -//! * `log`: Enables support for the `log` and `env_logger` crate. -//! * `slog`: Enables support for the `slog` crate. -//! * `tracing`: Enables support for the `tracing` crate. -//! * `test`: Enables testing support. -//! * `debug-logs`: Uses the `log` crate for internal logging. -//! * `reqwest`: Enables the `reqwest` transport, which is currently the default. -//! * `curl`: Enables the curl transport. -//! * `surf`: Enables the surf transport. -//! * `native-tls`: Uses the `native-tls` crate, which is currently the default. -//! This only has an effect on the `reqwest` transport. -//! * `rustls`: Enables the `rustls` support of the `reqwest` transport. -//! Please note that `native-tls` is a default feature, and one needs to use -//! `default-features = false` to completely disable building `native-tls` dependencies. - +//! 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` | | | | | +//! +//! [`sentry-log`]: https://crates.io/crates/sentry-log +//! [`sentry-slog`]: https://crates.io/crates/sentry-slog +//! +//! +//! Descriptions of all features, grouped by an arbitrary set of categories, sorted in a similarly +//! arbitrary order: +//! +//! ## 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`. +//! +//! ## Debugging/Testing +//! - `anyhow`: Enables support for the `anyhow` crate. +//! - `test`: Enables testing support. +//! - `debug-images`: Attaches a list of loaded libraries to events (currently only supported on Unix). +//! +//! ## 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. #![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)] @@ -89,28 +124,27 @@ pub use crate::init::{init, ClientInitGuard}; /// Available Sentry Integrations. /// /// Integrations extend the functionality of the SDK for some common frameworks and -/// libraries. Integrations come two primary kinds: as event *sources* or as event +/// libraries. Integrations come two primary kinds: as event *sources* or as event /// *processors*. /// -/// Integrations which are *sources*, like e.g. the -/// [`sentry::integrations::anyhow`](integrations::anyhow) integration, usually provide one -/// or more functions to create new events. They will usually provide their own extension -/// trait exposing a new method on the [`Hub`]. +/// Integrations which are *sources*, like e.g. the [`sentry::integrations::anyhow`] +/// integration, usually provide one or more functions to create new events. They +/// will usually provide their own extension trait exposing a new method on the +/// [`Hub`]. /// /// Integrations which *process* events in some way usually implement the -/// [`Itegration`](crate::Integration) trait and need to be installed when sentry is -/// initialised. +/// [`Integration`] trait and need to be installed when sentry is initialised. /// /// # Installing Integrations /// -/// Processing integrations which implement [`Integration`](crate::Integration) need to be -/// installed when sentry is initialised. This is done using the -/// [`ClientOptions::add_integration`](crate::ClientOptions::add_integration) function, which you can -/// use to add extra integrations. +/// Processing integrations which implement [`Integration`] need to be installed +/// when sentry is initialised. This is done using the +/// [`ClientOptions::add_integration`] function, which you can use to add extra +/// integrations. /// -/// For example if you disabled the default integrations (see below) but still wanted the -/// [`sentry::integrations::debug_images`](integrations::debug_images) integration enabled, -/// you could do this as such: +/// For example if you disabled the default integrations (see below) but still +/// wanted the [`sentry::integrations::debug_images`] integration enabled, you could +/// do the following: /// /// ``` /// # #[cfg(feature = "debug-images")] { @@ -127,13 +161,18 @@ pub use crate::init::{init, ClientInitGuard}; /// /// # Default Integrations /// -/// The [`ClientOptions::default_integrations`](crate::ClientOptions::default_integrations) -/// option is a boolean field that when enabled will enable a number of default integrations -/// **before** any integrations provided by -/// [`ClientOptions::integrations`](crate::ClientOptions::integrations) are installed. This -/// is done using the [`apply_defaults`] function, which should be consulted for more -/// details and the list of which integrations are enabled by default. +/// 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`]. /// +/// [`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")] diff --git a/sentry/src/transports/reqwest.rs b/sentry/src/transports/reqwest.rs index af986dbf8..fb77d9e65 100644 --- a/sentry/src/transports/reqwest.rs +++ b/sentry/src/transports/reqwest.rs @@ -11,6 +11,7 @@ use crate::{sentry_debug, ClientOptions, Envelope, Transport}; /// When the `transport` feature is enabled this will currently /// be the default transport. This is separately enabled by the /// `reqwest` flag. +/// [reqwest]: https://crates.io/crates/reqwest pub struct ReqwestHttpTransport { thread: TransportThread, } From 621e387a91aae4e34b9cd7c92218d1fa660c4b8b Mon Sep 17 00:00:00 2001 From: Betty Da Date: Mon, 21 Jun 2021 20:05:07 -0400 Subject: [PATCH 05/11] format table good --- sentry/README.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/sentry/README.md b/sentry/README.md index 64cab854c..bd99124e3 100644 --- a/sentry/README.md +++ b/sentry/README.md @@ -59,25 +59,25 @@ one should use the [`sentry-core`] crate instead. ## 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 additional setup; See [`sentry-log`]'s documentation. | -| `debug-logs` | | | ✂️ | | Requires additional setup; See [`sentry-log`]'s documentation. | -| `slog` | | 🔌 | | | Requires additional 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` | | | | | +extra setup to function properly. + +| Feature | Default | Is Integration | Deprecated | Additional notes | +| -------------- | ------- | -------------- | ---------- | ---------------------------------------------------------------------------------------- | +| `backtrace` | ✅ | 🔌 | | | +| `contexts` | ✅ | 🔌 | | | +| `panic` | ✅ | 🔌 | | | +| `transport` | ✅ | | | | +| `anyhow` | | 🔌 | | | +| `test` | | | | | +| `debug-images` | | 🔌 | | | +| `log` | | 🔌 | | Requires additional setup; See [`sentry-log`]'s documentation. | +| `debug-logs` | | | ✂️ | Requires additional setup; See [`sentry-log`]'s documentation. | +| `slog` | | 🔌 | | Requires additional 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` | | | | | [`sentry-log`]: https://docs.rs/sentry-log [`sentry-slog`]: https://docs.rs/sentry-slog From 2db6fa1c75e7b1104e1386d74c06abf6b17cc762 Mon Sep 17 00:00:00 2001 From: Betty Da Date: Mon, 21 Jun 2021 20:06:32 -0400 Subject: [PATCH 06/11] nitpicky phrasing changes --- sentry/src/lib.rs | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/sentry/src/lib.rs b/sentry/src/lib.rs index 34785fcbf..bf2e8327a 100644 --- a/sentry/src/lib.rs +++ b/sentry/src/lib.rs @@ -124,27 +124,26 @@ pub use crate::init::{init, ClientInitGuard}; /// Available Sentry Integrations. /// /// Integrations extend the functionality of the SDK for some common frameworks and -/// libraries. Integrations come two primary kinds: as event *sources* or as event -/// *processors*. +/// libraries. There are two different kinds of integrations: +/// - Event sources +/// - Event processors /// -/// Integrations which are *sources*, like e.g. the [`sentry::integrations::anyhow`] -/// integration, usually provide one or more functions to create new events. They -/// will usually provide their own extension trait exposing a new method on the -/// [`Hub`]. +/// 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 +/// 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 is done using the -/// [`ClientOptions::add_integration`] function, which you can use to add extra -/// integrations. +/// when sentry is initialised. This can be accomplished by using +/// [`ClientOptions::add_integration()`]. /// -/// For example if you disabled the default integrations (see below) but still -/// wanted the [`sentry::integrations::debug_images`] integration enabled, you could -/// do the following: +/// 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")] { @@ -163,17 +162,17 @@ pub use crate::init::{init, ClientInitGuard}; /// /// 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 +/// [`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`]. +/// [`apply_defaults()`]'s implementation. /// /// [`sentry::integrations::anyhow`]: integrations::anyhow /// [`Integration`]: crate::Integration -/// [`ClientOptions::add_integration`]: crate::ClientOptions::add_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 +/// [`apply_defaults()`]: ../fn.apply_defaults.html pub mod integrations { #[cfg(feature = "anyhow")] #[doc(inline)] From d2f3e3590e845f700a1bf774d7ece24ad6d73ec2 Mon Sep 17 00:00:00 2001 From: Betty Da Date: Mon, 21 Jun 2021 20:07:37 -0400 Subject: [PATCH 07/11] linter fixes and more nitpicky changes --- sentry/src/transports/curl.rs | 2 +- sentry/src/transports/reqwest.rs | 5 +++-- sentry/src/transports/surf.rs | 4 +++- 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/sentry/src/transports/curl.rs b/sentry/src/transports/curl.rs index 8a7468e17..4c1e4d5a3 100644 --- a/sentry/src/transports/curl.rs +++ b/sentry/src/transports/curl.rs @@ -9,7 +9,7 @@ use crate::{sentry_debug, types::Scheme, ClientOptions, Envelope, Transport}; /// A [`Transport`] that sends events via the [`curl`] library. /// -/// This is enabled by the `curl` flag. +/// This is enabled by the `curl` feature flag. pub struct CurlHttpTransport { thread: TransportThread, } diff --git a/sentry/src/transports/reqwest.rs b/sentry/src/transports/reqwest.rs index fb77d9e65..168e9ba77 100644 --- a/sentry/src/transports/reqwest.rs +++ b/sentry/src/transports/reqwest.rs @@ -10,8 +10,9 @@ use crate::{sentry_debug, ClientOptions, Envelope, Transport}; /// /// When the `transport` feature is enabled this will currently /// be the default transport. This is separately enabled by the -/// `reqwest` flag. -/// [reqwest]: https://crates.io/crates/reqwest +/// `reqwest` feature flag. +/// +/// [`reqwest`]: https://crates.io/crates/reqwest pub struct ReqwestHttpTransport { thread: TransportThread, } diff --git a/sentry/src/transports/surf.rs b/sentry/src/transports/surf.rs index 17d417566..e88c9f58b 100644 --- a/sentry/src/transports/surf.rs +++ b/sentry/src/transports/surf.rs @@ -8,7 +8,9 @@ use crate::{sentry_debug, ClientOptions, Envelope, Transport}; /// A [`Transport`] that sends events via the [`surf`] library. /// -/// This is enabled by the `surf` flag. +/// This is enabled by the `surf` feature flag. +/// +/// [`surf`]: https://crates.io/crates/surf pub struct SurfHttpTransport { thread: TransportThread, } From 7d5a6b5fc722a3d44728fb847df298be8d35d2aa Mon Sep 17 00:00:00 2001 From: Betty Da Date: Mon, 21 Jun 2021 20:08:48 -0400 Subject: [PATCH 08/11] use feature(doc_cfg) in docs to show feature requirements and fix a bad link --- sentry/Cargo.toml | 2 ++ sentry/src/lib.rs | 12 ++++++++++++ sentry/src/transports/curl.rs | 3 +++ sentry/src/transports/reqwest.rs | 3 +++ sentry/src/transports/surf.rs | 3 +++ 5 files changed, 23 insertions(+) diff --git a/sentry/Cargo.toml b/sentry/Cargo.toml index de42bf4f4..ce378e537 100644 --- a/sentry/Cargo.toml +++ b/sentry/Cargo.toml @@ -14,6 +14,8 @@ autoexamples = true [package.metadata.docs.rs] all-features = true +# defines the configuration attribute `doc_cfg` in order to expose feature-gated docs +rustdoc-args = ["--cfg", "doc_cfg"] [features] default = ["backtrace", "contexts", "panic", "transport"] diff --git a/sentry/src/lib.rs b/sentry/src/lib.rs index bf2e8327a..581a6f8e9 100644 --- a/sentry/src/lib.rs +++ b/sentry/src/lib.rs @@ -108,6 +108,10 @@ #![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; @@ -175,27 +179,35 @@ pub use crate::init::{init, ClientInitGuard}; /// [`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 = "tracing")] + #[cfg_attr(doc_cfg, doc(cfg(feature = "tracing")))] #[doc(inline)] pub use sentry_tracing as tracing; } diff --git a/sentry/src/transports/curl.rs b/sentry/src/transports/curl.rs index 4c1e4d5a3..90f021e02 100644 --- a/sentry/src/transports/curl.rs +++ b/sentry/src/transports/curl.rs @@ -10,10 +10,12 @@ use crate::{sentry_debug, types::Scheme, ClientOptions, Envelope, Transport}; /// A [`Transport`] that sends events via the [`curl`] library. /// /// This is enabled by the `curl` feature flag. +#[cfg_attr(doc_cfg, doc(cfg(feature = "curl")))] pub struct CurlHttpTransport { thread: TransportThread, } +#[cfg_attr(doc_cfg, doc(cfg(feature = "curl")))] impl CurlHttpTransport { /// Creates a new Transport. pub fn new(options: &ClientOptions) -> Self { @@ -122,6 +124,7 @@ impl CurlHttpTransport { } } +#[cfg_attr(doc_cfg, doc(cfg(feature = "curl")))] impl Transport for CurlHttpTransport { fn send_envelope(&self, envelope: Envelope) { self.thread.send(envelope) diff --git a/sentry/src/transports/reqwest.rs b/sentry/src/transports/reqwest.rs index 168e9ba77..ee4f3d2bf 100644 --- a/sentry/src/transports/reqwest.rs +++ b/sentry/src/transports/reqwest.rs @@ -13,10 +13,12 @@ use crate::{sentry_debug, ClientOptions, Envelope, Transport}; /// `reqwest` feature flag. /// /// [`reqwest`]: https://crates.io/crates/reqwest +#[cfg_attr(doc_cfg, doc(cfg(feature = "reqwest")))] pub struct ReqwestHttpTransport { thread: TransportThread, } +#[cfg_attr(doc_cfg, doc(cfg(feature = "reqwest")))] impl ReqwestHttpTransport { /// Creates a new Transport. pub fn new(options: &ClientOptions) -> Self { @@ -87,6 +89,7 @@ impl ReqwestHttpTransport { } } +#[cfg_attr(doc_cfg, doc(cfg(feature = "reqwest")))] impl Transport for ReqwestHttpTransport { fn send_envelope(&self, envelope: Envelope) { self.thread.send(envelope) diff --git a/sentry/src/transports/surf.rs b/sentry/src/transports/surf.rs index e88c9f58b..d1acdbc0f 100644 --- a/sentry/src/transports/surf.rs +++ b/sentry/src/transports/surf.rs @@ -11,10 +11,12 @@ use crate::{sentry_debug, ClientOptions, Envelope, Transport}; /// This is enabled by the `surf` feature flag. /// /// [`surf`]: https://crates.io/crates/surf +#[cfg_attr(doc_cfg, doc(cfg(feature = "surf")))] pub struct SurfHttpTransport { thread: TransportThread, } +#[cfg_attr(doc_cfg, doc(cfg(feature = "surf")))] impl SurfHttpTransport { /// Creates a new Transport. pub fn new(options: &ClientOptions) -> Self { @@ -73,6 +75,7 @@ impl SurfHttpTransport { } } +#[cfg_attr(doc_cfg, doc(cfg(feature = "surf")))] impl Transport for SurfHttpTransport { fn send_envelope(&self, envelope: Envelope) { self.thread.send(envelope) From 8e1ea1310486eae6994d314be9cbc30f27356617 Mon Sep 17 00:00:00 2001 From: Betty Da Date: Mon, 21 Jun 2021 20:26:43 -0400 Subject: [PATCH 09/11] undo readme changes since those files are generated --- README.md | 3 +- sentry-contexts/README.md | 2 +- sentry-core/README.md | 15 +++-- sentry-debug-images/README.md | 4 +- sentry-log/README.md | 2 +- sentry-panic/README.md | 2 +- sentry/README.md | 106 ++++++++++++---------------------- 7 files changed, 51 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index 79513c690..fc1c80550 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,7 @@ This workspace contains various crates that provide support for logging events a - [sentry](./sentry) [![crates.io](https://img.shields.io/crates/v/sentry.svg)](https://crates.io/crates/sentry) [![docs.rs](https://docs.rs/sentry/badge.svg)](https://docs.rs/sentry) - The main `sentry` crate aimed at application users that want to log events to sentry. You'll want - to start here if you're trying to use sentry in your application. + The main `sentry` crate aimed at application users that want to log events to sentry. - [sentry-actix](./sentry-actix) [![crates.io](https://img.shields.io/crates/v/sentry-actix.svg)](https://crates.io/crates/sentry-actix) diff --git a/sentry-contexts/README.md b/sentry-contexts/README.md index 23e27469a..c2d58763d 100644 --- a/sentry-contexts/README.md +++ b/sentry-contexts/README.md @@ -9,7 +9,7 @@ Adds Contexts to Sentry Events This integration is enabled by default in `sentry` and adds `device`, `os` -and `rust` contexts to Events, and also sets a `server_name` if it is not +and `rust` contexts to Events, as well as sets a `server_name` if not already defined. See the [Contexts Interface] documentation for more info. diff --git a/sentry-core/README.md b/sentry-core/README.md index c983b612e..bec12a526 100644 --- a/sentry-core/README.md +++ b/sentry-core/README.md @@ -6,14 +6,14 @@ # Sentry Rust SDK: sentry-core -This crate provides the core of the [Sentry] SDK, which can be used to log -events and errors. +This crate provides the core of the [Sentry](https://sentry.io/) SDK, which +can be used to log events and errors. -`sentry-core` is meant for integration authors and third-party library authors +This crate is meant for integration authors and third party library authors that want to instrument their code for sentry. Regular users who wish to integrate sentry into their applications should -instead use the [`sentry`] crate, which comes with a default transport and +rather use the [`sentry`] crate, which comes with a default transport, and a large set of integrations for various third-party libraries. ## Core Concepts @@ -34,16 +34,15 @@ functionality. ## Features -- `feature = "client"`: Activates the [`Client`] type and certain +* `feature = "client"`: Activates the [`Client`] type and certain [`Hub`] functionality. -- `feature = "test"`: Activates the [`test`] module, which can be used to +* `feature = "test"`: Activates the [`test`] module, which can be used to write integration tests. It comes with a test transport which can capture all sent events for inspection. -- `feature = "debug-logs"`: Uses the `log` crate for debug output, instead +* `feature = "debug-logs"`: Uses the `log` crate for debug output, instead of printing to `stderr`. This feature is **deprecated** and will be replaced by a dedicated log callback in the future. -[Sentry]: https://sentry.io/ [`sentry`]: https://crates.io/crates/sentry [Unified API]: https://develop.sentry.dev/sdk/unified-api/ [`Client`]: https://docs.rs/sentry-core/0.21.0/sentry_core/struct.Client.html diff --git a/sentry-debug-images/README.md b/sentry-debug-images/README.md index 7429dc657..c005176b6 100644 --- a/sentry-debug-images/README.md +++ b/sentry-debug-images/README.md @@ -6,12 +6,12 @@ # Sentry Rust SDK: sentry-debug-images -The Sentry Debug Images integration. +The Sentry Debug Images Integration. The [`DebugImagesIntegration`] adds metadata about the loaded shared libraries to Sentry [`Event`]s. -This Integration only works on Unix-like OSes right now. Support for Windows +This Integration only works on Unix-like OSs right now. Support for Windows will be added in the future. ## Configuration diff --git a/sentry-log/README.md b/sentry-log/README.md index dd462d75e..25e804bcf 100644 --- a/sentry-log/README.md +++ b/sentry-log/README.md @@ -10,7 +10,7 @@ Adds support for automatic Breadcrumb and Event capturing from logs. The `log` crate is supported in two ways. First, logs can be captured as breadcrumbs for later. Secondly, error logs can be captured as events to -Sentry. By default anything above `Info` is recorded as a breadcrumb and +Sentry. By default anything above `Info` is recorded as breadcrumb and anything above `Error` is captured as error event. ## Examples diff --git a/sentry-panic/README.md b/sentry-panic/README.md index 2d28cf80a..836996878 100644 --- a/sentry-panic/README.md +++ b/sentry-panic/README.md @@ -6,7 +6,7 @@ # Sentry Rust SDK: sentry-panic -The Sentry Panic handler integration. +The Sentry Panic handler Integration. The `PanicIntegration`, which is enabled by default in `sentry`, installs a panic handler that will automatically dispatch all errors to Sentry that diff --git a/sentry/README.md b/sentry/README.md index bd99124e3..0aa6f147f 100644 --- a/sentry/README.md +++ b/sentry/README.md @@ -7,20 +7,18 @@ # Sentry Rust SDK: sentry This crate provides support for logging events and errors / panics to the -[Sentry] error logging service. It integrates with the standard panic +[Sentry](https://sentry.io/) 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, +The most convenient way to use this library is the [`sentry::init`] function, which starts a sentry client with a default set of integrations, and binds it to the current [`Hub`]. 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 +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 @@ -30,25 +28,19 @@ sentry::capture_message("Hello World!", sentry::Level::Info); // 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`]: https://docs.rs/sentry/0.21.0/sentry/fn.init.html [`Hub`]: https://docs.rs/sentry/0.21.0/sentry/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](https://docs.rs/sentry/0.21.0/sentry/integrations/index.html) and -[apply_defaults](https://docs.rs/sentry/0.21.0/sentry/fn.apply_defaults.html). +What makes this crate useful are the various integrations that exist. Some of them are enabled +by default, some uncommon ones or for deprecated parts of the ecosystem a feature flag needs to +be enabled. For the available integrations and how to use them see +[integrations](https://docs.rs/sentry/0.21.0/sentry/integrations/index.html) and [apply_defaults](https://docs.rs/sentry/0.21.0/sentry/fn.apply_defaults.html). ## Minimal API -This crate comes fully-featured. If the goal is to instrument libraries for usage +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. @@ -58,57 +50,35 @@ one should use the [`sentry-core`] crate instead. ## 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 additional setup; See [`sentry-log`]'s documentation. | -| `debug-logs` | | | ✂️ | Requires additional setup; See [`sentry-log`]'s documentation. | -| `slog` | | 🔌 | | Requires additional 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` | | | | | - -[`sentry-log`]: https://docs.rs/sentry-log -[`sentry-slog`]: https://docs.rs/sentry-slog - -Descriptions of all features, grouped by an arbitrary set of categories, sorted in a similarly -arbitrary order: - -### 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`. - -### Debugging/Testing -- `anyhow`: Enables support for the `anyhow` crate. -- `test`: Enables testing support. -- `debug-images`: Attaches a list of loaded libraries to events (currently only supported on Unix). - -### 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. +Functionality of the crate can be turned on and off by feature flags. This is the current list +of feature flags: + +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`. + +Additional features: + +* `anyhow`: Enables support for the `anyhow` crate. +* `debug-images`: Attaches a list of loaded libraries to events (currently only supported on unix). +* `error-chain`: Enables support for the `error-chain` crate. +* `failure`: Enables support for the `failure` crate. +* `log`: Enables support for the `log` crate. +* `env_logger`: Enables support for the `log` crate with additional `env_logger` support. +* `slog`: Enables support for the `slog` crate. +* `test`: Enables testing support. +* `debug-logs`: Uses the `log` crate for internal logging. +* `reqwest`: Enables the `reqwest` transport, which is currently the default. +* `curl`: Enables the curl transport. +* `surf`: Enables the surf transport. +* `native-tls`: Uses the `native-tls` crate, which is currently the default. + This only has an effect on the `reqwest` transport. +* `rustls`: Enables the `rustls` support of the `reqwest` transport. + Please note that `native-tls` is a default feature, and one needs to use + `default-features = false` to completely disable building `native-tls` dependencies. ## Resources From 4c0726d67fc40b35f9c24743f09b5169366bdd1b Mon Sep 17 00:00:00 2001 From: Betty Da Date: Mon, 21 Jun 2021 21:09:39 -0400 Subject: [PATCH 10/11] remove doc(cfg) changes since they live in a different PR --- sentry/Cargo.toml | 2 -- sentry/src/lib.rs | 12 ------------ sentry/src/transports/curl.rs | 5 +---- sentry/src/transports/reqwest.rs | 7 +------ sentry/src/transports/surf.rs | 7 +------ 5 files changed, 3 insertions(+), 30 deletions(-) diff --git a/sentry/Cargo.toml b/sentry/Cargo.toml index ce378e537..de42bf4f4 100644 --- a/sentry/Cargo.toml +++ b/sentry/Cargo.toml @@ -14,8 +14,6 @@ autoexamples = true [package.metadata.docs.rs] all-features = true -# defines the configuration attribute `doc_cfg` in order to expose feature-gated docs -rustdoc-args = ["--cfg", "doc_cfg"] [features] default = ["backtrace", "contexts", "panic", "transport"] diff --git a/sentry/src/lib.rs b/sentry/src/lib.rs index 581a6f8e9..bf2e8327a 100644 --- a/sentry/src/lib.rs +++ b/sentry/src/lib.rs @@ -108,10 +108,6 @@ #![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; @@ -179,35 +175,27 @@ pub use crate::init::{init, ClientInitGuard}; /// [`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 = "tracing")] - #[cfg_attr(doc_cfg, doc(cfg(feature = "tracing")))] #[doc(inline)] pub use sentry_tracing as tracing; } diff --git a/sentry/src/transports/curl.rs b/sentry/src/transports/curl.rs index 90f021e02..8a7468e17 100644 --- a/sentry/src/transports/curl.rs +++ b/sentry/src/transports/curl.rs @@ -9,13 +9,11 @@ use crate::{sentry_debug, types::Scheme, ClientOptions, Envelope, Transport}; /// A [`Transport`] that sends events via the [`curl`] library. /// -/// This is enabled by the `curl` feature flag. -#[cfg_attr(doc_cfg, doc(cfg(feature = "curl")))] +/// This is enabled by the `curl` flag. pub struct CurlHttpTransport { thread: TransportThread, } -#[cfg_attr(doc_cfg, doc(cfg(feature = "curl")))] impl CurlHttpTransport { /// Creates a new Transport. pub fn new(options: &ClientOptions) -> Self { @@ -124,7 +122,6 @@ impl CurlHttpTransport { } } -#[cfg_attr(doc_cfg, doc(cfg(feature = "curl")))] impl Transport for CurlHttpTransport { fn send_envelope(&self, envelope: Envelope) { self.thread.send(envelope) diff --git a/sentry/src/transports/reqwest.rs b/sentry/src/transports/reqwest.rs index ee4f3d2bf..af986dbf8 100644 --- a/sentry/src/transports/reqwest.rs +++ b/sentry/src/transports/reqwest.rs @@ -10,15 +10,11 @@ use crate::{sentry_debug, ClientOptions, Envelope, Transport}; /// /// When the `transport` feature is enabled this will currently /// be the default transport. This is separately enabled by the -/// `reqwest` feature flag. -/// -/// [`reqwest`]: https://crates.io/crates/reqwest -#[cfg_attr(doc_cfg, doc(cfg(feature = "reqwest")))] +/// `reqwest` flag. pub struct ReqwestHttpTransport { thread: TransportThread, } -#[cfg_attr(doc_cfg, doc(cfg(feature = "reqwest")))] impl ReqwestHttpTransport { /// Creates a new Transport. pub fn new(options: &ClientOptions) -> Self { @@ -89,7 +85,6 @@ impl ReqwestHttpTransport { } } -#[cfg_attr(doc_cfg, doc(cfg(feature = "reqwest")))] impl Transport for ReqwestHttpTransport { fn send_envelope(&self, envelope: Envelope) { self.thread.send(envelope) diff --git a/sentry/src/transports/surf.rs b/sentry/src/transports/surf.rs index d1acdbc0f..17d417566 100644 --- a/sentry/src/transports/surf.rs +++ b/sentry/src/transports/surf.rs @@ -8,15 +8,11 @@ use crate::{sentry_debug, ClientOptions, Envelope, Transport}; /// A [`Transport`] that sends events via the [`surf`] library. /// -/// This is enabled by the `surf` feature flag. -/// -/// [`surf`]: https://crates.io/crates/surf -#[cfg_attr(doc_cfg, doc(cfg(feature = "surf")))] +/// This is enabled by the `surf` flag. pub struct SurfHttpTransport { thread: TransportThread, } -#[cfg_attr(doc_cfg, doc(cfg(feature = "surf")))] impl SurfHttpTransport { /// Creates a new Transport. pub fn new(options: &ClientOptions) -> Self { @@ -75,7 +71,6 @@ impl SurfHttpTransport { } } -#[cfg_attr(doc_cfg, doc(cfg(feature = "surf")))] impl Transport for SurfHttpTransport { fn send_envelope(&self, envelope: Envelope) { self.thread.send(envelope) From 158f7de22bc9e7d897a10a76eb85ee67bf8ca790 Mon Sep 17 00:00:00 2001 From: Betty Da Date: Mon, 21 Jun 2021 21:14:52 -0400 Subject: [PATCH 11/11] remove unnecessary line --- sentry/src/lib.rs | 4 ---- 1 file changed, 4 deletions(-) diff --git a/sentry/src/lib.rs b/sentry/src/lib.rs index bf2e8327a..be7614a80 100644 --- a/sentry/src/lib.rs +++ b/sentry/src/lib.rs @@ -77,10 +77,6 @@ //! [`sentry-log`]: https://crates.io/crates/sentry-log //! [`sentry-slog`]: https://crates.io/crates/sentry-slog //! -//! -//! Descriptions of all features, grouped by an arbitrary set of categories, sorted in a similarly -//! arbitrary order: -//! //! ## Default features //! - `backtrace`: Enables backtrace support. //! - `contexts`: Enables capturing device, OS, and Rust contexts.