docs(rust): Document new Rust configuration

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.
+
 <TableOfContents ignoreIds={["available-options"]} />
 
 ## 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 <SandboxLink scenario="releases">sandbox</SandboxLink>.
 
+Use `.release(...)` with a string, or `.maybe_release(sentry::release_name!())` when using the optional value returned by the release macro.
+
 </SdkOption>
 
 <SdkOption name="environment" type='string' envVar='SENTRY_ENVIRONMENT'>
@@ -131,7 +135,9 @@ The list of default integrations depends on the feature flags of the `sentry` cr
 
 <SdkOption name="sample_rate" type='f32' defaultValue='1.0'>
 
-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.
 
 </SdkOption>
 
@@ -145,15 +151,21 @@ By the time `before_send` is executed, all scope data has already been applied t
 
 ## Tracing Options
 
-<SdkOption name="traces_sample_rate" type='f32' defaultValue='0.0'>
+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.
+<SdkOption name="traces_sample_rate" type='f32'>
+
+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.
 
 </SdkOption>
 
 <SdkOption name="traces_sampler" type='Fn'>
 
-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.
 
 </SdkOption>
 

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

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 <PlatformIdentifier name="sample-rate" /> 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 <PlatformIdentifier name="sample-rate" /> 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:
 
 <PlatformContent includePath="configuration/sample-rate" />
 
@@ -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 (<PlatformIdentifier name="traces-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 (<PlatformIdentifier name="traces-sampler" />) which:
+   - Selects `TracesSamplingStrategy::Function`
    - Samples different transactions at different rates
    - <PlatformLink to="/configuration/filtering/">Filters</PlatformLink> 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.
 
-<Alert>
-
-Sampling functions (<PlatformIdentifier name="traces-sampler" />) are currently not supported by this platform.
-
-</Alert>
+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 <PlatformLink to="/tracing/trace-propagation/">Distributed Tracing</PlatformLink> 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 <PlatformIdentifier name="traces-sampler" /> 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.
-
-<PlatformContent includePath="performance/always-inherit-sampling-decision">
-
-In some SDKs, for convenience, the <PlatformIdentifier name="traces-sampler" /> 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:
 
-</PlatformContent>
+- `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 <PlatformIdentifier name="traces-sample-rate" /> rather than a <PlatformIdentifier name="traces-sampler" />, 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 <PlatformIdentifier name="traces-sample-rate" />
+- The default disabled traces sampling strategy
+- Random sampling according to a static sample rate set with <PlatformIdentifier name="traces-sample-rate" />
 - Random sampling according to a sample function rate returned by <PlatformIdentifier name="traces-sampler" />
 - Absolute decision (100% chance or 0% chance) returned by <PlatformIdentifier name="traces-sampler" />
 - If the transaction has a parent, inheriting its parent's sampling decision
-- Absolute decision passed to <PlatformIdentifier name="start-transaction" />
+- 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 <PlatformIdentifier name="start-transaction" />, that decision will be used, overriding everything else.
-1. If <PlatformIdentifier name="traces-sampler" /> 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 <PlatformIdentifier name="traces-sampler" /> is not defined, but there's a parent sampling decision, the parent sampling decision will be used.
-1. If <PlatformIdentifier name="traces-sampler" /> is not defined and there's no parent sampling decision, <PlatformIdentifier name="traces-sample-rate" /> 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.
 
 <Alert>
 

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

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 <PlatformIdentifier name="traces-sample-rate" /> option in your SDK config to a number between `0` and `1`. (For example, to send 20% of transactions, set <PlatformIdentifier name="traces-sample-rate" /> 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 <PlatformIdentifier name="traces-sampler" /> config option.
 
-The two options are meant to be mutually exclusive. If you set both, <PlatformIdentifier name="traces-sampler" /> 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.
 
 <PlatformContent includePath="performance/configure-sample-rate" />
 

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());

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.