Add active

Author: sentrivana

sentry_sdk/scope.py

@@ -1225,6 +1225,7 @@ def start_streamed_span(
         name: str,
         attributes: "Optional[Attributes]" = None,
         parent_span: "Optional[StreamedSpan]" = None,
+        active: bool = True,
         **kwargs: "Any",  # TODO[span-first]: remove, just for expediting seer testing
     ) -> "StreamedSpan":
         # TODO: rename to start_span once we drop the old API
@@ -1259,6 +1260,7 @@ def start_streamed_span(
             return StreamedSpan(
                 name=name,
                 attributes=attributes,
+                active=active,
                 scope=self,
                 segment=None,
                 trace_id=propagation_context.trace_id,
@@ -1277,6 +1279,7 @@ def start_streamed_span(
             return StreamedSpan(
                 name=name,
                 attributes=attributes,
+                active=active,
                 scope=self,
                 trace_id=parent_span.trace_id,
                 parent_span_id=parent_span.span_id,

sentry_sdk/traces.py

@@ -102,6 +102,7 @@ def start_span(
     name: str,
     attributes: "Optional[Attributes]" = None,
     parent_span: "Optional[StreamedSpan]" = None,
+    active: bool = True,
 ) -> "StreamedSpan":
     """
     Start a span.
@@ -136,19 +137,28 @@ def start_span(
 
     :param name: The name to identify this span by.
     :type name: str
+
     :param attributes: Key-value attributes to set on the span from the start.
         When provided via the `start_span()` function, these will also be
         accessible in the traces sampler.
     :type attributes: "Optional[Attributes]"
+
     :param parent_span: A span instance that the new span should be parented to.
         If not provided, the parent will be set to the currently active span,
         if any.
     :type parent_span: "Optional[StreamedSpan]"
+
+    :param active: Controls whether spans started while this span is running
+        will automatically become its children. That's the default behavior. If
+        you want to create a span that shouldn't have any children (unless
+        provided explicitly via the `parent_span` argument), set this to False.
+    :type active: bool
+
     :return: A span.
     :rtype: StreamedSpan
     """
     return sentry_sdk.get_current_scope().start_streamed_span(
-        name, attributes, parent_span
+        name, attributes, parent_span, active
     )
 
 
@@ -201,6 +211,7 @@ class StreamedSpan:
     __slots__ = (
         "_name",
         "_attributes",
+        "_active",
         "_span_id",
         "_trace_id",
         "parent_span_id",
@@ -227,6 +238,7 @@ def __init__(
         name: str,
         scope: "sentry_sdk.Scope",
         attributes: "Optional[Attributes]" = None,
+        active: bool = True,
         # TODO[span-first]: would be good to actually take this propagation
         # context stuff directly from the PropagationContext, but for that
         # we'd actually need to refactor PropagationContext to stay in sync
@@ -241,6 +253,7 @@ def __init__(
         last_valid_parent_id: "Optional[str]" = None,
     ) -> None:
         self._scope = scope
+        self._active = active
 
         self._name: str = name
         self._attributes: "Attributes" = {}
@@ -295,14 +308,16 @@ def __repr__(self) -> str:
             f"trace_id={self.trace_id}, "
             f"span_id={self.span_id}, "
             f"parent_span_id={self.parent_span_id}, "
-            f"sampled={self.sampled})>"
+            f"sampled={self.sampled}, "
+            f"active={self._active})>"
         )
 
     def __enter__(self) -> "StreamedSpan":
         scope = self._scope or sentry_sdk.get_current_scope()
-        old_span = scope.span
-        scope.span = self
-        self._context_manager_state = (scope, old_span)
+        if self._active:
+            old_span = scope.span
+            scope.span = self
+            self._context_manager_state = (scope, old_span)
 
         if self.is_segment():
             sampling_context = {
@@ -338,11 +353,15 @@ def __exit__(
         if value is not None and should_be_treated_as_error(ty, value):
             self.set_status(SpanStatus.ERROR)
 
-        with capture_internal_exceptions():
-            scope, old_span = self._context_manager_state
-            del self._context_manager_state
-            self._end(scope=scope)
-            scope.span = old_span
+        if self._active:
+            with capture_internal_exceptions():
+                scope, old_span = self._context_manager_state
+                del self._context_manager_state
+                scope.span = old_span
+        else:
+            scope = self._scope
+
+        self._end(scope=self._scope)
 
     def start(self) -> "StreamedSpan":
         """
@@ -761,6 +780,7 @@ def trace(
     *,
     name: "Optional[str]" = None,
     attributes: "Optional[dict[str, Any]]" = None,
+    active: bool = True,
 ) -> "Union[Callable[P, R], Callable[[Callable[P, R]], Callable[P, R]]]":
     """
     Decorator to start a span around a function call.
@@ -783,6 +803,12 @@ def trace(
         attributes provide additional context about the span's execution.
     :type attributes: dict[str, Any] or None
 
+    :param active: Controls whether spans started while this span is running
+        will automatically become its children. That's the default behavior. If
+        you want to create a span that shouldn't have any children (unless
+        provided explicitly via the `parent_span` argument), set this to False.
+    :type active: bool
+
     :returns: When used as ``@trace``, returns the decorated function. When used as
         ``@trace(...)`` with parameters, returns a decorator function.
     :rtype: Callable or decorator function
@@ -811,6 +837,7 @@ def make_db_query(sql):
     decorator = create_streaming_span_decorator(
         name=name,
         attributes=attributes,
+        active=active,
     )
 
     if func:

sentry_sdk/tracing_utils.py

@@ -1046,14 +1046,10 @@ def sync_wrapper(*args: "Any", **kwargs: "Any") -> "Any":
 def create_streaming_span_decorator(
     name: "Optional[str]" = None,
     attributes: "Optional[dict[str, Any]]" = None,
+    active: bool = True,
 ) -> "Any":
     """
-    Create a span decorator that can wrap both sync and async functions.
-
-    :param name: The name of the span.
-    :type name: str or None
-    :param attributes: Additional attributes to set on the span.
-    :type attributes: dict or None
+    Create a span creating decorator that can wrap both sync and async functions.
     """
     from sentry_sdk.scope import should_send_default_pii
 
@@ -1066,7 +1062,9 @@ def span_decorator(f: "Any") -> "Any":
         async def async_wrapper(*args: "Any", **kwargs: "Any") -> "Any":
             span_name = name or qualname_from_function(f) or ""
 
-            with start_streaming_span(name=span_name, attributes=attributes):
+            with start_streaming_span(
+                name=span_name, attributes=attributes, active=active
+            ):
                 result = await f(*args, **kwargs)
                 return result
 
@@ -1079,7 +1077,9 @@ async def async_wrapper(*args: "Any", **kwargs: "Any") -> "Any":
         def sync_wrapper(*args: "Any", **kwargs: "Any") -> "Any":
             span_name = name or qualname_from_function(f) or ""
 
-            with start_streaming_span(name=span_name, attributes=attributes):
+            with start_streaming_span(
+                name=span_name, attributes=attributes, active=active
+            ):
                 return f(*args, **kwargs)
 
         try:

tests/tracing/test_span_streaming.py

@@ -428,6 +428,43 @@ def traces_sampler(sampling_context):
     assert span_id_in_traces_sampler == segment.span_id
 
 
+def test_start_inactive_span(sentry_init, capture_envelopes):
+    sentry_init(
+        traces_sample_rate=1.0,
+        _experiments={"trace_lifecycle": "stream"},
+    )
+
+    events = capture_envelopes()
+
+    with sentry_sdk.traces.start_span(name="segment") as segment:
+        with sentry_sdk.traces.start_span(name="child1", active=False):
+            with sentry_sdk.traces.start_span(name="child2"):
+                # Should have segment as parent since child1 is inactive
+                pass
+
+    sentry_sdk.get_client().flush()
+    spans = envelopes_to_spans(events)
+
+    assert len(spans) == 3
+    child2, child1, segment = spans
+
+    assert segment["is_segment"] is True
+    assert segment["name"] == "segment"
+    assert segment["attributes"]["sentry.segment.name"] == "segment"
+
+    assert child1["is_segment"] is False
+    assert child1["name"] == "child1"
+    assert child1["attributes"]["sentry.segment.name"] == "segment"
+    assert child1["parent_span_id"] == segment["span_id"]
+    assert child1["trace_id"] == segment["trace_id"]
+
+    assert child2["is_segment"] is False
+    assert child2["name"] == "child2"
+    assert child2["attributes"]["sentry.segment.name"] == "segment"
+    assert child2["parent_span_id"] == segment["span_id"]
+    assert child2["trace_id"] == segment["trace_id"]
+
+
 def test_start_span_override_parent(sentry_init, capture_envelopes):
     sentry_init(
         traces_sample_rate=1.0,
@@ -685,6 +722,33 @@ def traced_function(): ...
     assert span["status"] == "ok"
 
 
+def test_trace_decorator_inactive(sentry_init, capture_envelopes):
+    sentry_init(
+        traces_sample_rate=1.0,
+        _experiments={"trace_lifecycle": "stream"},
+    )
+
+    events = capture_envelopes()
+
+    @sentry_sdk.traces.trace(name="outer", active=False)
+    def traced_function():
+        with sentry_sdk.traces.start_span(name="inner"):
+            ...
+
+    traced_function()
+
+    sentry_sdk.get_client().flush()
+    spans = envelopes_to_spans(events)
+
+    assert len(spans) == 2
+    (span1, span2) = spans
+
+    assert span1["name"] == "inner"
+    assert span1["parent_span_id"] != span2["span_id"]
+
+    assert span2["name"] == "outer"
+
+
 @minimum_python_38
 def test_trace_decorator_async(sentry_init, capture_envelopes):
     sentry_init(
@@ -737,6 +801,34 @@ async def traced_function(): ...
     assert span["status"] == "ok"
 
 
+@minimum_python_38
+def test_trace_decorator_async_inactive(sentry_init, capture_envelopes):
+    sentry_init(
+        traces_sample_rate=1.0,
+        _experiments={"trace_lifecycle": "stream"},
+    )
+
+    events = capture_envelopes()
+
+    @sentry_sdk.traces.trace(name="outer", active=False)
+    async def traced_function():
+        with sentry_sdk.traces.start_span(name="inner"):
+            ...
+
+    asyncio.run(traced_function())
+
+    sentry_sdk.get_client().flush()
+    spans = envelopes_to_spans(events)
+
+    assert len(spans) == 2
+    (span1, span2) = spans
+
+    assert span1["name"] == "inner"
+    assert span1["parent_span_id"] != span2["span_id"]
+
+    assert span2["name"] == "outer"
+
+
 def test_set_span_status(sentry_init, capture_envelopes):
     sentry_init(
         traces_sample_rate=1.0,