From c6be968360f5b3dca3df59f8382e1bd00274dd35 Mon Sep 17 00:00:00 2001 From: Daniel Szoke Date: Thu, 23 Jul 2026 13:30:16 +0200 Subject: [PATCH] docs(rust): Document new Rust configuration Document the Rust SDK's new configuration options, to be introduced in version 0.49.0. This release will fundamentally change how we configure SDK options. The API now uses a builder pattern rather than a struct literal; the old API no longer works. We made this change in order to allow for greater future compatibility going forward. Resolves #18814 Resolves [DOCS-2913](https://linear.app/getsentry/issue/DOCS-2913/document-new-builder-api) --- .../rust/common/configuration/options.mdx | 20 ++++-- .../rust/common/configuration/releases.mdx | 34 +++++----- .../rust/common/configuration/sampling.mdx | 47 ++++++------- docs/platforms/rust/common/logs/index.mdx | 53 +++++++-------- docs/platforms/rust/common/tracing/index.mdx | 2 +- .../automatic-instrumentation.mdx | 30 ++++---- .../rust/common/troubleshooting/index.mdx | 2 +- .../platforms/rust/guides/actix-web/index.mdx | 18 +++-- docs/platforms/rust/guides/axum/index.mdx | 16 ++--- docs/platforms/rust/guides/tracing/index.mdx | 16 ++--- docs/platforms/rust/index.mdx | 68 ++++++++++--------- .../configuration/before-send/rust.mdx | 11 ++- .../configuration/config-intro/rust.mdx | 21 +++--- .../configuration/sample-rate/rust.mdx | 5 +- .../getting-started-config/rust.mdx | 15 ++-- platform-includes/metrics/options/rust.mdx | 30 ++++---- .../configure-sample-rate/rust.mdx | 14 ++-- .../force-sampling-decision/rust.mdx | 4 ++ .../performance/traces-sample-rate/rust.mdx | 11 +-- .../performance/uniform-sample-rate/rust.mdx | 4 +- platform-includes/set-environment/rust.mdx | 5 +- platform-includes/set-release/rust.mdx | 13 ++-- 22 files changed, 218 insertions(+), 221 deletions(-) diff --git a/docs/platforms/rust/common/configuration/options.mdx b/docs/platforms/rust/common/configuration/options.mdx index 9370a05cba9849..a745e38e15aba6 100644 --- a/docs/platforms/rust/common/configuration/options.mdx +++ b/docs/platforms/rust/common/configuration/options.mdx @@ -8,6 +8,8 @@ description: "Learn more about how the SDK can be configured via options. These ## Available Options +Configure `ClientOptions` with builder methods such as `.dsn(...)`, `.sample_rate(...)`, and `.traces_sample_rate(...)`. Public fields remain readable after construction, but builders are the supported way to create options because `ClientOptions` is non-exhaustive. + ## Core Options @@ -32,6 +34,8 @@ Turns debug mode on or off. If debug is enabled, the SDK will attempt to print o Sets the release. This string is freeform and not set by default. Some formats are detected by Sentry and might be rendered differently. Learn more about how to send release data so Sentry can tell you about regressions between releases and identify the potential source in [the releases documentation](/product/releases/) or the sandbox. +Use `.release(...)` with a string, or `.maybe_release(sentry::release_name!())` when using the optional value returned by the release macro. + @@ -131,7 +135,9 @@ The list of default integrations depends on the feature flags of the `sentry` cr -Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly. +Configures the fixed sample rate for error events through the `.sample_rate(...)` builder, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly. + +Under the hood, this sets `event_sampling_strategy` to `EventSamplingStrategy::FixedRate`. Fixed-rate sampling is currently the only supported event sampling strategy; the SDK does not provide a callback-based event sampler. @@ -145,15 +151,21 @@ By the time `before_send` is executed, all scope data has already been applied t ## Tracing Options - +The SDK stores one traces sampling strategy at a time (`traces_sampling_strategy`). Configure it with either `.traces_sample_rate(...)` or `.traces_sampler(...)`. These builders are mutually exclusive: each call replaces the previous strategy, so the last builder called wins. The default is `TracesSamplingStrategy::Disabled`, which is not the same as an explicit fixed rate of `0.0`. -A number between `0.0` and `1.0`, controlling the percentage chance a given transaction will be sent to Sentry (`0.0` represents 0% while `1.0` represents 100%.) Applies equally to all transactions created in the app. + + +A number between `0.0` and `1.0`, controlling the percentage chance a given transaction will be sent to Sentry (`0.0` represents 0% while `1.0` represents 100%.) Applies when there is no inherited parent sampling decision. + +Calling `.traces_sample_rate(...)` selects `TracesSamplingStrategy::FixedRate`, including when the rate is `0.0`. That explicit fixed-rate strategy can still honor an inherited parent sampling decision. Leaving tracing at the default disabled strategy rejects transactions even when a parent or explicit decision is positive. -If given, called with a `SamplingContext` for each transaction to determine the sampling rate. Return a sample rate between `0.0` and `1.0` for the transaction in question. Takes priority over the `traces_sample_rate`. +If given, called with a `TransactionContext` for each transaction to determine the sampling rate. Return a sample rate between `0.0` and `1.0` for the transaction in question. + +Calling `.traces_sampler(...)` selects `TracesSamplingStrategy::Function` and replaces any strategy previously set with `.traces_sample_rate(...)`. The callback receives the transaction context, including any parent sampling decision in `ctx.sampled()`, and decides the rate itself. diff --git a/docs/platforms/rust/common/configuration/releases.mdx b/docs/platforms/rust/common/configuration/releases.mdx index 516e713bea9878..f9b8ad50a02626 100644 --- a/docs/platforms/rust/common/configuration/releases.mdx +++ b/docs/platforms/rust/common/configuration/releases.mdx @@ -21,24 +21,22 @@ Additionally, you need to initialize the SDK by specifying additional options: ```rust use sentry; -let _guard = sentry::init(("___PUBLIC_DSN___", sentry::ClientOptions { - // The `sentry::release_name` macro automatically infers the release from the cargo metadata, and is the preferred way to set the release - release: sentry::release_name!(), - // OR, manually: - // release: Some("my-project-name@2.3.12".into()), - - // Enables automatic session tracking, according to the configured `session_mode`. - // If the value of this option is set `false`, sessions need to be manually managed using `sentry::start_session` and `sentry::stop_session`. - auto_session_tracking: true, - - // Sets the automatic session tracking mode. - // Possible values are `sentry::SessionMode::Application` and `sentry::SessionMode::Request`. - // `Application` should be used for user-attended programs, which typically have a single long running session that span the application's lifetime. - // `Request` should be used for servers, where each incoming request shall be considered as its own session. - session_mode: sentry::SessionMode::Application, - - ..Default::default() -})); +let _guard = sentry::init( + sentry::ClientOptions::new() + .dsn("___PUBLIC_DSN___") + // The `sentry::release_name` macro automatically infers the release from the cargo metadata, and is the preferred way to set the release + .maybe_release(sentry::release_name!()) + // OR, manually: + // .release("my-project-name@2.3.12") + // Enables automatic session tracking, according to the configured `session_mode`. + // If the value of this option is set `false`, sessions need to be manually managed using `sentry::start_session` and `sentry::stop_session`. + .auto_session_tracking(true) + // Sets the automatic session tracking mode. + // Possible values are `sentry::SessionMode::Application` and `sentry::SessionMode::Request`. + // `Application` should be used for user-attended programs, which typically have a single long running session that span the application's lifetime. + // `Request` should be used for servers, where each incoming request shall be considered as its own session. + .session_mode(sentry::SessionMode::Application), +); ``` ## Setting a Release diff --git a/docs/platforms/rust/common/configuration/sampling.mdx b/docs/platforms/rust/common/configuration/sampling.mdx index 576ef12e6758d3..08fb793ee7ed11 100644 --- a/docs/platforms/rust/common/configuration/sampling.mdx +++ b/docs/platforms/rust/common/configuration/sampling.mdx @@ -9,7 +9,7 @@ Adding Sentry to your app gives you a great deal of very valuable information ab ## Sampling Error Events -To send a representative sample of your errors to Sentry, set the option in your SDK configuration to a number between `0` (0% of errors sent) and `1` (100% of errors sent). This is a static rate, which will apply equally to all errors. For example, to sample 25% of your errors: +To send a representative sample of your errors to Sentry, call the builder on your `ClientOptions` with a number between `0` (0% of errors sent) and `1` (100% of errors sent). This is a static rate, which will apply equally to all errors. For example, to sample 25% of your errors: @@ -32,25 +32,23 @@ Choose a sampling rate with the goal of finding a balance between performance an ## Configuring the Transaction Sample Rate -The Sentry SDKs have two configuration options to control the volume of transactions sent to Sentry, allowing you to take a representative sample: +The Rust SDK stores a single traces sampling strategy. Configure it with one of these builders: 1. Uniform sample rate (): - - Provides an even cross-section of transactions, no matter where in your app or under what circumstances they occur. - - Uses default [inheritance](#inheritance) and [precedence](#precedence) behavior + - Selects `TracesSamplingStrategy::FixedRate` + - Provides an even cross-section of transactions, no matter where in your app or under what circumstances they occur + - Uses default [inheritance](#inheritance) and [precedence](#precedence) behavior for the fixed-rate strategy 2. Sampling function () which: + - Selects `TracesSamplingStrategy::Function` - Samples different transactions at different rates - Filters out some transactions entirely - - Modifies default [precedence](#precedence) and [inheritance](#inheritance) behavior + - Decides through the callback instead of the fixed-rate inheritance path -By default, none of these options are set, meaning no transactions will be sent to Sentry. You must set either one of the options to start sending transactions. +These builders are mutually exclusive. Each call replaces the previous strategy, so the last sampling builder called wins. - - -Sampling functions () are currently not supported by this platform. - - +By default, the strategy is `TracesSamplingStrategy::Disabled`, meaning tracing is off and transactions are not sent. You must call either `.traces_sample_rate(...)` or `.traces_sampler(...)` to enable a non-disabled strategy. Calling `.traces_sample_rate(0.0)` is an explicit fixed-rate strategy and is not equivalent to leaving tracing disabled; see [inheritance](#inheritance). ### Setting a Uniform Sample Rate @@ -62,32 +60,31 @@ Whatever a transaction's sampling decision, that decision will be passed to its (See Distributed Tracing for more about how that propagation is done.) -If the transaction currently being created is one of those subsequent transactions (in other words, if it has a parent transaction), the upstream (parent) sampling decision will be included in the sampling context data. Your can use this information to choose whether to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. - - - -In some SDKs, for convenience, the function can return a boolean, so that a parent's decision can be returned directly if that's the desired behavior. +If the transaction currently being created is one of those subsequent transactions (in other words, if it has a parent transaction), the upstream (parent) sampling decision is available on the transaction context as `ctx.sampled()`. Behavior depends on the configured strategy: - +- `TracesSamplingStrategy::Disabled` (default): the transaction is not sent, even when a parent decision is positive. +- `TracesSamplingStrategy::FixedRate` (from `.traces_sample_rate(...)`): an inherited parent decision is honored. When there is no parent decision, the configured fixed rate is used. This remains true for an explicit rate of `0.0`. +- `TracesSamplingStrategy::Function` (from `.traces_sampler(...)`): the callback receives the transaction context, including any parent decision, and returns the sample rate. Inherit the parent decision in the callback when you want to keep distributed traces intact. -If you're using a rather than a , the decision will always be inherited. +In most cases, inheriting a parent decision is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. ## Precedence There are multiple ways for a transaction to end up with a sampling decision. -- Random sampling according to a static sample rate set in +- The default disabled traces sampling strategy +- Random sampling according to a static sample rate set with - Random sampling according to a sample function rate returned by - Absolute decision (100% chance or 0% chance) returned by - If the transaction has a parent, inheriting its parent's sampling decision -- Absolute decision passed to +- Explicit decision set on the transaction context, for example with `ctx.set_sampled(true)` before `start_transaction` -When there's the potential for more than one of these to come into play, the following precedence rules apply: +Because only one traces sampling strategy is active at a time, strategy selection is last-builder-call-wins when both `.traces_sample_rate(...)` and `.traces_sampler(...)` appear in configuration. Once a strategy is selected, the following rules apply: -1. If a sampling decision is passed to , that decision will be used, overriding everything else. -1. If is defined, its decision will be used. It can choose to keep or ignore any parent sampling decision, use the sampling context data to make its own decision, or choose a sample rate for the transaction. We advise against overriding the parent sampling decision because it will break distributed traces) -1. If is not defined, but there's a parent sampling decision, the parent sampling decision will be used. -1. If is not defined and there's no parent sampling decision, will be used. +1. If the strategy is `Disabled`, the transaction is not sampled. +2. If the strategy is `Function`, the callback's returned rate is used. The callback may read or ignore a parent decision on the transaction context. +3. If the strategy is `FixedRate` and the transaction context carries an explicit sampling decision (from a parent or from `set_sampled`), that decision is used. +4. If the strategy is `FixedRate` and there is no explicit decision, the configured fixed rate is used. diff --git a/docs/platforms/rust/common/logs/index.mdx b/docs/platforms/rust/common/logs/index.mdx index 5865cd216204f0..3d6337a2d15109 100644 --- a/docs/platforms/rust/common/logs/index.mdx +++ b/docs/platforms/rust/common/logs/index.mdx @@ -81,14 +81,12 @@ use tracing::{error, info, warn}; use tracing_subscriber::prelude::*; fn main() { - let _guard = sentry::init(( - "___PUBLIC_DSN___", - sentry::ClientOptions { - release: sentry::release_name!(), - enable_logs: true, - ..Default::default() - }, - )); + let _guard = sentry::init( + sentry::ClientOptions::new() + .dsn("___PUBLIC_DSN___") + .maybe_release(sentry::release_name!()) + .enable_logs(true), + ); tracing_subscriber::registry() .with(tracing_subscriber::fmt::layer()) @@ -148,14 +146,12 @@ use sentry_log::LogFilter; use log::{info, warn, error}; fn main() { - let _guard = sentry::init(( - "___PUBLIC_DSN___", - sentry::ClientOptions { - release: sentry::release_name!(), - enable_logs: true, - ..Default::default() - }, - )); + let _guard = sentry::init( + sentry::ClientOptions::new() + .dsn("___PUBLIC_DSN___") + .maybe_release(sentry::release_name!()) + .enable_logs(true), + ); let logger = sentry::integrations::log::SentryLogger::with_dest( env_logger::Builder::from_default_env().build(), @@ -181,18 +177,19 @@ If you'd like to see support for additional logging libraries, please open a [ne To filter logs, or update them before they are sent to Sentry, you can use the `before_send_log` client option. ```rust -let _guard = sentry::init(("___PUBLIC_DSN___", sentry::ClientOptions { - release: sentry::release_name!(), - enable_logs: true, - before_send_log: Some(std::sync::Arc::new(|log| { - // filter out all trace level logs - if log.level == sentry::protocol::LogLevel::Trace { - return None; - } - Some(log) - })), - ..Default::default() -})); +let _guard = sentry::init( + sentry::ClientOptions::new() + .dsn("___PUBLIC_DSN___") + .maybe_release(sentry::release_name!()) + .enable_logs(true) + .before_send_log(|log| { + // filter out all trace level logs + if log.level == sentry::protocol::LogLevel::Trace { + return None; + } + Some(log) + }), +); ``` ## Default Attributes diff --git a/docs/platforms/rust/common/tracing/index.mdx b/docs/platforms/rust/common/tracing/index.mdx index 2343b80a8ae1d6..b33c6a55db1211 100644 --- a/docs/platforms/rust/common/tracing/index.mdx +++ b/docs/platforms/rust/common/tracing/index.mdx @@ -21,7 +21,7 @@ First, enable tracing and configure the sample rate for transactions. Set the sa - Setting a uniform sample rate for all transactions using the option in your SDK config to a number between `0` and `1`. (For example, to send 20% of transactions, set to `0.2`.) - Controlling the sample rate based on the transaction itself and the context in which it's captured, by providing a function to the config option. -The two options are meant to be mutually exclusive. If you set both, will take precedence. +These builders select mutually exclusive strategies. The last sampling builder called wins. Tracing defaults to disabled (`TracesSamplingStrategy::Disabled`); you must configure a non-disabled strategy before transactions are sent. An explicit `.traces_sample_rate(0.0)` is not the same as leaving tracing disabled, because the fixed-rate strategy can still honor an inherited parent sampling decision. diff --git a/docs/platforms/rust/common/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/rust/common/tracing/instrumentation/automatic-instrumentation.mdx index 01b00c380ea100..99e4c1bd19549e 100644 --- a/docs/platforms/rust/common/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/rust/common/tracing/instrumentation/automatic-instrumentation.mdx @@ -24,14 +24,14 @@ fn main() { .with(sentry::integrations::tracing::layer()) .init(); - let _guard = sentry::init(sentry::ClientOptions { - release: sentry::release_name!(), - 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 - send_default_pii: true, - ..Default::default() - }); + let _guard = sentry::init( + sentry::ClientOptions::new() + .maybe_release(sentry::release_name!()) + .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 + .send_default_pii(true), + ); main_span1(); } @@ -79,15 +79,13 @@ use opentelemetry_sdk::trace::SdkTracerProvider; use sentry::integrations::opentelemetry as sentry_opentelemetry; // Initialize the Sentry SDK -let _guard = sentry::init(( - "___PUBLIC_DSN___", - sentry::ClientOptions { - release: sentry::release_name!(), +let _guard = sentry::init( + sentry::ClientOptions::new() + .dsn("___PUBLIC_DSN___") + .maybe_release(sentry::release_name!()) // Enable capturing of traces; set this a to lower value in production. - traces_sample_rate: 1.0, - ..sentry::ClientOptions::default() - }, -)); + .traces_sample_rate(1.0), +); // Register the Sentry propagator for distributed tracing global::set_text_map_propagator(sentry_opentelemetry::SentryPropagator::new()); diff --git a/docs/platforms/rust/common/troubleshooting/index.mdx b/docs/platforms/rust/common/troubleshooting/index.mdx index 9d36a3e8370e62..15f8082dc3d0c1 100644 --- a/docs/platforms/rust/common/troubleshooting/index.mdx +++ b/docs/platforms/rust/common/troubleshooting/index.mdx @@ -5,7 +5,7 @@ sidebar_section: configuration description: "If you need help solving issues with the Sentry Rust SDK, you can read the edge cases documented below." --- -To start debugging any SDK issue, enable debug mode by setting `debug: true` in the `ClientOptions` struct you pass to `sentry::init`. +To start debugging any SDK issue, enable debug mode by calling `.debug(true)` on the `ClientOptions` builder you pass to `sentry::init`. This will make the SDK log additional debug information on stderr. Below is a list of common problems and how to solve them. diff --git a/docs/platforms/rust/guides/actix-web/index.mdx b/docs/platforms/rust/guides/actix-web/index.mdx index 9dcda181c6cc23..920460d50cf098 100644 --- a/docs/platforms/rust/guides/actix-web/index.mdx +++ b/docs/platforms/rust/guides/actix-web/index.mdx @@ -41,20 +41,18 @@ async fn failing(_req: HttpRequest) -> Result { } fn main() -> io::Result<()> { - let _guard = sentry::init(( - "___PUBLIC_DSN___", - sentry::ClientOptions { - release: sentry::release_name!(), + 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, + .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 - send_default_pii: true, + .send_default_pii(true) // Capture all HTTP request bodies, regardless of size - max_request_body_size: sentry::MaxRequestBodySize::Always, - ..Default::default() - }, - )); + .max_request_body_size(sentry::MaxRequestBodySize::Always), + ); actix_web::rt::System::new().block_on(async { HttpServer::new(|| { diff --git a/docs/platforms/rust/guides/axum/index.mdx b/docs/platforms/rust/guides/axum/index.mdx index c9e1bf93d0199c..8f37b93370577b 100644 --- a/docs/platforms/rust/guides/axum/index.mdx +++ b/docs/platforms/rust/guides/axum/index.mdx @@ -48,20 +48,18 @@ async fn failing() -> () { } fn main() -> io::Result<()> { - let _guard = sentry::init(( - "___PUBLIC_DSN___", - sentry::ClientOptions { - release: sentry::release_name!(), + let _guard = sentry::init( + 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 - traces_sample_rate: 1.0, + .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 - send_default_pii: true, - ..Default::default() - }, - )); + .send_default_pii(true), + ); let app = Router::new().route("/", get(failing)).layer( ServiceBuilder::new() diff --git a/docs/platforms/rust/guides/tracing/index.mdx b/docs/platforms/rust/guides/tracing/index.mdx index 22198761213b67..f4813fea2e8924 100644 --- a/docs/platforms/rust/guides/tracing/index.mdx +++ b/docs/platforms/rust/guides/tracing/index.mdx @@ -45,20 +45,18 @@ use tracing_subscriber::prelude::*; fn main() { // Initialize Sentry - let _guard = sentry::init(( - "___PUBLIC_DSN___", - sentry::ClientOptions { - release: sentry::release_name!(), + let _guard = sentry::init( + 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 - traces_sample_rate: 1.0, + .traces_sample_rate(1.0) # ___PRODUCT_OPTION_END___ performance # ___PRODUCT_OPTION_START___ logs - enable_logs:true + .enable_logs(true), # ___PRODUCT_OPTION_END___ logs - ..sentry::ClientOptions::default() - }, - )); + ); // Register the Sentry tracing layer tracing_subscriber::registry() diff --git a/docs/platforms/rust/index.mdx b/docs/platforms/rust/index.mdx index 2ed530ec808a9b..8dbc49db1c5f05 100644 --- a/docs/platforms/rust/index.mdx +++ b/docs/platforms/rust/index.mdx @@ -36,13 +36,14 @@ The most convenient way to use this library is the `sentry::init` function, whic 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. ```rust {filename:main.rs} -let _guard = sentry::init(("___PUBLIC_DSN___", sentry::ClientOptions { - 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, - ..Default::default() -})); +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), +); ``` **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) in sentry.io. @@ -55,15 +56,16 @@ In a multithreaded application, spawned threads should inherit the Hub from the // WRONG #[tokio::main] async fn main() { -let _guard = sentry::init(("___PUBLIC_DSN___", sentry::ClientOptions { - 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, - ..Default::default() -})); - -// implementation of 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), + ); + + // implementation of main } ``` @@ -72,15 +74,16 @@ Do this instead: ```rust {filename:main.rs} // RIGHT fn main() { -let _guard = sentry::init(("___PUBLIC_DSN___", sentry::ClientOptions { - 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, - ..Default::default() -})); - -tokio::runtime::Builder::new_multi_thread() + 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), + ); + + tokio::runtime::Builder::new_multi_thread() .enable_all() .build() .unwrap() @@ -96,13 +99,14 @@ 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(("___PUBLIC_DSN___", sentry::ClientOptions { - 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, - ..Default::default() - })); + 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!"); diff --git a/platform-includes/configuration/before-send/rust.mdx b/platform-includes/configuration/before-send/rust.mdx index 105cbe82810f11..0eedb9477d9444 100644 --- a/platform-includes/configuration/before-send/rust.mdx +++ b/platform-includes/configuration/before-send/rust.mdx @@ -1,10 +1,9 @@ ```rust -sentry::init(sentry::ClientOptions { - before_send: Some(Arc::new(|mut event| { +sentry::init( + sentry::ClientOptions::new().before_send(|mut event| { // Modify event here - event.server_name = None; // Don't send server name + event.server_name = None; // Don't send server name Some(event) - })), - ..Default::default() -}); + }), +); ``` diff --git a/platform-includes/configuration/config-intro/rust.mdx b/platform-includes/configuration/config-intro/rust.mdx index dc2abca10d0001..4b8ff329ce2874 100644 --- a/platform-includes/configuration/config-intro/rust.mdx +++ b/platform-includes/configuration/config-intro/rust.mdx @@ -1,15 +1,16 @@ -Options are passed to the `init()` function as tuple where the first argument is the DSN and the second the options: +Options are passed to the `init()` function as a `ClientOptions` value built with builder methods: Additionally, the `release_name` macro automatically generates the expected release based on the cargo metadata. ```rust -let _guard = sentry::init(("___PUBLIC_DSN___", sentry::ClientOptions { - release: sentry::release_name!(), - max_breadcrumbs: 50, - // 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, - debug: true, // <- this should only be used during development - ..Default::default() -})); +let _guard = sentry::init( + sentry::ClientOptions::new() + .dsn("___PUBLIC_DSN___") + .maybe_release(sentry::release_name!()) + .max_breadcrumbs(50) + // 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) + .debug(true), // <- this should only be used during development +); ``` diff --git a/platform-includes/configuration/sample-rate/rust.mdx b/platform-includes/configuration/sample-rate/rust.mdx index 4411478eabc149..40675bb418f4db 100644 --- a/platform-includes/configuration/sample-rate/rust.mdx +++ b/platform-includes/configuration/sample-rate/rust.mdx @@ -1,6 +1,3 @@ ```rust -let _guard = sentry::init(sentry::ClientOptions { - sample_rate: 1.0, - ..Default::default() -}); +let _guard = sentry::init(sentry::ClientOptions::new().sample_rate(1.0)); ``` diff --git a/platform-includes/getting-started-config/rust.mdx b/platform-includes/getting-started-config/rust.mdx index a1f4013edca237..28a601c1985354 100644 --- a/platform-includes/getting-started-config/rust.mdx +++ b/platform-includes/getting-started-config/rust.mdx @@ -1,11 +1,12 @@ `sentry.init()` will return you a guard that when freed, will prevent process exit until all events have been sent (within a timeout): ```rust -let _guard = sentry::init(("___PUBLIC_DSN___", sentry::ClientOptions { - 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, - ..Default::default() -})); +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), +); ``` diff --git a/platform-includes/metrics/options/rust.mdx b/platform-includes/metrics/options/rust.mdx index 206f9bc203ce9c..f53778be8bdc33 100644 --- a/platform-includes/metrics/options/rust.mdx +++ b/platform-includes/metrics/options/rust.mdx @@ -1,35 +1,31 @@ ### Filtering Metrics -Use [`before_send_metric`](https://docs.rs/sentry/latest/sentry/struct.ClientOptions.html#structfield.before_send_metric) to drop or update metrics before Sentry sends them. Return `None` to drop a metric. +Use [`before_send_metric`](https://docs.rs/sentry/latest/sentry/struct.ClientOptions.html#method.before_send_metric) to drop or update metrics before Sentry sends them. Return `None` to drop a metric. For example, to filter all metrics with the name `"debug.metric"`, you could use the following `before_send_metric`: ```rust {filename:main.rs} -let _guard = sentry::init(( - "___PUBLIC_DSN___", - sentry::ClientOptions { - before_send_metric: Some(std::sync::Arc::new(|metric| { +let _guard = sentry::init( + sentry::ClientOptions::new() + .dsn("___PUBLIC_DSN___") + .before_send_metric(|metric| { if metric.name == "debug.metric" { return None; } Some(metric) - })), - ..Default::default() - }, -)); + }), +); ``` ### Disabling Metrics -Metrics are enabled by default when the `sentry` crate is compiled with the `metrics` feature. To stop sending metrics, set [`enable_metrics: false`](https://docs.rs/sentry/latest/sentry/struct.ClientOptions.html#structfield.enable_metrics) in the [`ClientOptions`](https://docs.rs/sentry/latest/sentry/struct.ClientOptions.html). +Metrics are enabled by default when the `sentry` crate is compiled with the `metrics` feature. To stop sending metrics, call [`.enable_metrics(false)`](https://docs.rs/sentry/latest/sentry/struct.ClientOptions.html#method.enable_metrics) on [`ClientOptions`](https://docs.rs/sentry/latest/sentry/struct.ClientOptions.html). ```rust {filename:main.rs} -let _guard = sentry::init(( - "___PUBLIC_DSN___", - sentry::ClientOptions { - enable_metrics: false, - ..Default::default() - }, -)); +let _guard = sentry::init( + sentry::ClientOptions::new() + .dsn("___PUBLIC_DSN___") + .enable_metrics(false), +); ``` diff --git a/platform-includes/performance/configure-sample-rate/rust.mdx b/platform-includes/performance/configure-sample-rate/rust.mdx index 845c8653ab77fa..1d0f66477e5247 100644 --- a/platform-includes/performance/configure-sample-rate/rust.mdx +++ b/platform-includes/performance/configure-sample-rate/rust.mdx @@ -1,10 +1,8 @@ ```rust -let _guard = sentry::init(sentry::ClientOptions { - release: sentry::release_name!(), - // To set a uniform sample rate - traces_sample_rate: 0.2, - // The Rust SDK does not currently support `traces_sampler` - - ..Default::default() -}); +let _guard = sentry::init( + sentry::ClientOptions::new() + .maybe_release(sentry::release_name!()) + // To set a uniform sample rate + .traces_sample_rate(0.2), +); ``` diff --git a/platform-includes/performance/force-sampling-decision/rust.mdx b/platform-includes/performance/force-sampling-decision/rust.mdx index fac1080104471c..589dfd34c593f2 100644 --- a/platform-includes/performance/force-sampling-decision/rust.mdx +++ b/platform-includes/performance/force-sampling-decision/rust.mdx @@ -1,4 +1,8 @@ +An explicit decision set with `ctx.set_sampled(true)` is honored by the fixed-rate strategy from `.traces_sample_rate(...)` (including `0.0`). It is not applied automatically when using `.traces_sampler(...)`; that callback must read `ctx.sampled()` itself. With the default disabled strategy, the transaction is not sent even if you force a positive decision, so configure a non-disabled strategy first: + ```rust +let _guard = sentry::init(sentry::ClientOptions::new().traces_sample_rate(1.0)); + let mut ctx = sentry::TransactionContext::new("transaction", "op"); ctx.set_sampled(true); diff --git a/platform-includes/performance/traces-sample-rate/rust.mdx b/platform-includes/performance/traces-sample-rate/rust.mdx index 7a8266dde9945b..549836ae02c8da 100644 --- a/platform-includes/performance/traces-sample-rate/rust.mdx +++ b/platform-includes/performance/traces-sample-rate/rust.mdx @@ -1,7 +1,8 @@ ```rust -let _guard = sentry::init(sentry::ClientOptions { - release: sentry::release_name!(), - traces_sample_rate: 1.0, - ..Default::default() -}); +let _guard = sentry::init( + sentry::ClientOptions::new() + .dsn("___PUBLIC_DSN___") + .maybe_release(sentry::release_name!()) + .traces_sample_rate(1.0), +); ``` diff --git a/platform-includes/performance/uniform-sample-rate/rust.mdx b/platform-includes/performance/uniform-sample-rate/rust.mdx index b9b8f4408bddc6..ef1bd06b74a3ef 100644 --- a/platform-includes/performance/uniform-sample-rate/rust.mdx +++ b/platform-includes/performance/uniform-sample-rate/rust.mdx @@ -1,3 +1,5 @@ -To do this, set the option in your `sentry::init()` to a number between 0 and 1. With this option set, every transaction created will have that percentage chance of being sent to Sentry. For example, if you set to `0.2`, approximately 20% of your transactions will be recorded and sent. That looks like this: +To do this, call on your `ClientOptions` builder with a number between 0 and 1. With this option set, every transaction created will have that percentage chance of being sent to Sentry. For example, if you set to `0.2`, approximately 20% of your transactions will be recorded and sent. That looks like this: + +Tracing is disabled by default (`TracesSamplingStrategy::Disabled`). Calling `.traces_sample_rate(0.0)` is not the same as leaving tracing disabled: an explicit fixed rate of `0.0` can still honor an inherited parent sampling decision, while the default disabled strategy rejects the transaction even when a parent or explicit decision is positive. diff --git a/platform-includes/set-environment/rust.mdx b/platform-includes/set-environment/rust.mdx index 212ed250027e4a..9557118ad062b8 100644 --- a/platform-includes/set-environment/rust.mdx +++ b/platform-includes/set-environment/rust.mdx @@ -1,6 +1,3 @@ ```rust -sentry::init(sentry::ClientOptions { - environment: Some("production".into()), - ..Default::default() -}); +sentry::init(sentry::ClientOptions::new().environment("production")); ``` diff --git a/platform-includes/set-release/rust.mdx b/platform-includes/set-release/rust.mdx index e65c87a3ae930a..4c2d7513dafa91 100644 --- a/platform-includes/set-release/rust.mdx +++ b/platform-includes/set-release/rust.mdx @@ -3,10 +3,11 @@ The `release_name` macro automatically infers the release from the cargo metadat ```rust use sentry; -let _guard = sentry::init(("___PUBLIC_DSN___", sentry::ClientOptions { - release: Some("my-project-name@2.3.12".into()), - // OR automatically: - // release: sentry::release_name!(), - ..Default::default() -})); +let _guard = sentry::init( + sentry::ClientOptions::new() + .dsn("___PUBLIC_DSN___") + .release("my-project-name@2.3.12") + // OR automatically: + // .maybe_release(sentry::release_name!()), +); ```