safeguards, some type fixes

Author: sentrivana

sentry_sdk/_tracing.py

@@ -48,6 +48,8 @@
 - {custom_}sampling_context? -> if this is going to die, we need to revive the
   potel pr that went through the integrations and got rid of custom_sampling_context
   in favor of attributes
+- noop spans
+- add a switcher to top level API that figures out which @trace to enable
 
 Notes:
 - removed ability to provide a start_timestamp
@@ -106,6 +108,10 @@ def __str__(self) -> str:
 }
 
 
+class NoOpStreamedSpan:
+    pass
+
+
 class StreamedSpan:
     """
     A span holds timing information of a block of code.
@@ -185,7 +191,6 @@ def __init__(
 
         self._sampled: "Optional[bool]" = None
         self.sample_rate: "Optional[float]" = None
-        self._sample_rand: "Optional[float]" = None
 
         # XXX[span-first]: just do this for segments?
         self._baggage = baggage
@@ -248,17 +253,17 @@ def end(
         self,
         end_timestamp: "Optional[Union[float, datetime]]" = None,
         scope: "Optional[sentry_sdk.Scope]" = None,
-    ) -> "Optional[str]":
+    ) -> None:
         """
-        Set the end timestamp of the span.
+        Set the end timestamp of the span and queue it for sending.
 
         :param end_timestamp: Optional timestamp that should
             be used as timestamp instead of the current time.
         :param scope: The scope to use.
         """
         client = sentry_sdk.get_client()
         if not client.is_active():
-            return None
+            return
 
         scope: "Optional[sentry_sdk.Scope]" = (
             scope or self._scope or sentry_sdk.get_current_scope()
@@ -279,14 +284,14 @@ def end(
 
                 client.transport.record_lost_event(reason, data_category="span")
 
-            return None
+            return
 
         if self.sampled is None:
             logger.warning("Discarding transaction without sampling decision.")
 
         if self.timestamp is not None:
             # This span is already finished, ignore.
-            return None
+            return
 
         try:
             if end_timestamp:
@@ -304,8 +309,6 @@ def end(
         if self.segment.sampled:  # XXX this should just use its own sampled
             sentry_sdk.get_current_scope()._capture_span(self)
 
-        return
-
     def get_attributes(self) -> "Attributes":
         return self.attributes
 
@@ -325,6 +328,10 @@ 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 is_segment(self) -> bool:
         return self.segment == self
 
@@ -352,7 +359,7 @@ def sampled(self) -> "Optional[bool]":
 
         return self._sampled
 
-    def dynamic_sampling_context(self) -> str:
+    def dynamic_sampling_context(self) -> dict[str, str]:
         return self.segment._get_baggage().dynamic_sampling_context()
 
     def _update_active_thread(self) -> None:

sentry_sdk/api.py

@@ -7,6 +7,7 @@
 from sentry_sdk.consts import INSTRUMENTER
 from sentry_sdk.scope import Scope, _ScopeManager, new_scope, isolation_scope
 from sentry_sdk.tracing import NoOpSpan, Transaction, trace
+from sentry_sdk._tracing import StreamedSpan
 from sentry_sdk.crons import monitor
 
 from typing import TYPE_CHECKING
@@ -385,7 +386,9 @@ def set_measurement(name: str, value: float, unit: "MeasurementUnit" = "") -> No
         transaction.set_measurement(name, value, unit)
 
 
-def get_current_span(scope: "Optional[Scope]" = None) -> "Optional[Span]":
+def get_current_span(
+    scope: "Optional[Scope]" = None,
+) -> "Optional[Union[Span, StreamedSpan]]":
     """
     Returns the currently active span if there is one running, otherwise `None`
     """
@@ -501,6 +504,16 @@ def update_current_span(
     if current_span is None:
         return
 
+    if isinstance(current_span, StreamedSpan):
+        warnings.warn(
+            "The `update_current_span` API isn't available in streaming mode. "
+            "Retrieve the current span with get_current_span() and use its API "
+            "directly.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return
+
     if op is not None:
         current_span.op = op
 

sentry_sdk/client.py

@@ -69,7 +69,7 @@
     from sentry_sdk.scope import Scope
     from sentry_sdk.session import Session
     from sentry_sdk.spotlight import SpotlightClient
-    from sentry_sdk.trace import StreamedSpan
+    from sentry_sdk._tracing import StreamedSpan
     from sentry_sdk.transport import Transport, Item
     from sentry_sdk._log_batcher import LogBatcher
     from sentry_sdk._metrics_batcher import MetricsBatcher

sentry_sdk/scope.py

@@ -579,6 +579,13 @@ def get_traceparent(self, *args: "Any", **kwargs: "Any") -> "Optional[str]":
 
         # If we have an active span, return traceparent from there
         if has_tracing_enabled(client.options) and self.span is not None:
+            if isinstance(self.span, StreamedSpan):
+                warnings.warn(
+                    "Scope.get_traceparent is not available in streaming mode.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                return None
             return self.span.to_traceparent()
 
         # else return traceparent from the propagation context
@@ -593,6 +600,13 @@ def get_baggage(self, *args: "Any", **kwargs: "Any") -> "Optional[Baggage]":
 
         # If we have an active span, return baggage from there
         if has_tracing_enabled(client.options) and self.span is not None:
+            if isinstance(self.span, StreamedSpan):
+                warnings.warn(
+                    "Scope.get_baggage is not available in streaming mode.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                return None
             return self.span.to_baggage()
 
         # else return baggage from the propagation context
@@ -603,6 +617,14 @@ def get_trace_context(self) -> "Dict[str, Any]":
         Returns the Sentry "trace" context from the Propagation Context.
         """
         if has_tracing_enabled(self.get_client().options) and self._span is not None:
