[v9] Encourage using inheritOrSampleWith for tracesSampler in js (#12544)

Author: lforst

docs/platforms/javascript/common/configuration/sampling.mdx

@@ -42,8 +42,8 @@ The Sentry SDKs have two configuration options to control the volume of transact
 
 2. Sampling function (<PlatformIdentifier name="traces-sampler" />) which:
    - Samples different transactions at different rates
-   - <PlatformLink to="/configuration/filtering/">Filters</PlatformLink> out some
-     transactions entirely
+   - <PlatformLink to="/configuration/filtering/">Filters</PlatformLink> out
+     some transactions entirely
    - Modifies default [precedence](#precedence) and [inheritance](#inheritance) behavior
 
 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.
@@ -98,7 +98,6 @@ There are multiple ways for a transaction to end up with a sampling decision.
 
 When there's the potential for more than one of these to come into play, the following precedence 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.

platform-includes/performance/sampling-function-intro/javascript.mdx

@@ -3,3 +3,4 @@ To use the sampling function, set the <PlatformIdentifier name="traces-sampler"
 <PlatformContent includePath="performance/traces-sampler-as-sampler" />
 
 For convenience, the function can also return a boolean. Returning `true` is equivalent to returning `1`, and will guarantee the transaction will be sent to Sentry. Returning `false` is equivalent to returning `0` and will guarantee the transaction will **not** be sent to Sentry.
+Note that sampling decisions will be inherited for downstream services if you have set up distributed tracing.

platform-includes/performance/traces-sampler-as-sampler/javascript.mdx

@@ -5,17 +5,18 @@ interface SamplingContext {
   name: string;
   // Initial attributes of the span
   attributes: SpanAttributes | undefined;
-  // If the parent span was sampled - undefined if there is no parent span
+  // If the parent span was sampled - undefined if there is no incoming trace
   parentSampled: boolean | undefined;
+  // Sample rate that is coming from the incoming trace - undefined if there is no incoming trace
+  parentSampleRate: number | undefined;
 }
 
 Sentry.init({
   // ...
 
-  tracesSampler: ({ name, attributes, parentSampled }) => {
+  tracesSampler: ({ name, attributes, inheritOrSampleWith }) => {
     // Do not sample health checks ever
     if (name.includes("healthcheck")) {
-      // Drop this completely by setting its sample rate to 0%
       return 0;
     }
 
@@ -29,13 +30,17 @@ Sentry.init({
       return 0.01;
     }
 
-    // Continue trace decision, if there is any parentSampled information
-    if (typeof parentSampled === "boolean") {
-      return parentSampled;
-    }
-
-    // Else, use default sample rate
-    return 0.5;
+    // Otherwise, inherit the sample sampling decision of the incoming trace, or use a fallback sampling rate.
+    return inheritOrSampleWith(0.5);
   },
 });
 ```
+
+<Alert title="parentSampleRate">
+
+The `inheritOrSampleWith` sampling context utility was introduced in version 9 of the SDK.
+To inherit sampling decisions in earlier versions of the SDK, use the `parentSampled` sampling context.
+
+Going forward, using `inheritOrSampleWith()` is strongly encouraged over using `parentSampled`, because it allows for deterministic sampling and metric extrapolation for downstream traces.
+
+</Alert>