From 3861fa57b99a9adbc452a89e90f16f972547a6ef Mon Sep 17 00:00:00 2001
From: Daniel Szoke <daniel.szoke@sentry.io>
Date: Wed, 12 Aug 2026 07:37:30 +0200
Subject: [PATCH] chore(core): Deprecate `is_sampled` methods

Deprecate the `is_sampled` methods on `Transaction`, `Span`, and `TransactionOrSpan` because these methods no longer faithfully represent the sampling state of these objects now that the SDK can properly represent the tracing-disabled state. This will be even more true after the follow up PR #1286 is merged; that's because that PR changes these struct's internal `sampled` representation to accurately represent the disabled-tracing states.

This PR also removes `is_sampled` assertions from the trace continuation tests. These assertions are not needed because the tests' purpose is to check trace continuation, not sampling decision propagation. These `is_sampled` checks should probably never have been added there.

We are not adding a replacement for `is_sampled` because a review of code in the `getsentry` org and public GitHub repos did not reveal any usecases of `is_sampled` that could not be replaced with another reasonable existing alternative, e.g. the functions that return the trace propagation headers. In `getsentry`, no usages of these methods could be found outside the SDK itself.
---
 sentry-core/src/performance/mod.rs      | 47 +++++++++++++++++++++++--
 sentry-core/tests/trace_continuation.rs |  2 --
 2 files changed, 45 insertions(+), 4 deletions(-)

diff --git a/sentry-core/src/performance/mod.rs b/sentry-core/src/performance/mod.rs
index 090b5902..390c6081 100644
--- a/sentry-core/src/performance/mod.rs
+++ b/sentry-core/src/performance/mod.rs
@@ -564,10 +564,30 @@ impl TransactionOrSpan {
     }
 
     /// Get the sampling decision for this Transaction/Span.
+    ///
+    /// The returned `bool` does not fully represent the sampling state of this
+    /// Transaction/Span. Although `true` reliably indicates that the
+    /// Transaction/Span is sampled, a value of `false` can mean either that the
+    /// Transaction/Span is not sampled, or that tracing is disabled and the
+    /// sampling decision is deferred. This method therefore should no longer be
+    /// used, especially not for trace continuation purposes.
+    ///
+    /// For trace propagation, use [`Self::iter_headers`] or
+    /// [`crate::Scope::iter_trace_propagation_headers`] instead, to ensure
+    /// correct results.
+    #[deprecated = "the returned value may not accurately represent the sampling decision"]
     pub fn is_sampled(&self) -> bool {
         match self {
-            TransactionOrSpan::Transaction(transaction) => transaction.is_sampled(),
-            TransactionOrSpan::Span(span) => span.is_sampled(),
+            TransactionOrSpan::Transaction(transaction) =>
+            {
+                #[expect(deprecated)]
+                transaction.is_sampled()
+            }
+            TransactionOrSpan::Span(span) =>
+            {
+                #[expect(deprecated)]
+                span.is_sampled()
+            }
         }
     }
 
@@ -930,6 +950,18 @@ impl Transaction {
     }
 
     /// Get the sampling decision for this Transaction.
+    ///
+    /// The returned `bool` does not fully represent the Transaction's sampling
+    /// state. Although `true` reliably indicates that the Transaction is
+    /// sampled, a value of `false` can mean either that the Transaction is not
+    /// sampled, or that tracing is disabled and the sampling decision is
+    /// deferred. This method therefore should no longer be used, especially not
+    /// for trace continuation purposes.
+    ///
+    /// For trace propagation, use [`Self::iter_headers`] or
+    /// [`crate::Scope::iter_trace_propagation_headers`] instead, to ensure
+    /// correct results.
+    #[deprecated = "the returned value may not accurately represent the sampling decision"]
     pub fn is_sampled(&self) -> bool {
         self.inner.lock().unwrap().sampled
     }
@@ -1214,6 +1246,17 @@ impl Span {
     }
 
     /// Get the sampling decision for this Span.
+    ///
+    /// The returned `bool` does not fully represent the Span's sampling state.
+    /// Although `true` reliably indicates that the Span is sampled, a value of
+    /// `false` can mean either that the Span is not sampled, or that tracing is
+    /// disabled and the sampling decision is deferred. This method therefore
+    /// should no longer be used, especially not for trace continuation purposes.
+    ///
+    /// For trace propagation, use [`Self::iter_headers`] or
+    /// [`crate::Scope::iter_trace_propagation_headers`] instead, to ensure
+    /// correct results.
+    #[deprecated = "the returned value may not accurately represent the sampling decision"]
     pub fn is_sampled(&self) -> bool {
         self.sampled
     }
diff --git a/sentry-core/tests/trace_continuation.rs b/sentry-core/tests/trace_continuation.rs
index 78962c6a..ea7a5d81 100644
--- a/sentry-core/tests/trace_continuation.rs
+++ b/sentry-core/tests/trace_continuation.rs
@@ -71,7 +71,6 @@ impl TraceContinuationScenario {
         let context = self.transaction.get_trace_context();
         assert_eq!(context.trace_id, self.incoming_trace_id);
         assert_eq!(context.parent_span_id, Some(self.incoming_parent_span_id));
-        assert!(self.transaction.is_sampled());
     }
 
     /// Asserts that the transaction rejected the incoming trace and parent sampling.
@@ -79,7 +78,6 @@ impl TraceContinuationScenario {
         let context = self.transaction.get_trace_context();
         assert_ne!(context.trace_id, self.incoming_trace_id);
         assert_eq!(context.parent_span_id, None);
-        assert!(!self.transaction.is_sampled());
     }
 }