+            if isinstance(self._span, StreamedSpan):
+                warnings.warn(
+                    "Scope.get_trace_context is not available in streaming mode.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                return {}
+
             return self._span.get_trace_context()
 
         # if we are tracing externally (otel), those values take precedence
@@ -667,6 +689,15 @@ def iter_trace_propagation_headers(
         span = kwargs.pop("span", None)
         span = span or self.span
 
+        if isinstance(span, StreamedSpan):
+            warnings.warn(
+                "Scope.iter_trace_propagation_headers is not available in "
+                "streaming mode.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return None
+
         if has_tracing_enabled(client.options) and span is not None:
             for header in span.iter_headers():
                 yield header
@@ -760,6 +791,14 @@ def transaction(self) -> "Any":
         if self._span is None:
             return None
 
+        if isinstance(self._span, StreamedSpan):
+            warnings.warn(
+                "Scope.transaction is not available in streaming mode.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return None
+
         # there is an orphan span on the scope
         if self._span.containing_transaction is None:
             return None
@@ -789,17 +828,34 @@ def transaction(self, value: "Any") -> None:
             "Assigning to scope.transaction directly is deprecated: use scope.set_transaction_name() instead."
         )
         self._transaction = value
-        if self._span and self._span.containing_transaction:
-            self._span.containing_transaction.name = value
+        if self._span:
+            if isinstance(self._span, StreamedSpan):
+                warnings.warn(
+                    "Scope.transaction is not available in streaming mode.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                return None
+
+            if self._span.containing_transaction:
+                self._span.containing_transaction.name = value
 
     def set_transaction_name(self, name: str, source: "Optional[str]" = None) -> None:
         """Set the transaction name and optionally the transaction source."""
         self._transaction = name
+        if self._span:
+            if isinstance(self._span, StreamedSpan):
+                warnings.warn(
+                    "Scope.set_transaction_name is not available in streaming mode.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                return None
 
-        if self._span and self._span.containing_transaction:
-            self._span.containing_transaction.name = name
-            if source:
-                self._span.containing_transaction.source = source
+            if self._span.containing_transaction:
+                self._span.containing_transaction.name = name
+                if source:
+                    self._span.containing_transaction.source = source
 
         if source:
             self._transaction_info["source"] = source
@@ -1116,6 +1172,15 @@ def start_span(
         be removed in the next major version. Going forward, it should only
         be used by the SDK itself.
         """
+        client = sentry_sdk.get_client()
+        if has_span_streaming_enabled(client.options):
+            warnings.warn(
+                "Scope.start_span is not available in streaming mode.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return NoOpSpan()
+
         if kwargs.get("description") is not None:
             warnings.warn(
                 "The `description` parameter is deprecated. Please use `name` instead.",
@@ -1135,6 +1200,9 @@ def start_span(
 
             # get current span or transaction
             span = self.span or self.get_isolation_scope().span
+            if isinstance(span, StreamedSpan):
+                # make mypy happy
+                return NoOpSpan()
 
             if span is None:
                 # New spans get the `trace_id` from the scope

sentry_sdk/tracing.py

@@ -1427,6 +1427,69 @@ def calculate_interest_rate(amount, rate, years):
         return decorator
 
 
+def streamind_trace(
+    func: "Optional[Callable[P, R]]" = None,
+    *,
+    name: "Optional[str]" = None,
+    attributes: "Optional[dict[str, Any]]" = None,
+) -> "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
+
+    :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,
+    )
+
+    if func:
+        return decorator(func)
+    else:
+        return decorator
+
+
 # Circular imports
 
 from sentry_sdk.tracing_utils import (