From f44830ecdd20c53fafcbba047026e504f134c6cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Fri, 5 Jun 2026 16:34:25 +0200 Subject: [PATCH] docs(otlp): Add tail-based sampling warning for propagateTraceparent When propagateTraceparent is enabled, the frontend SDK's sampling decision propagates via the traceparent header. OTel backends using the default parentbased_* sampler honor that decision, silently bypassing collector tail-based sampling. Add a warning Alert to the Sentry with OTel concepts page explaining this interaction and recommending OTEL_TRACES_SAMPLER=always_on as the fix. Add a cross-reference note to the propagateTraceparent SdkOption block across all 8 platform options pages (JS, Android, Java, React Native, Flutter, Go, Apple, Native) via a shared include partial. Co-Authored-By: Claude --- docs/concepts/otlp/sentry-with-otel.mdx | 10 ++++++++++ docs/platforms/android/configuration/options.mdx | 2 ++ docs/platforms/apple/common/configuration/options.mdx | 2 ++ .../dart/guides/flutter/configuration/options.mdx | 2 ++ docs/platforms/go/common/configuration/options.mdx | 2 ++ docs/platforms/java/common/configuration/options.mdx | 2 ++ .../javascript/common/configuration/options.mdx | 2 ++ docs/platforms/native/common/configuration/options.mdx | 2 ++ docs/platforms/react-native/configuration/options.mdx | 2 ++ .../options/propagate-traceparent-tail-sampling.mdx | 1 + 10 files changed, 27 insertions(+) create mode 100644 includes/platforms/configuration/options/propagate-traceparent-tail-sampling.mdx diff --git a/docs/concepts/otlp/sentry-with-otel.mdx b/docs/concepts/otlp/sentry-with-otel.mdx index 9e7b04ee4acc57..cc20c1c4bdec13 100644 --- a/docs/concepts/otlp/sentry-with-otel.mdx +++ b/docs/concepts/otlp/sentry-with-otel.mdx @@ -16,6 +16,16 @@ This gives you end-to-end visibility: ![Sentry Distributed Trace](./img/sentry-distributed-trace.png) + + +When `propagateTraceparent` is enabled, the frontend SDK encodes its sampling decision in the `traceparent` header. If your OTel backend uses a `parentbased_*` sampler (the default is `parentbased_always_on`), it honors that decision and skips your collector's tail-based sampler entirely. + +To preserve tail-based sampling, set your backend's sampler to `always_on` so all spans reach the collector for evaluation: + +`OTEL_TRACES_SAMPLER=always_on` + + + The following SDKs support the `propagateTraceparent` option:
diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx index 656f5dff93aabb..028287290ae315 100644 --- a/docs/platforms/android/configuration/options.mdx +++ b/docs/platforms/android/configuration/options.mdx @@ -335,6 +335,8 @@ If is not provided, trace Controls whether the SDK should propagate the W3C `traceparent` HTTP header alongside the `sentry-trace` and `baggage` headers for outgoing HTTP requests. + + diff --git a/docs/platforms/apple/common/configuration/options.mdx b/docs/platforms/apple/common/configuration/options.mdx index dc0b7645412b42..c94053c693565b 100644 --- a/docs/platforms/apple/common/configuration/options.mdx +++ b/docs/platforms/apple/common/configuration/options.mdx @@ -667,6 +667,8 @@ Set this option to `true` if your backend services are instrumented with a W3C T Use to control which requests the `traceparent` header is attached to. + + diff --git a/docs/platforms/dart/guides/flutter/configuration/options.mdx b/docs/platforms/dart/guides/flutter/configuration/options.mdx index fe969649980f2e..a9153c83d913e9 100644 --- a/docs/platforms/dart/guides/flutter/configuration/options.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/options.mdx @@ -272,6 +272,8 @@ If is not provided, trace Controls whether the SDK should propagate the W3C `traceparent` HTTP header alongside the `sentry-trace` and `baggage` headers for outgoing HTTP requests. + + ## Experimental Features diff --git a/docs/platforms/go/common/configuration/options.mdx b/docs/platforms/go/common/configuration/options.mdx index 6d36c808466ad7..a26b24a2cd97b8 100644 --- a/docs/platforms/go/common/configuration/options.mdx +++ b/docs/platforms/go/common/configuration/options.mdx @@ -194,6 +194,8 @@ Controls which URLs will have trace propagation enabled. Does not support regex When set to `true`, the W3C Trace Context HTTP `traceparent` header is propagated on outgoing HTTP requests. + + diff --git a/docs/platforms/java/common/configuration/options.mdx b/docs/platforms/java/common/configuration/options.mdx index 826e5d59c491ce..1876eea6bbdef5 100644 --- a/docs/platforms/java/common/configuration/options.mdx +++ b/docs/platforms/java/common/configuration/options.mdx @@ -289,6 +289,8 @@ If is not provided, trace Controls whether the SDK should propagate the W3C `traceparent` HTTP header alongside the `sentry-trace` and `baggage` headers for distributed tracing. This option defaults to `false` and is available starting from SDK version 8.22.0. + + diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index cee6e0d4f9a505..34b2c65e4e320d 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -600,6 +600,8 @@ See De + + diff --git a/docs/platforms/native/common/configuration/options.mdx b/docs/platforms/native/common/configuration/options.mdx index 7accebb88c118a..7fc15c92318188 100644 --- a/docs/platforms/native/common/configuration/options.mdx +++ b/docs/platforms/native/common/configuration/options.mdx @@ -82,6 +82,8 @@ Controls how much memory the `native` backend captures in minidumps. This settin Controls whether the SDK should propagate the W3C `traceparent` HTTP header alongside the `sentry-trace` header for [distributed tracing](https://docs.sentry.io/platforms/native/tracing/trace-propagation/custom-instrumentation/). + + diff --git a/docs/platforms/react-native/configuration/options.mdx b/docs/platforms/react-native/configuration/options.mdx index c1058bba9bb600..c0c523a31c3f8e 100644 --- a/docs/platforms/react-native/configuration/options.mdx +++ b/docs/platforms/react-native/configuration/options.mdx @@ -322,6 +322,8 @@ If is not provided, trace Controls whether the SDK should propagate the W3C `traceparent` HTTP header alongside the `sentry-trace` and `baggage` headers for outgoing HTTP requests. + + ## Experimental Features diff --git a/includes/platforms/configuration/options/propagate-traceparent-tail-sampling.mdx b/includes/platforms/configuration/options/propagate-traceparent-tail-sampling.mdx new file mode 100644 index 00000000000000..005828048123c8 --- /dev/null +++ b/includes/platforms/configuration/options/propagate-traceparent-tail-sampling.mdx @@ -0,0 +1 @@ +If your backend uses an OTel collector with tail-based sampling, see [Sentry with OTel](/concepts/otlp/sentry-with-otel/) for an important interaction with this option. \ No newline at end of file