diff --git a/docs/platforms/rust/guides/actix-web/index.mdx b/docs/platforms/rust/guides/actix-web/index.mdx index 1e2dab8681067..6361e7d6c74b5 100644 --- a/docs/platforms/rust/guides/actix-web/index.mdx +++ b/docs/platforms/rust/guides/actix-web/index.mdx @@ -1,16 +1,16 @@ --- title: Actix Web -description: "Learn about monitoring your Actix Web application with Sentry." +description: "Learn how to set up Sentry in your Actix Web application and capture your first events." --- -The Sentry SDK offers a middleware for the [Actix Web](https://actix.rs/) framework that supports: +The Sentry SDK offers middleware for the [Actix Web](https://actix.rs/) framework that supports: - Capturing server errors returned by Actix Web services. - Starting a [transaction](/concepts/key-terms/tracing/) for each request-response cycle. ## Install -To add Sentry with the Actix Web integration to your Rust project, add a new dependency to your `Cargo.toml`: +Add Sentry with the `actix` integration to your `Cargo.toml`: ```toml {filename:Cargo.toml} [dependencies] @@ -20,13 +20,11 @@ sentry = { version = "{{@inject packages.version('sentry.rust') }}", features = ## Configure -Initialize and configure the Sentry client. This will enable a set of default integrations, such as panic reporting. -Then, initialize Actix Web with the Sentry middleware. -The Sentry middleware provides correct request and trace association for any captured errors or panics, so it should be the first to process the request, that means it should be the last in your chain of `wrap` calls. +Initialize the Sentry client, then add the Sentry middleware to your Actix Web app. The example route returns an error so you can verify the setup in the next step. -Macros like `#[tokio::main]` and `#[actix_web::main]` are not supported. The Sentry client must be initialized before the async runtime is started, as shown below. +Macros like `#[tokio::main]` and `#[actix_web::main]` are not supported. Initialize the Sentry client before starting the async runtime, as shown below. @@ -45,22 +43,27 @@ fn main() -> io::Result<()> { sentry::ClientOptions::new() .dsn("___PUBLIC_DSN___") .maybe_release(sentry::release_name!()) - // Capture all traces and spans. Set to a lower value in production + // Enable tracing and capture all traces and spans. + // Reduce this sample rate in production, or remove it to disable tracing. .traces_sample_rate(1.0) - // Capture user IPs and potentially sensitive headers when using HTTP server integrations - // see https://docs.sentry.io/platforms/rust/data-management/data-collected for more info + // Capture user IPs and potentially sensitive headers when using HTTP server integrations. + // Review the data your app sends before enabling this option in production. .send_default_pii(true) - // Capture all HTTP request bodies, regardless of size + // Capture all HTTP request bodies, regardless of size. .max_request_body_size(sentry::MaxRequestBodySize::Always), ); actix_web::rt::System::new().block_on(async { HttpServer::new(|| { App::new() + // Keep Sentry last in the wrap chain so it processes requests first + // and associates captured errors and panics with the correct request. .wrap( sentry::integrations::actix::Sentry::builder() - .capture_server_errors(true) // Capture server errors - .start_transaction(true) // Start a transaction (Sentry root span) for each request + // Report server errors returned by services to Sentry. + .capture_server_errors(true) + // Start a transaction (Sentry root span) for each request. + .start_transaction(true) .finish(), ) .service(failing) @@ -74,24 +77,19 @@ fn main() -> io::Result<()> { } ``` -## Verify +## Verify Your Setup -The snippet above sets up a service that always fails, so you can test that everything is working as soon as you set it up. - -Send a request to the application. The response error will be captured by Sentry. +Run the example above, then send a request to its failing route. The route returns an error, and Sentry captures it. ```bash curl http://localhost:3001/ ``` - - -Learn more about manually capturing an error or message in our Usage documentation. - - - -To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and select your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. +To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and select your project. Select **Issues** in the sidebar to find the new issue. ## Next Steps -- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup. +- Learn how to manually capture errors. +- Instrument more operations with custom tracing. +- Add logs and application metrics with manual instrumentation. diff --git a/docs/platforms/rust/guides/axum/index.mdx b/docs/platforms/rust/guides/axum/index.mdx index 8bfa36ac49009..d06c3c044554b 100644 --- a/docs/platforms/rust/guides/axum/index.mdx +++ b/docs/platforms/rust/guides/axum/index.mdx @@ -1,20 +1,18 @@ --- title: axum -description: "Learn about monitoring your axum application with Sentry." +description: "Learn how to set up Sentry in your axum application and capture your first events." --- -The Sentry SDK offers a middleware for the [axum](https://github.com/tokio-rs/axum) framework that supports: +The Sentry SDK offers middleware for the [axum](https://github.com/tokio-rs/axum) framework that supports: - Reporting errors and panics with the correct request correlation. - Starting a [transaction](/concepts/key-terms/tracing/) for each request-response cycle. -The integration actually supports any crate based on [tower](https://github.com/tower-rs/tower), not just `axum`. +The integration also supports any crate based on [tower](https://github.com/tower-rs/tower), not just `axum`. ## Install - - -To add Sentry with the `axum` integration to your Rust project, add a new dependency to your `Cargo.toml`: +Add Sentry with the `axum` integration to your `Cargo.toml`: ```toml {filename:Cargo.toml} [dependencies] @@ -26,14 +24,11 @@ sentry = { version = "{{@inject packages.version('sentry.rust') }}", features = ## Configure -Initialize and configure the Sentry client. This will enable a set of default integrations, such as panic reporting. -Then, initialize `axum` with the Sentry middleware. - -This snippet sets up a service that always panics, so you can test that everything is working as soon as you set it up. +Initialize the Sentry client, then add the Sentry middleware to your axum app. The example route panics so you can verify the setup in the next step. -Macros like `#[tokio::main]` are not supported. The Sentry client must be initialized before the async runtime is started, as shown below. +Macros like `#[tokio::main]` are not supported. Initialize the Sentry client before starting the async runtime, as shown below. @@ -43,8 +38,8 @@ use sentry::integrations::tower::{NewSentryLayer, SentryHttpLayer}; use std::io; use tower::ServiceBuilder; -async fn failing() -> () { - panic!("Everything is on fire!") +async fn failing() { + panic!("Everything is on fire!"); } fn main() -> io::Result<()> { @@ -52,22 +47,21 @@ fn main() -> io::Result<()> { sentry::ClientOptions::new() .dsn("___PUBLIC_DSN___") .maybe_release(sentry::release_name!()) - # ___PRODUCT_OPTION_START___ performance - // Capture all traces and spans. Set to a lower value in production + // Enable tracing and capture all traces and spans. + // Reduce this sample rate in production, or remove it to disable tracing. .traces_sample_rate(1.0) - # ___PRODUCT_OPTION_END___ performance - // Capture user IPs and potentially sensitive headers when using HTTP server integrations - // see https://docs.sentry.io/platforms/rust/data-management/data-collected for more info + // Capture user IPs and potentially sensitive headers when using HTTP server integrations. + // Review the data your app sends before enabling this option in production. .send_default_pii(true), ); let app = Router::new().route("/", get(failing)).layer( ServiceBuilder::new() - .layer(NewSentryLayer::>::new_from_top()) // Bind a new Hub per request, to ensure correct error <> request correlation - # ___PRODUCT_OPTION_START___ performance - .layer(SentryHttpLayer::new().enable_transaction()), // Start a transaction (Sentry root span) for each request - // If you're binding the layers directly on the `Router`, bind them in the opposite order, otherwise you might run into a memory leak - # ___PRODUCT_OPTION_END___ performance + // Bind a new Hub per request to associate errors with the correct request. + .layer(NewSentryLayer::>::new_from_top()) + // Start a transaction (Sentry root span) for each request. + // If binding layers directly to the Router, reverse their order to avoid a memory leak. + .layer(SentryHttpLayer::new().enable_transaction()), ); tokio::runtime::Builder::new_multi_thread() @@ -86,22 +80,19 @@ fn main() -> io::Result<()> { } ``` -## Verify +## Verify Your Setup -Send a request to the application. The panic will be captured by Sentry. +Run the example above, then send a request to its failing route. The route panics, and Sentry captures the error. ```bash curl http://localhost:3001/ ``` - - -Learn more about manually capturing an error or message in our Usage documentation. - - - -To view and resolve the recorded panic, log into [sentry.io](https://sentry.io) and select your project. Select Issues, and then Errors & Outages in the sidebar, where you will find the newly created issue. Clicking on the issue's title will open a page where you can see detailed information and mark it as resolved. +To view and resolve the recorded panic, log into [sentry.io](https://sentry.io) and select your project. Select **Issues** in the sidebar to find the new issue. ## Next Steps -- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup. +- Learn how to manually capture errors. +- Instrument more operations with custom tracing. +- Add logs and application metrics with manual instrumentation. diff --git a/docs/platforms/rust/guides/tracing/index.mdx b/docs/platforms/rust/guides/tracing/index.mdx index c2d743cd9e6ac..fef492a0e5006 100644 --- a/docs/platforms/rust/guides/tracing/index.mdx +++ b/docs/platforms/rust/guides/tracing/index.mdx @@ -1,6 +1,6 @@ --- title: tokio-rs/tracing -description: "Learn about monitoring your Rust application with Sentry's tokio-rs/tracing integration." +description: "Learn how to set up Sentry in your Rust application and capture your first events with the tokio-rs/tracing integration." --- The Sentry SDK offers an integration for tokio's [tracing](https://github.com/tokio-rs/tracing) ecosystem that supports: @@ -12,15 +12,13 @@ The Sentry SDK offers an integration for tokio's [tracing](https://github.com/to ## Install -To add Sentry with the `tracing` integration to your Rust project, add the necessary dependencies to your `Cargo.toml`: +Add Sentry and the `tracing` dependencies to your `Cargo.toml`. The `tracing` feature enables the Sentry tracing integration. ```toml {filename:Cargo.toml} [dependencies] tracing = "0.1.41" tracing-subscriber = "0.3.19" -sentry = { version = "{{@inject packages.version('sentry.rust') }}", features = [ - "tracing" -] } +sentry = { version = "{{@inject packages.version('sentry.rust') }}", features = ["tracing"] } tokio = { version = "1.45.0", features = ["full"] } ``` @@ -30,31 +28,31 @@ Initialize the Sentry SDK and register the Sentry layers to start sending `traci -Macros like `#[tokio::main]` and `#[actix_web::main]` are not supported. The Sentry client must be initialized before the async runtime is started, as shown below. +Macros like `#[tokio::main]` and `#[actix_web::main]` are not supported. Initialize the Sentry client before starting the async runtime, as shown below. -```rust +```rust {filename:main.rs} use sentry::integrations::tracing::{LogLayer, SpanLayer}; +use sentry::SentryFutureExt; use tracing_subscriber::filter::LevelFilter; use tracing_subscriber::prelude::*; -fn main() { - // Initialize Sentry +fn main() -> Result<(), Box> { let _guard = sentry::init( sentry::ClientOptions::new() .dsn("___PUBLIC_DSN___") .maybe_release(sentry::release_name!()) - // Capture all traces and spans. Set to a lower value in production - .traces_sample_rate(1.0) + // Enable tracing and capture all traces and spans. + // Reduce this sample rate in production, or remove it to disable tracing. + .traces_sample_rate(1.0), ); - // Register the Sentry tracing layers tracing_subscriber::registry() .with(tracing_subscriber::fmt::layer()) - // Capture INFO, WARN, and ERROR spans as Sentry transactions and spans + // Capture INFO, WARN, and ERROR spans as Sentry transactions and spans. .with(SpanLayer::new().with_filter(LevelFilter::INFO)) - // Capture INFO, WARN, and ERROR events as Sentry logs + // Capture INFO, WARN, and ERROR events as Sentry logs. .with(LogLayer::new().with_filter(LevelFilter::INFO)) .init(); @@ -62,20 +60,29 @@ fn main() { .enable_all() .build()? .block_on(async { - // Futures should to be bound to a Hub - // Learn more at https://docs.rs/sentry-core/latest/sentry_core/#parallelism-concurrency-and-async + // Bind async work to the current Sentry Hub. fail().bind_hub(sentry::Hub::current()).await; }); + + Ok(()) } -#[tracing::instrument] // Captures a root span (transaction) around this function execution +#[tracing::instrument] // Capture a root span (transaction) around this function. async fn fail() { - tracing::info!("Doing work"); // Captured as a log - let _span = tracing::info_span("Child span").entered(); // Captures a child span - tracing::error!("Everything is on fire!"); // Captured as a log, linked to the child span + tracing::info!("Doing work"); // Capture a log. + let _span = tracing::info_span!("Child span").entered(); // Capture a child span. + tracing::error!("Everything is on fire!"); // Capture a log linked to the child span. } ``` +## Verify Your Setup + +Run the example above to send traces and logs to Sentry. Log into [sentry.io](https://sentry.io) and select your project. View the recorded traces and spans in **Explore > Traces**, and the recorded logs in **Explore > Logs**. + +The example captures `tracing::error!` as a log. To also create an issue, enable the optional [error layer](#capture-errors-as-issues), then run the example again and select **Issues** in the sidebar. + +## Customize Event Capture + The integration provides separate layers, so you can choose which `tracing` data to send to Sentry. We recommend enabling the span and log layers, as shown above: - [`SpanLayer`](https://docs.rs/sentry-tracing/latest/sentry_tracing/struct.SpanLayer.html): Captures `tracing` spans as Sentry transactions and spans. @@ -117,18 +124,9 @@ Events captured by `ErrorLayer` count toward your [error quota](/pricing/quotas/ The SDK also provides [`BreadcrumbLayer`](https://docs.rs/sentry-tracing/latest/sentry_tracing/struct.BreadcrumbLayer.html), which adds `tracing` events as breadcrumbs to subsequent Sentry errors. It's mainly there to support legacy setups. We recommend `LogLayer` instead, since logs are sent whether or not an error occurs. -## Verify - - - -Learn more about manually capturing an error or message in our Usage documentation. - - - -To view the recorded traces and spans, log into [sentry.io](https://sentry.io), select your project, and then select Explore > Traces in the sidebar. - -To view the recorded logs, select Explore > Logs in the sidebar. - ## Next Steps -- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup. +- Learn how to manually capture errors. +- Instrument more operations with custom tracing. +- Add application metrics with manual instrumentation. diff --git a/docs/platforms/rust/index.mdx b/docs/platforms/rust/index.mdx index 91429a0d22be9..52cb21a88895c 100644 --- a/docs/platforms/rust/index.mdx +++ b/docs/platforms/rust/index.mdx @@ -31,26 +31,33 @@ sentry = "{{@inject packages.version('sentry.rust') }}" ## Configure -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. +Call `sentry::init()` as early as possible in your `main` function. It starts a Sentry client with a default set of integrations, such as panic reporting, and binds it to the current Hub. -The `sentry::init` function returns a guard that when dropped, will flush Events that weren't yet sent to Sentry. It has a two-second deadline, so application shutdown may be slightly delayed as a result. Be sure to keep the guard or you won't be able to send events. +`sentry::init()` returns a guard that flushes events that haven't been sent yet when it's dropped. The flush has a two-second deadline, so application shutdown may be slightly delayed. Keep the guard alive for as long as your app runs, or the SDK won't be able to send events. ```rust {filename:main.rs} -let _guard = sentry::init( - sentry::ClientOptions::new() - .dsn("___PUBLIC_DSN___") - .maybe_release(sentry::release_name!()) - // Capture user IPs and potentially sensitive headers when using HTTP server integrations - // see https://docs.sentry.io/platforms/rust/data-management/data-collected for more info - .send_default_pii(true), -); +fn main() { + let _guard = sentry::init( + sentry::ClientOptions::new() + .dsn("___PUBLIC_DSN___") + .maybe_release(sentry::release_name!()) + // Enable tracing and capture all traces and spans. + // Reduce this sample rate in production, or remove it to disable tracing. + .traces_sample_rate(1.0) + // Capture user IPs and potentially sensitive headers when using HTTP server integrations. + // Review the data your app sends before enabling this option in production. + .send_default_pii(true), + ); + + // implementation of main +} ``` **Important:** Remember your DSN. The DSN (Data Source Name) tells the SDK where to send events. If you forget it, you can find it by going to: Settings -> Projects -> [Client Keys (DSN)](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/keys/) in sentry.io. ### Async Main Function -In a multithreaded application, spawned threads should inherit the Hub from the main thread. In order for that to happen, the Sentry client must be initialized before starting an async runtime or spawning threads. This means you'll have to avoid using macros such as `#[tokio::main]` or `#[actix_web::main]`, because they start the runtime first. So rather than doing this: +In a multithreaded application, spawned threads should inherit the Hub from the main thread. For that to happen, initialize the Sentry client before starting an async runtime or spawning threads. This means you'll have to avoid macros such as `#[tokio::main]` or `#[actix_web::main]`, because they start the runtime first. So rather than doing this: ```rust {filename:main.rs} // WRONG @@ -59,10 +66,7 @@ async fn main() { let _guard = sentry::init( sentry::ClientOptions::new() .dsn("___PUBLIC_DSN___") - .maybe_release(sentry::release_name!()) - // Capture user IPs and potentially sensitive headers when using HTTP server integrations - // see https://docs.sentry.io/platforms/rust/data-management/data-collected for more info - .send_default_pii(true), + .maybe_release(sentry::release_name!()), ); // implementation of main @@ -77,10 +81,7 @@ fn main() { let _guard = sentry::init( sentry::ClientOptions::new() .dsn("___PUBLIC_DSN___") - .maybe_release(sentry::release_name!()) - // Capture user IPs and potentially sensitive headers when using HTTP server integrations - // see https://docs.sentry.io/platforms/rust/data-management/data-collected for more info - .send_default_pii(true), + .maybe_release(sentry::release_name!()), ); tokio::runtime::Builder::new_multi_thread() @@ -93,33 +94,9 @@ fn main() { } ``` -## Verify Setup +### Integrations -The quickest way to verify Sentry in your Rust application is to cause a panic: - -```rust {filename:main.rs} -fn main() { - let _guard = sentry::init( - sentry::ClientOptions::new() - .dsn("___PUBLIC_DSN___") - .maybe_release(sentry::release_name!()) - // Capture user IPs and potentially sensitive headers when using HTTP server integrations - // see https://docs.sentry.io/platforms/rust/data-management/data-collected for more info - .send_default_pii(true), - ); - - // Sentry will capture this - panic!("Everything is on fire!"); -} -``` - -## Integrations - -_Integrations_ extend the functionality of the SDK for some common frameworks -and libraries. - -A list of integrations and their feature flags can be found -[in the integration API docs](https://docs.rs/sentry/0/sentry/integrations/index.html). +_Integrations_ extend the functionality of the SDK for some common frameworks and libraries. A list of integrations and their feature flags can be found [in the integration API docs](https://docs.rs/sentry/0/sentry/integrations/index.html). @@ -131,13 +108,21 @@ Conflicts could lead to UI warning messages in Sentry, as it can be interpreted -## More Information +## Verify Your Setup + +The quickest way to verify Sentry in your Rust application is to cause a panic after initializing the SDK: + +```rust {filename:main.rs} +// Sentry will capture this +panic!("Everything is on fire!"); +``` -- [API Docs](https://docs.rs/sentry) -- [Crates.io page](https://crates.io/crates/sentry) -- [Bug Tracker](https://github.com/getsentry/sentry-rust/issues) -- [GitHub Project](https://github.com/getsentry/sentry-rust) +To view and resolve the recorded panic, log into [sentry.io](https://sentry.io) and select your project. Select **Issues** in the sidebar to find the new issue. ## Next Steps -- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Enable additional [framework and library integrations](#integrations) for your app. These integrations require explicit configuration or Cargo feature flags. +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup. +- Learn how to manually capture errors. +- Instrument more operations with custom tracing. +- Browse the [API docs](https://docs.rs/sentry), the [crates.io page](https://crates.io/crates/sentry), and the [GitHub project](https://github.com/getsentry/sentry-rust). Report bugs in the [issue tracker](https://github.com/getsentry/sentry-rust/issues).