fix(sampling): Attribute backpressure as unsampling reason more accurately (#6445)

### Description

#### Context

If backpressure handling is active, it lowers the effective sample rate.

There are different outcomes for when a span is unsampled due to
`sample_rate` or `backpressure`.

#### Behavior

Before this change, if under backpressure, we'd only report
`backpressure` as the reason for unsampling if the monitor lowered the
effective sample rate to a falsy value. Which only covers a small
portion of unsample decisions made due to backpressure. The rest would
be reported as a generic `sample_rate` drop, potentially leading to
confusing reporting. If someone e.g. has a `traces_sample_rate` of
`1.0`, they might see spans being dropped because of `sample_rate`,
which is hard to justify.

In this PR, we try to do a better job at determining whether
backpressure was actually the reason a span was dropped and emit the
corresponding outcome.

The idea is, for an unsampled span:
- if `sample_rand` would've been higher than the original,
non-backpressure `sample_rate`, the span would've been unsampled
regardless of backpressure handling, so the outcome should be
`sample_rate`
- if `sample_rand` actually would've been lower than the original
`sample_rate` had the `sample_rate` not been lowered, the span would've
been sampled. In that case backpressure handling is the direct cause and
the outcome should be `backpressure`

#### Issues
<!--
* resolves: #1234
* resolves: LIN-1234
-->

#### Reminders
- Please add tests to validate your changes, and lint your code using
`uv run ruff`.
- Add GH Issue ID _&_ Linear ID (if applicable)
- PR title should use [conventional
commit](https://develop.sentry.dev/engineering-practices/commit-messages/#type)
style (`feat:`, `fix:`, `ref:`, `meta:`)
- For external contributors:
[CONTRIBUTING.md](https://github.com/getsentry/sentry-python/blob/master/CONTRIBUTING.md),
[Sentry SDK development docs](https://develop.sentry.dev/sdk/), [Discord
community](https://discord.gg/Ww9hbqr)

Author: sentrivana

sentry_sdk/tracing_utils.py

@@ -1577,23 +1577,39 @@ def _make_sampling_decision(
         return False, 0.0, None, "sample_rate"
 
     # Adjust sample rate if we're under backpressure
+    sample_rate_before_backpressure = sample_rate
     if client.monitor:
         sample_rate /= 2**client.monitor.downsample_factor
 
         if not sample_rate:
             logger.debug(f"[Tracing] Discarding {name} because backpressure")
             return False, 0.0, None, "backpressure"
 
+    # Make the actual decision
     sampled = sample_rand < sample_rate
 
     if sampled:
         logger.debug(f"[Tracing] Starting {name}")
         outcome = None
+
     else:
-        logger.debug(
-            f"[Tracing] Discarding {name} because it's not included in the random sample (sampling rate = {sample_rate})"
-        )
-        outcome = "sample_rate"
+        # Determine why exactly the span will not be sampled. If we've lowered
+        # the effective sample_rate because of backpressure, check whether the
+        # span would've been sampled if backpressure wasn't active. If that's the
+        # case, backpressure is the actual reason, otherwise just pure sampling
+        # rate.
+        if (
+            sample_rate_before_backpressure != sample_rate
+            and sample_rand < sample_rate_before_backpressure
+        ):
+            logger.debug(f"[Tracing] Discarding {name} because backpressure")
+            outcome = "backpressure"
+
+        else:
+            logger.debug(
+                f"[Tracing] Discarding {name} because it's not included in the random sample (sampling rate = {sample_rate})"
+            )
+            outcome = "sample_rate"
 
     return sampled, sample_rate, sample_rand, outcome
 

tests/tracing/test_span_streaming.py

@@ -754,6 +754,69 @@ def test_continue_trace_unsampled(sentry_init, capture_items):
     assert len(spans) == 0
 
 
+@pytest.mark.parametrize(
+    ("sample_rand", "expected_sampled", "expected_outcome"),
+    [
+        ("0.100000", True, None),
+        ("0.250000", False, "backpressure"),
+        ("0.300000", False, "backpressure"),
+        ("0.500000", False, "sample_rate"),
+        ("0.700000", False, "sample_rate"),
+    ],
+)
+def test_backpressure_outcome(
+    sentry_init,
+    capture_items,
+    capture_record_lost_event_calls,
+    sample_rand,
+    expected_sampled,
+    expected_outcome,
+):
+    sentry_init(
+        traces_sample_rate=0.5,
+        enable_backpressure_handling=True,
+        _experiments={"trace_lifecycle": "stream"},
+    )
+
+    items = capture_items("span")
+    record_lost_event_calls = capture_record_lost_event_calls()
+
+    client = sentry_sdk.get_client()
+    client.monitor._downsample_factor = 1
+
+    trace_id = "0af7651916cd43dd8448eb211c80319c"
+    parent_span_id = "b7ad6b7169203331"
+
+    sentry_sdk.traces.continue_trace(
+        {
+            "sentry-trace": f"{trace_id}-{parent_span_id}",
+            "baggage": f"sentry-trace_id={trace_id},sentry-sample_rand={sample_rand}",
+        }
+    )
+
+    with sentry_sdk.traces.start_span(name="span") as span:
+        pass
+
+    sentry_sdk.get_client().flush()
+    spans = [item.payload for item in items]
+
+    # Original traces_sample_rate is 0.5, downsampled sample rate is 0.25, so:
+    # - sample_rand < 0.25 -> sampled
+    # - 0.25 < sample_rand < 0.5 -> unsampled because of backpressure (would've been sampled if no backpressure)
+    # - 0.5 < sample_rand -> unsampled because of sampling rate
+
+    assert span.sampled is expected_sampled
+
+    if expected_sampled:
+        assert len(spans) == 1
+        assert not record_lost_event_calls
+    else:
+        assert len(spans) == 0
+        assert record_lost_event_calls == [
+            (expected_outcome, "span", None, 1),
+        ]
+
+
 def test_unsampled_spans_produce_client_report(
     sentry_init, capture_items, capture_record_lost_event_calls
 ):