getsentry · dingsdax · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
diff --git 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)
 
+<Alert level="warning" title="Tail-Based Sampling Interaction">
+
+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`
+
+</Alert>
+
 The following SDKs support the `propagateTraceparent` option:
 
 <div style={{display: 'grid', gridTemplateColumns: '1fr 1fr 1fr', gap: '1.5rem'}}>

diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx
@@ -335,6 +335,8 @@ If <PlatformIdentifier name="tracePropagationTargets" /> 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.
 
+<Include name="platforms/configuration/options/propagate-traceparent-tail-sampling.mdx" />
+
 </SdkOption>
 
 <SdkOption name="traceOptionsRequests" type="bool" defaultValue="true">

diff --git 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 <PlatformIdentifier name="tracePropagationTargets" /> to control which requests the `traceparent` header is attached to.
 
+<Include name="platforms/configuration/options/propagate-traceparent-tail-sampling.mdx" />
+
 </SdkOption>
 
 <SdkOption name="enablePersistingTracesWhenCrashing" type="bool" defaultValue="false" availableSince="8.41.0">

diff --git a/docs/platforms/dart/guides/flutter/configuration/options.mdx b/docs/platforms/dart/guides/flutter/configuration/options.mdx
@@ -272,6 +272,8 @@ If <PlatformIdentifier name="tracePropagationTargets" /> 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.
 
+<Include name="platforms/configuration/options/propagate-traceparent-tail-sampling.mdx" />
+
 </SdkOption>
 
 ## Experimental Features

diff --git 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.
 
+<Include name="platforms/configuration/options/propagate-traceparent-tail-sampling.mdx" />
+
 </SdkOption>
 
 <SdkOption name="StrictTraceContinuation" type="bool" defaultValue="false">

diff --git a/docs/platforms/java/common/configuration/options.mdx b/docs/platforms/java/common/configuration/options.mdx
@@ -289,6 +289,8 @@ If <PlatformIdentifier name="tracePropagationTargets" /> 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.
 
+<Include name="platforms/configuration/options/propagate-traceparent-tail-sampling.mdx" />
+
 </SdkOption>
 
 <SdkOption name="traceOptionsRequests" type="boolean" defaultValue="true">

diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx
@@ -600,6 +600,8 @@ See <PlatformLink to="/tracing/distributed-tracing/dealing-with-cors-issues/">De
 
 </PlatformSection>
 
+<Include name="platforms/configuration/options/propagate-traceparent-tail-sampling.mdx" />
+
 </SdkOption>
 
 <SdkOption name="streamGenAiSpans" type='boolean' defaultValue='false' availableSince='10.53.0'>

diff --git 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/).
 
+<Include name="platforms/configuration/options/propagate-traceparent-tail-sampling.mdx" />
+
 </SdkOption>
 
 <SdkOption name="send_client_reports" type="bool" defaultValue="true" availableSince="0.13.6">

diff --git a/docs/platforms/react-native/configuration/options.mdx b/docs/platforms/react-native/configuration/options.mdx
@@ -322,6 +322,8 @@ If <PlatformIdentifier name="tracePropagationTargets" /> 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.
 
+<Include name="platforms/configuration/options/propagate-traceparent-tail-sampling.mdx" />
+
 </SdkOption>
 
 ## Experimental Features

diff --git a/includes/platforms/configuration/options/propagate-traceparent-tail-sampling.mdx 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.
Original file line number	Diff line number	Diff line change
		@@ -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.