From 946decc9ff9b9f057612f39a297b4df95a5ab0dd Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 12:08:24 +0100 Subject: [PATCH 01/23] ref: Remove flag storage from StreamedSpan --- sentry_sdk/traces.py | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index 531a06b1fd..e0235268f0 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -17,9 +17,6 @@ from sentry_sdk._types import Attributes, AttributeValue -FLAGS_CAPACITY = 10 - - class SpanStatus(str, Enum): OK = "ok" ERROR = "error" @@ -65,10 +62,10 @@ class StreamedSpan: """ A span holds timing information of a block of code. - Spans can have multiple child spans thus forming a span tree. + Spans can have multiple child spans, thus forming a span tree. - This is the Span First span implementation. The original transaction-based - span implementation lives in tracing.Span. + This is the Span First span implementation that streams spans. The original + transaction-based span implementation lives in tracing.Span. """ __slots__ = ( @@ -77,7 +74,6 @@ class StreamedSpan: "_span_id", "_trace_id", "_status", - "_flags", ) def __init__( @@ -99,8 +95,6 @@ def __init__( self.set_status(SpanStatus.OK) self.set_source(SegmentSource.CUSTOM) - self._flags: dict[str, bool] = {} - def get_attributes(self) -> "Attributes": return self._attributes @@ -143,10 +137,6 @@ def get_name(self) -> str: def set_name(self, name: str) -> None: self._name = name - def set_flag(self, flag: str, result: bool) -> None: - if len(self._flags) < FLAGS_CAPACITY: - self._flags[flag] = result - def set_op(self, op: str) -> None: self.set_attribute("sentry.op", op) From f3ee55c909ee080c6807f32fc5943e77b44fde20 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 12:12:51 +0100 Subject: [PATCH 02/23] ref: Tweak StreamedSpan interface --- sentry_sdk/traces.py | 53 ++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 29 deletions(-) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index e0235268f0..333a9a5c5f 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -92,8 +92,16 @@ def __init__( self._span_id: "Optional[str]" = None self._trace_id: "Optional[str]" = trace_id - self.set_status(SpanStatus.OK) - self.set_source(SegmentSource.CUSTOM) + self._status = SpanStatus.OK.value + self.set_attribute("sentry.span.source", SegmentSource.CUSTOM.value) + + def __repr__(self) -> str: + return ( + f"<{self.__class__.__name__}(" + f"name={self._name}, " + f"trace_id={self.trace_id}, " + f"span_id={self.span_id}>" + ) def get_attributes(self) -> "Attributes": return self._attributes @@ -111,44 +119,31 @@ def remove_attribute(self, key: str) -> None: except KeyError: pass - def get_status(self) -> "Union[SpanStatus, str]": - if self._status in {s.value for s in SpanStatus}: - return SpanStatus(self._status) - + @property + def status(self) -> "str": return self._status - def set_status(self, status: "Union[SpanStatus, str]") -> None: + @status.setter + def status(self, status: "Union[SpanStatus, str]") -> None: if isinstance(status, Enum): status = status.value - self._status = status - - def set_http_status(self, http_status: int) -> None: - self.set_attribute(SPANDATA.HTTP_STATUS_CODE, http_status) + if status not in {e.value for e in SpanStatus}: + logger.debug( + f'Unsupported span status {status}. Expected one of: "ok", "error"' + ) + return - if http_status >= 400: - self.set_status(SpanStatus.ERROR) - else: - self.set_status(SpanStatus.OK) + self._status = status - def get_name(self) -> str: + @property + def name(self) -> str: return self._name - def set_name(self, name: str) -> None: + @name.setter + def name(self, name: str) -> None: self._name = name - def set_op(self, op: str) -> None: - self.set_attribute("sentry.op", op) - - def set_origin(self, origin: str) -> None: - self.set_attribute("sentry.origin", origin) - - def set_source(self, source: "Union[str, SegmentSource]") -> None: - if isinstance(source, Enum): - source = source.value - - self.set_attribute("sentry.span.source", source) - @property def span_id(self) -> str: if not self._span_id: From 47ed910d32d99c66d2a142a21d8494aa02740492 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 12:21:15 +0100 Subject: [PATCH 03/23] Add missing logger --- sentry_sdk/traces.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index 333a9a5c5f..4a1ad8d396 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -10,7 +10,7 @@ from typing import TYPE_CHECKING from sentry_sdk.consts import SPANDATA -from sentry_sdk.utils import format_attribute +from sentry_sdk.utils import format_attribute, logger if TYPE_CHECKING: from typing import Optional, Union From 5023c76a6248ab91e23939e7225d093bcad41ac5 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 12:40:02 +0100 Subject: [PATCH 04/23] fixes --- sentry_sdk/traces.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index 4a1ad8d396..d733899e4b 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -9,7 +9,6 @@ from enum import Enum from typing import TYPE_CHECKING -from sentry_sdk.consts import SPANDATA from sentry_sdk.utils import format_attribute, logger if TYPE_CHECKING: @@ -100,7 +99,7 @@ def __repr__(self) -> str: f"<{self.__class__.__name__}(" f"name={self._name}, " f"trace_id={self.trace_id}, " - f"span_id={self.span_id}>" + f"span_id={self.span_id})>" ) def get_attributes(self) -> "Attributes": From 644544705c10cb26a5c238ff9475742eb7a132ee Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 12:40:34 +0100 Subject: [PATCH 05/23] ref: Add active to StreamedSpan --- sentry_sdk/traces.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index d733899e4b..768e658b5b 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -70,6 +70,7 @@ class StreamedSpan: __slots__ = ( "_name", "_attributes", + "_active", "_span_id", "_trace_id", "_status", @@ -80,9 +81,11 @@ def __init__( *, name: str, attributes: "Optional[Attributes]" = None, + active: bool = True, trace_id: "Optional[str]" = None, ): self._name: str = name + self._active: bool = active self._attributes: "Attributes" = {} if attributes: for attribute, value in attributes.items(): @@ -99,7 +102,8 @@ def __repr__(self) -> str: f"<{self.__class__.__name__}(" f"name={self._name}, " f"trace_id={self.trace_id}, " - f"span_id={self.span_id})>" + f"span_id={self.span_id}, " + f"active={self._active})>" ) def get_attributes(self) -> "Attributes": From 47e6211f473ebad9caf55762ce83dd3b73136a81 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 12:24:32 +0100 Subject: [PATCH 06/23] Add property --- sentry_sdk/traces.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index 768e658b5b..859bebdacd 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -147,6 +147,10 @@ def name(self) -> str: def name(self, name: str) -> None: self._name = name + @property + def active(self) -> bool: + return self._active + @property def span_id(self) -> str: if not self._span_id: From 1e7b694d9f1e9ac9d3ff9b86d20cb9d83178247a Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 12:33:20 +0100 Subject: [PATCH 07/23] ref: Add no-op streaming span class --- sentry_sdk/traces.py | 53 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index 859bebdacd..4f0807d007 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -164,3 +164,56 @@ def trace_id(self) -> str: self._trace_id = uuid.uuid4().hex return self._trace_id + + +class NoOpStreamedSpan(StreamedSpan): + __slots__ = ( + ) + + def __init__( + self, + ) -> None: + pass + + def __repr__(self) -> str: + return f"<{self.__class__.__name__}(sampled={self.sampled})>" + + def get_attributes(self) -> "Attributes": + return {} + + def set_attribute(self, key: str, value: "AttributeValue") -> None: + pass + + def set_attributes(self, attributes: "Attributes") -> None: + pass + + def remove_attribute(self, key: str) -> None: + pass + + @property + def status(self) -> "str": + return SpanStatus.OK.value + + @status.setter + def status(self, status: "Union[SpanStatus, str]") -> None: + pass + + @property + def name(self) -> str: + return "" + + @name.setter + def name(self, value: str) -> None: + pass + + @property + def active(self) -> bool: + return True + + @property + def span_id(self) -> str: + return "0000000000000000" + + @property + def trace_id(self) -> str: + return "00000000000000000000000000000000" From 80bfe5a2af99d568a51135a842c9398154d48751 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 12:37:30 +0100 Subject: [PATCH 08/23] Remove redundant stuff --- sentry_sdk/traces.py | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index 4f0807d007..e09d7191c3 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -167,17 +167,6 @@ def trace_id(self) -> str: class NoOpStreamedSpan(StreamedSpan): - __slots__ = ( - ) - - def __init__( - self, - ) -> None: - pass - - def __repr__(self) -> str: - return f"<{self.__class__.__name__}(sampled={self.sampled})>" - def get_attributes(self) -> "Attributes": return {} From d77342836cc94dbc98870b63d1d030b586a98ebd Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 13:26:59 +0100 Subject: [PATCH 09/23] ref: Add experimental streaming API --- sentry_sdk/scope.py | 54 ++++++++++++++++++++++++- sentry_sdk/traces.py | 94 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 146 insertions(+), 2 deletions(-) diff --git a/sentry_sdk/scope.py b/sentry_sdk/scope.py index 3bc51c1af0..b6943df634 100644 --- a/sentry_sdk/scope.py +++ b/sentry_sdk/scope.py @@ -33,7 +33,7 @@ normalize_incoming_data, PropagationContext, ) -from sentry_sdk.traces import StreamedSpan +from sentry_sdk.traces import StreamedSpan, NoOpStreamedSpan from sentry_sdk.tracing import ( BAGGAGE_HEADER_NAME, SENTRY_TRACE_HEADER_NAME, @@ -1174,6 +1174,58 @@ def start_span( return span + def start_streamed_span( + self, + name: str, + attributes: "Optional[Attributes]" = None, + parent_span: "Optional[StreamedSpan]" = None, + active: bool = True, + ) -> "StreamedSpan": + # TODO: rename to start_span once we drop the old API + if isinstance(parent_span, NoOpStreamedSpan): + # parent_span is only set if the user explicitly set it + logger.debug( + "Ignored parent span provided. Span will be parented to the " + "currently active span instead." + ) + + if parent_span is None or isinstance(parent_span, NoOpStreamedSpan): + parent_span = self.span or self.get_current_scope().span # type: ignore + + # If no eligible parent_span was provided and there is no currently + # active span, this is a segment + if parent_span is None: + propagation_context = self.get_active_propagation_context() + + return StreamedSpan( + name=name, + attributes=attributes, + active=active, + scope=self, + segment=None, + trace_id=propagation_context.trace_id, + parent_span_id=propagation_context.parent_span_id, + parent_sampled=propagation_context.parent_sampled, + baggage=propagation_context.baggage, + ) + + # This is a child span; take propagation context from the parent span + with new_scope(): + if isinstance(parent_span, NoOpStreamedSpan): + return NoOpStreamedSpan() + + return StreamedSpan( + name=name, + attributes=attributes, + active=active, + scope=self, + segment=parent_span._segment, + trace_id=parent_span.trace_id, + parent_span_id=parent_span.span_id, + parent_sampled=parent_span.sampled, + ) + + def continue_trace( self, environ_or_headers: "Dict[str, Any]", diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index e09d7191c3..30fca8b2f4 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -9,6 +9,8 @@ from enum import Enum from typing import TYPE_CHECKING +import sentry_sdk +from sentry_sdk.tracing_utils import Baggage from sentry_sdk.utils import format_attribute, logger if TYPE_CHECKING: @@ -57,6 +59,66 @@ def __str__(self) -> str: } +def start_span( + name: str, + attributes: "Optional[Attributes]" = None, + parent_span: "Optional[StreamedSpan]" = None, + active: bool = True, +) -> "StreamedSpan": + """ + Start a span. + + The span's parent, unless provided explicitly via the `parent_span` argument, + will be the current active span, if any. If there is none, this span will + become the root of a new span tree. + + `start_span()` can either be used as context manager or you can use the span + object it returns and explicitly end it via `span.end()`. The following is + equivalent: + + ```python + import sentry_sdk + + with sentry_sdk.traces.start_span(name="My Span"): + # do something + + # The span automatically finishes once the `with` block is exited + ``` + + ```python + import sentry_sdk + + span = sentry_sdk.traces.start_span(name="My Span") + # do something + span.end() + ``` + + :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. + These will also be accessible in the traces sampler. + :type attributes: "Optional[Attributes]" + + :param parent_span: A span instance that the new span should consider its + parent. 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: The span that has been started. + :rtype: StreamedSpan + """ + return sentry_sdk.get_current_scope().start_streamed_span( + name, attributes, parent_span, active + ) + + class StreamedSpan: """ A span holds timing information of a block of code. @@ -73,7 +135,12 @@ class StreamedSpan: "_active", "_span_id", "_trace_id", + "_parent_span_id", + "_segment", + "_parent_sampled", "_status", + "_scope", + "_baggage", ) def __init__( @@ -82,7 +149,12 @@ def __init__( name: str, attributes: "Optional[Attributes]" = None, active: bool = True, + scope: "sentry_sdk.Scope", + segment: "Optional[StreamedSpan]" = None, trace_id: "Optional[str]" = None, + parent_span_id: "Optional[str]" = None, + parent_sampled: "Optional[bool]" = None, + baggage: "Optional[Baggage]" = None, ): self._name: str = name self._active: bool = active @@ -91,8 +163,16 @@ def __init__( for attribute, value in attributes.items(): self.set_attribute(attribute, value) - self._span_id: "Optional[str]" = None + self._scope = scope + + self._segment = segment or self + self._trace_id: "Optional[str]" = trace_id + self._parent_span_id = parent_span_id + self._parent_sampled = parent_sampled + self._baggage = baggage + + self._span_id: "Optional[str]" = None self._status = SpanStatus.OK.value self.set_attribute("sentry.span.source", SegmentSource.CUSTOM.value) @@ -103,6 +183,7 @@ def __repr__(self) -> str: f"name={self._name}, " f"trace_id={self.trace_id}, " f"span_id={self.span_id}, " + f"parent_span_id={self._parent_span_id}, " f"active={self._active})>" ) @@ -165,8 +246,15 @@ def trace_id(self) -> str: return self._trace_id + @property + def sampled(self) -> "Optional[bool]": + return True + class NoOpStreamedSpan(StreamedSpan): + def __init__(self) -> None: + pass + def get_attributes(self) -> "Attributes": return {} @@ -206,3 +294,7 @@ def span_id(self) -> str: @property def trace_id(self) -> str: return "00000000000000000000000000000000" + + @property + def sampled(self) -> "Optional[bool]": + return False From 647fa79ed6e5839b1c34cd71f5167fe98c5dbf7a Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 13:33:09 +0100 Subject: [PATCH 10/23] reformat --- sentry_sdk/scope.py | 1 - 1 file changed, 1 deletion(-) diff --git a/sentry_sdk/scope.py b/sentry_sdk/scope.py index b6943df634..708e27ff45 100644 --- a/sentry_sdk/scope.py +++ b/sentry_sdk/scope.py @@ -1225,7 +1225,6 @@ def start_streamed_span( parent_sampled=parent_span.sampled, ) - def continue_trace( self, environ_or_headers: "Dict[str, Any]", From 49bdbe61a58043a88982c38f682a79dec76e7e7f Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 13:44:37 +0100 Subject: [PATCH 11/23] Add a __repr__ --- sentry_sdk/traces.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index 30fca8b2f4..aa54296d97 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -255,6 +255,9 @@ class NoOpStreamedSpan(StreamedSpan): def __init__(self) -> None: pass + def __repr__(self) -> str: + return f"<{self.__class__.__name__}(sampled={self.sampled})>" + def get_attributes(self) -> "Attributes": return {} From 54f81afad43200d26176527a0de9757687406146 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 13:41:02 +0100 Subject: [PATCH 12/23] ref: Add new_trace, continue_trace to span first --- sentry_sdk/traces.py | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index aa54296d97..f6156e77ac 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -14,7 +14,7 @@ from sentry_sdk.utils import format_attribute, logger if TYPE_CHECKING: - from typing import Optional, Union + from typing import Any, Optional, Union from sentry_sdk._types import Attributes, AttributeValue @@ -93,6 +93,9 @@ def start_span( span.end() ``` + To continue a trace from another service, call + `sentry_sdk.traces.continue_trace()` prior to creating a top-level span. + :param name: The name to identify this span by. :type name: str @@ -119,6 +122,44 @@ def start_span( ) +def continue_trace(incoming: "dict[str, Any]") -> None: + """ + Continue a trace from headers or environment variables. + + This function sets the propagation context on the scope. Any span started + in the updated scope will belong under the trace extracted from the + provided propagation headers or environment variables. + + continue_trace() doesn't start any spans on its own. Use the start_span() + API for that. + """ + # This is set both on the isolation and the current scope for compatibility + # reasons. Conceptually, it belongs on the isolation scope, and it also + # used to be set there in non-span-first mode. But in span first mode, we + # start spans on the current scope, regardless of type, like JS does, so we + # need to set the propagation context there. + sentry_sdk.get_isolation_scope().generate_propagation_context( + incoming, + ) + return sentry_sdk.get_current_scope().generate_propagation_context( + incoming, + ) + + +def new_trace() -> None: + """ + Resets the propagation context, forcing a new trace. + + This function sets the propagation context on the scope. Any span started + in the updated scope will start its own trace. + + new_trace() doesn't start any spans on its own. Use the start_span() API + for that. + """ + sentry_sdk.get_isolation_scope().set_new_propagation_context() + sentry_sdk.get_current_scope().set_new_propagation_context() + + class StreamedSpan: """ A span holds timing information of a block of code. From 941863e2f692f067deaf23e9b21452679f513f53 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 13:57:08 +0100 Subject: [PATCH 13/23] ref: Add streaming trace decorator --- sentry_sdk/traces.py | 76 ++++++++++++++++++++++++++++++++++++- sentry_sdk/tracing_utils.py | 59 ++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+), 1 deletion(-) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index f6156e77ac..09ba250e23 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -14,9 +14,12 @@ from sentry_sdk.utils import format_attribute, logger if TYPE_CHECKING: - from typing import Any, Optional, Union + from typing import Any, Callable, Optional, ParamSpec, TypeVar, Union from sentry_sdk._types import Attributes, AttributeValue + P = ParamSpec("P") + R = TypeVar("R") + class SpanStatus(str, Enum): OK = "ok" @@ -342,3 +345,74 @@ def trace_id(self) -> str: @property def sampled(self) -> "Optional[bool]": return False + + +def trace( + func: "Optional[Callable[P, R]]" = None, + *, + 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. + + This decorator automatically creates a new span when the decorated function + is called, and finishes the span when the function returns or raises an exception. + + :param func: The function to trace. When used as a decorator without parentheses, + this is the function being decorated. When used with parameters (e.g., + ``@trace(op="custom")``, this should be None. + :type func: Callable or None + + :param name: The human-readable name/description for the span. If not provided, + defaults to the function name. This provides more specific details about + what the span represents (e.g., "GET /api/users", "process_user_data"). + :type name: str or None + + :param attributes: A dictionary of key-value pairs to add as attributes to the span. + Attribute values must be strings, integers, floats, or booleans. These + 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 + + Example:: + + import sentry_sdk + + # Simple usage with default values + @sentry_sdk.trace + def process_data(): + # Function implementation + pass + + # With custom parameters + @sentry_sdk.trace( + name="Get user data", + attributes={"postgres": True} + ) + def make_db_query(sql): + # Function implementation + pass + """ + from sentry_sdk.tracing_utils import create_streaming_span_decorator + + decorator = create_streaming_span_decorator( + name=name, + attributes=attributes, + active=active, + ) + + if func: + return decorator(func) + else: + return decorator diff --git a/sentry_sdk/tracing_utils.py b/sentry_sdk/tracing_utils.py index c1d6c44535..8fe31bb33d 100644 --- a/sentry_sdk/tracing_utils.py +++ b/sentry_sdk/tracing_utils.py @@ -942,6 +942,58 @@ def sync_wrapper(*args: "Any", **kwargs: "Any") -> "Any": return span_decorator +def create_streaming_span_decorator( + name: "Optional[str]" = None, + attributes: "Optional[dict[str, Any]]" = None, + active: bool = True, +) -> "Any": + """ + Create a span creating decorator that can wrap both sync and async functions. + """ + from sentry_sdk.scope import should_send_default_pii + + def span_decorator(f: "Any") -> "Any": + """ + Decorator to create a span for the given function. + """ + + @functools.wraps(f) + 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, active=active + ): + result = await f(*args, **kwargs) + return result + + try: + async_wrapper.__signature__ = inspect.signature(f) # type: ignore[attr-defined] + except Exception: + pass + + @functools.wraps(f) + 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, active=active + ): + return f(*args, **kwargs) + + try: + sync_wrapper.__signature__ = inspect.signature(f) # type: ignore[attr-defined] + except Exception: + pass + + if inspect.iscoroutinefunction(f): + return async_wrapper + else: + return sync_wrapper + + return span_decorator + + def get_current_span(scope: "Optional[sentry_sdk.Scope]" = None) -> "Optional[Span]": """ Returns the currently active span if there is one running, otherwise `None` @@ -1320,3 +1372,10 @@ def add_sentry_baggage_to_headers( if TYPE_CHECKING: from sentry_sdk.tracing import Span + + +from sentry_sdk.traces import ( + LOW_QUALITY_SEGMENT_SOURCES, + start_span as start_streaming_span, + StreamedSpan, +) From 4b14e8d534e686b5a18f931655128453f0ecc14b Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 14:52:21 +0100 Subject: [PATCH 14/23] Remove redundant code --- sentry_sdk/scope.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sentry_sdk/scope.py b/sentry_sdk/scope.py index 708e27ff45..9970ea975e 100644 --- a/sentry_sdk/scope.py +++ b/sentry_sdk/scope.py @@ -1190,7 +1190,7 @@ def start_streamed_span( ) if parent_span is None or isinstance(parent_span, NoOpStreamedSpan): - parent_span = self.span or self.get_current_scope().span # type: ignore + parent_span = self.span # type: ignore # If no eligible parent_span was provided and there is no currently # active span, this is a segment From 474f8e6e1e2740043acead83d915b5f1f4ef0a82 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 14:56:00 +0100 Subject: [PATCH 15/23] simplify --- sentry_sdk/traces.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index f6156e77ac..1739f8b25c 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -141,7 +141,7 @@ def continue_trace(incoming: "dict[str, Any]") -> None: sentry_sdk.get_isolation_scope().generate_propagation_context( incoming, ) - return sentry_sdk.get_current_scope().generate_propagation_context( + sentry_sdk.get_current_scope().generate_propagation_context( incoming, ) From f2738ff53a93069b1eadc0d920befedde9a970b8 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 14:58:52 +0100 Subject: [PATCH 16/23] reorder imports --- sentry_sdk/tracing_utils.py | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/sentry_sdk/tracing_utils.py b/sentry_sdk/tracing_utils.py index 8fe31bb33d..9c6f811d85 100644 --- a/sentry_sdk/tracing_utils.py +++ b/sentry_sdk/tracing_utils.py @@ -1369,13 +1369,11 @@ def add_sentry_baggage_to_headers( LOW_QUALITY_TRANSACTION_SOURCES, SENTRY_TRACE_HEADER_NAME, ) - -if TYPE_CHECKING: - from sentry_sdk.tracing import Span - - from sentry_sdk.traces import ( LOW_QUALITY_SEGMENT_SOURCES, start_span as start_streaming_span, StreamedSpan, ) + +if TYPE_CHECKING: + from sentry_sdk.tracing import Span From c974d3edca3a39d33a4cd9a1869a7521026c3237 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 15:15:15 +0100 Subject: [PATCH 17/23] add dummy __enter__, __exit__ --- sentry_sdk/traces.py | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index bb924563d5..f02954c949 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -231,6 +231,14 @@ def __repr__(self) -> str: f"active={self._active})>" ) + def __enter__(self) -> "StreamedSpan": + return self + + def __exit__( + self, ty: "Optional[Any]", value: "Optional[Any]", tb: "Optional[Any]" + ) -> None: + pass + def get_attributes(self) -> "Attributes": return self._attributes @@ -302,6 +310,14 @@ def __init__(self) -> None: def __repr__(self) -> str: return f"<{self.__class__.__name__}(sampled={self.sampled})>" + def __enter__(self) -> "StreamedSpan": + return self + + def __exit__( + self, ty: "Optional[Any]", value: "Optional[Any]", tb: "Optional[Any]" + ) -> None: + pass + def get_attributes(self) -> "Attributes": return {} From 831adae305487de271d9113776a08db111174fe3 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 15:20:26 +0100 Subject: [PATCH 18/23] type hint --- sentry_sdk/traces.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index f02954c949..bede851e0c 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -310,7 +310,7 @@ def __init__(self) -> None: def __repr__(self) -> str: return f"<{self.__class__.__name__}(sampled={self.sampled})>" - def __enter__(self) -> "StreamedSpan": + def __enter__(self) -> "NoOpStreamedSpan": return self def __exit__( From 1dcf176a90df631b1002eb0b601d5c80861a9962 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Thu, 5 Mar 2026 16:22:49 +0100 Subject: [PATCH 19/23] remove unused import --- sentry_sdk/tracing_utils.py | 1 - 1 file changed, 1 deletion(-) diff --git a/sentry_sdk/tracing_utils.py b/sentry_sdk/tracing_utils.py index 9c6f811d85..80b4628153 100644 --- a/sentry_sdk/tracing_utils.py +++ b/sentry_sdk/tracing_utils.py @@ -950,7 +950,6 @@ def create_streaming_span_decorator( """ Create a span creating decorator that can wrap both sync and async functions. """ - from sentry_sdk.scope import should_send_default_pii def span_decorator(f: "Any") -> "Any": """ From f2235745e492a8429ed4f88cb53cdb2054aef73e Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 6 Mar 2026 13:50:28 +0100 Subject: [PATCH 20/23] Correctly detect user-set parent_span=None --- sentry_sdk/scope.py | 12 +++++++----- sentry_sdk/traces.py | 13 ++++++++++--- 2 files changed, 17 insertions(+), 8 deletions(-) diff --git a/sentry_sdk/scope.py b/sentry_sdk/scope.py index 9970ea975e..caaac114bf 100644 --- a/sentry_sdk/scope.py +++ b/sentry_sdk/scope.py @@ -33,7 +33,7 @@ normalize_incoming_data, PropagationContext, ) -from sentry_sdk.traces import StreamedSpan, NoOpStreamedSpan +from sentry_sdk.traces import _DEFAULT_PARENT_SPAN, StreamedSpan, NoOpStreamedSpan from sentry_sdk.tracing import ( BAGGAGE_HEADER_NAME, SENTRY_TRACE_HEADER_NAME, @@ -1177,9 +1177,9 @@ def start_span( def start_streamed_span( self, name: str, - attributes: "Optional[Attributes]" = None, - parent_span: "Optional[StreamedSpan]" = None, - active: bool = True, + attributes: "Optional[Attributes]", + parent_span: "Optional[StreamedSpan]", + active: bool, ) -> "StreamedSpan": # TODO: rename to start_span once we drop the old API if isinstance(parent_span, NoOpStreamedSpan): @@ -1189,7 +1189,9 @@ def start_streamed_span( "currently active span instead." ) - if parent_span is None or isinstance(parent_span, NoOpStreamedSpan): + if parent_span is _DEFAULT_PARENT_SPAN or isinstance( + parent_span, NoOpStreamedSpan + ): parent_span = self.span # type: ignore # If no eligible parent_span was provided and there is no currently diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index aa54296d97..615d5d8f2a 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -59,10 +59,15 @@ def __str__(self) -> str: } +# Sentinel value for an unset parent_span to be able to distinguish it from +# a None set by the user +_DEFAULT_PARENT_SPAN = object() + + def start_span( name: str, attributes: "Optional[Attributes]" = None, - parent_span: "Optional[StreamedSpan]" = None, + parent_span: "Optional[StreamedSpan]" = _DEFAULT_PARENT_SPAN, active: bool = True, ) -> "StreamedSpan": """ @@ -70,7 +75,8 @@ def start_span( The span's parent, unless provided explicitly via the `parent_span` argument, will be the current active span, if any. If there is none, this span will - become the root of a new span tree. + become the root of a new span tree. If you explicitly want this span to be + top-level without a parent, set `parent_span=None`. `start_span()` can either be used as context manager or you can use the span object it returns and explicitly end it via `span.end()`. The following is @@ -102,7 +108,8 @@ def start_span( :param parent_span: A span instance that the new span should consider its parent. If not provided, the parent will be set to the currently active - span, if any. + span, if any. If set to `None`, this span will become a new root-level + span. :type parent_span: "Optional[StreamedSpan]" :param active: Controls whether spans started while this span is running From 9e8e60ef87bbd8a2167bbd3310c17b92b84a94e9 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 6 Mar 2026 13:54:47 +0100 Subject: [PATCH 21/23] mypy --- sentry_sdk/traces.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sentry_sdk/traces.py b/sentry_sdk/traces.py index 615d5d8f2a..0dcb003581 100644 --- a/sentry_sdk/traces.py +++ b/sentry_sdk/traces.py @@ -67,7 +67,7 @@ def __str__(self) -> str: def start_span( name: str, attributes: "Optional[Attributes]" = None, - parent_span: "Optional[StreamedSpan]" = _DEFAULT_PARENT_SPAN, + parent_span: "Optional[StreamedSpan]" = _DEFAULT_PARENT_SPAN, # type: ignore[assignment] active: bool = True, ) -> "StreamedSpan": """ From 1006e7b30294e54445a4bc9b996cad895b1f009b Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Fri, 6 Mar 2026 14:02:47 +0100 Subject: [PATCH 22/23] remove unused imports --- sentry_sdk/tracing_utils.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/sentry_sdk/tracing_utils.py b/sentry_sdk/tracing_utils.py index 80b4628153..54c3dcc6f5 100644 --- a/sentry_sdk/tracing_utils.py +++ b/sentry_sdk/tracing_utils.py @@ -1369,9 +1369,7 @@ def add_sentry_baggage_to_headers( SENTRY_TRACE_HEADER_NAME, ) from sentry_sdk.traces import ( - LOW_QUALITY_SEGMENT_SOURCES, start_span as start_streaming_span, - StreamedSpan, ) if TYPE_CHECKING: From 876532fcc7058a3c1c7228f95a608e890a8d7724 Mon Sep 17 00:00:00 2001 From: Ivana Kellyer Date: Mon, 9 Mar 2026 09:50:31 +0100 Subject: [PATCH 23/23] ref: Per-bucket limits, fix envelope chunking (8) (#5595) ### Description - correctly splice spans into multiple envelopes if a bucket contains more than 1000 spans from the same `trace_id` - add weight-based flushing (actual limit is 10 MB, we flush at 5 MB) - apply the weight and amount limits per `trace_id` rather than globally - add `trace_id`, `parent_span_id` to the transport format #### 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](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) --- sentry_sdk/_span_batcher.py | 90 ++++++++++++++++++++++++------------- 1 file changed, 58 insertions(+), 32 deletions(-) diff --git a/sentry_sdk/_span_batcher.py b/sentry_sdk/_span_batcher.py index 947eca3806..baa67fbd9d 100644 --- a/sentry_sdk/_span_batcher.py +++ b/sentry_sdk/_span_batcher.py @@ -15,10 +15,15 @@ class SpanBatcher(Batcher["StreamedSpan"]): - # TODO[span-first]: size-based flushes - # TODO[span-first]: adjust flush/drop defaults + # MAX_BEFORE_FLUSH should be lower than MAX_BEFORE_DROP, so that there is + # a bit of a buffer for spans that appear between setting the flush event + # and actually flushing the buffer. + # + # The max limits are all per trace. + MAX_ENVELOPE_SIZE = 1000 # spans MAX_BEFORE_FLUSH = 1000 - MAX_BEFORE_DROP = 5000 + MAX_BEFORE_DROP = 2000 + MAX_BYTES_BEFORE_FLUSH = 5 * 1024 * 1024 # 5 MB FLUSH_WAIT_TIME = 5.0 TYPE = "span" @@ -35,6 +40,7 @@ def __init__( # envelope. # trace_id -> span buffer self._span_buffer: dict[str, list["StreamedSpan"]] = defaultdict(list) + self._running_size: dict[str, int] = defaultdict(lambda: 0) self._capture_func = capture_func self._record_lost_func = record_lost_func self._running = True @@ -45,16 +51,12 @@ def __init__( self._flusher: "Optional[threading.Thread]" = None self._flusher_pid: "Optional[int]" = None - def get_size(self) -> int: - # caller is responsible for locking before checking this - return sum(len(buffer) for buffer in self._span_buffer.values()) - def add(self, span: "StreamedSpan") -> None: if not self._ensure_thread() or self._flusher is None: return None with self._lock: - size = self.get_size() + size = len(self._span_buffer[span.trace_id]) if size >= self.MAX_BEFORE_DROP: self._record_lost_func( reason="queue_overflow", @@ -64,18 +66,36 @@ def add(self, span: "StreamedSpan") -> None: return None self._span_buffer[span.trace_id].append(span) + self._running_size[span.trace_id] += self._estimate_size(span) + if size + 1 >= self.MAX_BEFORE_FLUSH: self._flush_event.set() + return + + if self._running_size[span.trace_id] >= self.MAX_BYTES_BEFORE_FLUSH: + self._flush_event.set() + return + + @staticmethod + def _estimate_size(item: "StreamedSpan") -> int: + # Rough estimate of serialized span size that's quick to compute. + # 210 is the rough size of the payload without attributes, and we + # estimate additional 70 bytes on top of that per attribute. + return 210 + 70 * len(item._attributes) @staticmethod def _to_transport_format(item: "StreamedSpan") -> "Any": # TODO[span-first] res: "dict[str, Any]" = { + "trace_id": item.trace_id, "span_id": item.span_id, "name": item._name, "status": item._status, } + if item._parent_span_id: + res["parent_span_id"] = item._parent_span_id + if item._attributes: res["attributes"] = { k: serialize_attribute(v) for (k, v) in item._attributes.items() @@ -86,7 +106,7 @@ def _to_transport_format(item: "StreamedSpan") -> "Any": def _flush(self) -> None: with self._lock: if len(self._span_buffer) == 0: - return None + return envelopes = [] for trace_id, spans in self._span_buffer.items(): @@ -95,34 +115,40 @@ def _flush(self) -> None: # dsc = spans[0].dynamic_sampling_context() dsc = None - envelope = Envelope( - headers={ - "sent_at": format_timestamp(datetime.now(timezone.utc)), - "trace": dsc, - } - ) - - envelope.add_item( - Item( - type="span", - content_type="application/vnd.sentry.items.span.v2+json", + # Max per envelope is 1000, so if we happen to have more than + # 1000 spans in one bucket, we'll need to separate them. + for start in range(0, len(spans), self.MAX_ENVELOPE_SIZE): + end = min(start + self.MAX_ENVELOPE_SIZE, len(spans)) + + envelope = Envelope( headers={ - "item_count": len(spans), - }, - payload=PayloadRef( - json={ - "items": [ - self._to_transport_format(span) - for span in spans - ] - } - ), + "sent_at": format_timestamp(datetime.now(timezone.utc)), + "trace": dsc, + } + ) + + envelope.add_item( + Item( + type=self.TYPE, + content_type=self.CONTENT_TYPE, + headers={ + "item_count": end - start, + }, + payload=PayloadRef( + json={ + "items": [ + self._to_transport_format(spans[j]) + for j in range(start, end) + ] + } + ), + ) ) - ) - envelopes.append(envelope) + envelopes.append(envelope) self._span_buffer.clear() + self._running_size.clear() for envelope in envelopes: self._capture_func(envelope)