ref: Allow to start and finish StreamedSpans (9)

[sentrivana]

Description

This PR adds logic for starting and finishing spans, both via a context manager with start_span(...), as well as directly with span = start_span(...) and span.end().

Summary

• Added internal _start() and _end() functions that handle the starting and ending logic.
  • _start() handles keeping track of what was called context_manager_state on old Spans, i.e., remembering which span was set on the scope before this span so that it can be restored once this span is over.
  • _end() handles restoring the old span, setting the end timestamp, adding final attributes on it, and queueing it in the span batcher.
• Added __enter__ and __exit__ methods on both StreamedSpan and NoOpStreamedSpan. These call the internal methods above, with __exit__ additionally setting the span status to error if it encountered one.
• Added a new span.end() public function that allows to set an optional end_timestamp. If provided, it sets it and calls _end() internally.
• There is a span.finish() too, which is deprecated from the get go, just to make the migration to span first a bit easier (since the method is called finish() on legacy spans).

Issues

Reminders

• Please add tests to validate your changes, and lint your code using tox -e linters.
• Add GH Issue ID & Linear ID (if applicable)
• PR title should use conventional commit style (feat:, fix:, ref:, meta:)
• For external contributors: CONTRIBUTING.md, Sentry SDK development docs, Discord community

[sentrivana]

There is no scenario where a span that's already in the span batcher wouldn't have an end _timestamp, but mypy doesn't know that. 🤡

[sentrivana]

Anything related to _start_timestamp_monotonic_ns is just copy-pasted from the Span implementation

[sentrivana]

Just here for compat reasons, to make the transition from the old API easier (very slightly).

[sentrivana]

_active basically controls whether a span will be set on the scope, so if it's False, we don't need to keep track of the old parent span to restore it later, because we're never replacing it.

[sentrivana]

Unlike the main span class, no-op spans don't have an active flag. The user cannot control whether a no-op span will be set on the scope; the SDK does this internally, and it uses the _scope attribute to remember the decision. In the case of normal spans, the _scope attribute plays a different role: they all need a scope, regardless of whether they'll actually be set on it or not, because they will be captured using that scope in either case.

Coming back to no-op spans, the decision whether to set them on the scope or not is tightly coupled to how we want ignore_spans to work (coming in a future PR). Basically, if a segment/root span would be ignored, all of its children should be as well. That's easiest to accomplish if we actually set the root no-op span on the scope. On the other hand, if a non-root span is ignored, it's not set on scope, so that any children spans effectively use the last not ignored span that's set on the scope as parent.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: NoOpStreamedSpan._end() missing double-end guard causes error logs
  • Added a double-end guard in NoOpStreamedSpan._end() that returns when _previous_span_on_scope is already removed, preventing spurious internal error logging on repeated end() calls.

Or push these changes by commenting:

@cursor push 048194f3a9

Preview (048194f3a9)

diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py
--- a/sentry_sdk/traces.py
+++ b/sentry_sdk/traces.py
@@ -448,7 +448,7 @@
         self._previous_span_on_scope = old_span
 
     def _end(self, end_timestamp: "Optional[Union[float, datetime]]" = None) -> None:
-        if self._scope is None:
+        if self._scope is None or not hasattr(self, "_previous_span_on_scope"):
             return
 
         with capture_internal_exceptions():

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Status mutated on already-queued span after early end

Low Severity

When a user calls span.end() inside a with start_span() block and then an exception occurs, __exit__ sets self.status = SpanStatus.ERROR on the already-queued span object before _end() returns early due to its _timestamp is not None guard. Since the batcher holds a reference to the span, the status mutation retroactively changes the queued span from OK to ERROR, even though the span was explicitly finished before the exception happened.

Additional Locations (1)

• sentry_sdk/traces.py#L299-L303