Revert "chore: Remove start_span(sampled=X)"

This reverts commit 33d6f1b.

Author: sentrivana

MIGRATION_GUIDE.md

@@ -157,7 +157,6 @@ Looking to upgrade from Sentry SDK 2.x to 3.x? Here's a comprehensive list of wh
 - `Transport.capture_event` has been removed. Use `Transport.capture_envelope` instead.
 - Function transports are no longer supported. Subclass the `Transport` instead.
 - `start_transaction` (`start_span`) no longer takes the following arguments:
-  - `sampled`: use a `traces_sampler` to adjust the sampling rate
   - `trace_id`, `baggage`: use `continue_trace` for propagation from headers or environment variables
   - `same_process_as_parent`
   - `span_id`

sentry_sdk/integrations/opentelemetry/consts.py

@@ -33,3 +33,4 @@ class SentrySpanAttribute:
     NAME = "sentry.name"
     SOURCE = "sentry.source"
     CONTEXT = "sentry.context"
+    CUSTOM_SAMPLED = "sentry.custom_sampled"  # used for saving start_span(sampled=X)

sentry_sdk/integrations/opentelemetry/sampler.py

@@ -211,6 +211,26 @@ def should_sample(
             # We are the head SDK and we need to generate a new sample_rand
             sample_rand = cast(Decimal, _generate_sample_rand(str(trace_id), (0, 1)))
 
+        # Explicit sampled value provided at start_span
+        custom_sampled = cast(
+            "Optional[bool]", attributes.get(SentrySpanAttribute.CUSTOM_SAMPLED)
+        )
+        if custom_sampled is not None:
+            if is_root_span:
+                sample_rate = float(custom_sampled)
+                if sample_rate > 0:
+                    return sampled_result(
+                        parent_span_context, attributes, sample_rate=sample_rate
+                    )
+                else:
+                    return dropped_result(
+                        parent_span_context, attributes, sample_rate=sample_rate
+                    )
+            else:
+                logger.debug(
+                    f"[Tracing] Ignoring sampled param for non-root span {name}"
+                )
+
         # Check if there is a traces_sampler
         # Traces_sampler is responsible to check parent sampled to have full transactions.
         has_traces_sampler = callable(client.options.get("traces_sampler"))

sentry_sdk/tracing.py

@@ -282,6 +282,7 @@ def __init__(
         op=None,  # type: Optional[str]
         description=None,  # type: Optional[str]
         status=None,  # type: Optional[str]
+        sampled=None,  # type: Optional[bool]
         start_timestamp=None,  # type: Optional[Union[datetime, float]]
         origin=None,  # type: Optional[str]
         name=None,  # type: Optional[str]
@@ -332,6 +333,8 @@ def __init__(
                     attributes[SentrySpanAttribute.SOURCE] = source
                 if description is not None:
                     attributes[SentrySpanAttribute.DESCRIPTION] = description
+                if sampled is not None:
+                    attributes[SentrySpanAttribute.CUSTOM_SAMPLED] = sampled
 
                 parent_context = None
                 if parent_span is not None:

tests/integrations/sqlalchemy/test_sqlalchemy.py

@@ -111,7 +111,7 @@ class Address(Base):
     Session = sessionmaker(bind=engine)  # noqa: N806
     session = Session()
 
-    with sentry_sdk.start_span(name="test_transaction"):
+    with sentry_sdk.start_span(name="test_transaction", sampled=True):
         with session.begin_nested():
             session.query(Person).first()
 
@@ -185,7 +185,7 @@ class Address(Base):
     Session = sessionmaker(bind=engine)  # noqa: N806
     session = Session()
 
-    with sentry_sdk.start_span(name="test_transaction"):
+    with sentry_sdk.start_span(name="test_transaction", sampled=True):
         with session.begin_nested():
             session.query(Person).first()
 
@@ -304,7 +304,7 @@ def test_query_source_disabled(sentry_init, capture_events):
 
     events = capture_events()
 
-    with sentry_sdk.start_span(name="test_transaction"):
+    with sentry_sdk.start_span(name="test_transaction", sampled=True):
         Base = declarative_base()  # noqa: N806
 
         class Person(Base):
@@ -356,7 +356,7 @@ def test_query_source_enabled(sentry_init, capture_events, enable_db_query_sourc
 
     events = capture_events()
 
-    with sentry_sdk.start_span(name="test_transaction"):
+    with sentry_sdk.start_span(name="test_transaction", sampled=True):
         Base = declarative_base()  # noqa: N806
 
         class Person(Base):
@@ -403,7 +403,7 @@ def test_query_source(sentry_init, capture_events):
     )
     events = capture_events()
 
-    with sentry_sdk.start_span(name="test_transaction"):
+    with sentry_sdk.start_span(name="test_transaction", sampled=True):
         Base = declarative_base()  # noqa: N806
 
         class Person(Base):
@@ -473,7 +473,7 @@ def test_query_source_with_module_in_search_path(sentry_init, capture_events):
         query_first_model_from_session,
     )
 
-    with sentry_sdk.start_span(name="test_transaction"):
+    with sentry_sdk.start_span(name="test_transaction", sampled=True):
         Base = declarative_base()  # noqa: N806
 
         class Person(Base):
@@ -531,7 +531,7 @@ def test_no_query_source_if_duration_too_short(sentry_init, capture_events):
     )
     events = capture_events()
 
-    with sentry_sdk.start_span(name="test_transaction"):
+    with sentry_sdk.start_span(name="test_transaction", sampled=True):
         Base = declarative_base()  # noqa: N806
 
         class Person(Base):
@@ -599,7 +599,7 @@ def test_query_source_if_duration_over_threshold(sentry_init, capture_events):
     )
     events = capture_events()
 
-    with sentry_sdk.start_span(name="test_transaction"):
+    with sentry_sdk.start_span(name="test_transaction", sampled=True):
         Base = declarative_base()  # noqa: N806
 
         class Person(Base):

tests/tracing/test_sampling.py

@@ -23,6 +23,19 @@ def test_sampling_decided_only_for_root_spans(sentry_init):
         assert root_span2.sampled is not None
 
 
+@pytest.mark.parametrize("sampled", [True, False])
+def test_nested_span_sampling_override(sentry_init, sampled):
+    sentry_init(traces_sample_rate=1.0)
+
+    with start_span(name="outer", sampled=sampled) as outer_span:
+        assert outer_span.sampled is sampled
+        with start_span(name="inner", sampled=(not sampled)) as inner_span:
+            # won't work because the child span inherits the sampling decision
+            # from the parent
+            assert inner_span.sampled is sampled
+        assert outer_span.sampled is sampled
+
+
 def test_no_double_sampling(sentry_init, capture_events):
     # Transactions should not be subject to the global/error sample rate.
     # Only the traces_sample_rate should apply.
@@ -143,6 +156,19 @@ def test_ignores_inherited_sample_decision_when_traces_sampler_defined(
     assert span.sampled is not parent_sampling_decision
 
 
+@pytest.mark.parametrize("explicit_decision", [True, False])
+def test_traces_sampler_doesnt_overwrite_explicitly_passed_sampling_decision(
+    sentry_init, explicit_decision
+):
+    # make traces_sampler pick the opposite of the explicit decision, to prove
+    # that the explicit decision takes precedence
+    traces_sampler = mock.Mock(return_value=not explicit_decision)
+    sentry_init(traces_sampler=traces_sampler)
+
+    with start_span(name="dogpark", sampled=explicit_decision) as span:
+        assert span.sampled is explicit_decision
+
+
 @pytest.mark.parametrize("parent_sampling_decision", [True, False])
 def test_inherits_parent_sampling_decision_when_traces_sampler_undefined(
     sentry_init, parent_sampling_decision