ref: Add warnings to span streaming APIs (10)

sentry_sdk/_span_batcher.py

@@ -91,8 +91,12 @@ def _to_transport_format(item: "StreamedSpan") -> "Any":
             "span_id": item.span_id,
             "name": item._name,
             "status": item._status,
+            "start_timestamp": item._start_timestamp.timestamp(),
         }
 
+        if item._timestamp:
+            res["end_timestamp"] = item._timestamp.timestamp()
+
         if item._parent_span_id:
             res["parent_span_id"] = item._parent_span_id
 

sentry_sdk/scope.py

@@ -1182,6 +1182,15 @@ def start_streamed_span(
         active: bool,
     ) -> "StreamedSpan":
         # TODO: rename to start_span once we drop the old API
+        if not has_span_streaming_enabled(self.client.options):
+            warnings.warn(
+                "Using span streaming API in non-span-streaming mode. Use "
+                "sentry_sdk.start_transaction() and sentry_sdk.start_span() "
+                "instead.",
+                stacklevel=2,
+            )
+            return NoOpStreamedSpan()
+
         if isinstance(parent_span, NoOpStreamedSpan):
             # parent_span is only set if the user explicitly set it
             logger.debug(

sentry_sdk/traces.py

@@ -1,17 +1,27 @@
 """
+EXPERIMENTAL. Do not use in production.
+
 The API in this file is only meant to be used in span streaming mode.
 
 You can enable span streaming mode via
 sentry_sdk.init(_experiments={"trace_lifecycle": "stream"}).
 """
 
 import uuid
+import warnings
+from datetime import datetime, timedelta, timezone
 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
+from sentry_sdk.utils import (
+    capture_internal_exceptions,
+    format_attribute,
+    logger,
+    nanosecond_time,
+    should_be_treated_as_error,
+)
 
 if TYPE_CHECKING:
     from typing import Any, Callable, Optional, ParamSpec, TypeVar, Union
@@ -76,6 +86,9 @@ def start_span(
     """
     Start a span.
 
+    EXPERIMENTAL. Use sentry_sdk.start_transaction() and sentry_sdk.start_span()
+    instead.
+
     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. If you explicitly want this span to be
@@ -136,6 +149,8 @@ def continue_trace(incoming: "dict[str, Any]") -> None:
     """
     Continue a trace from headers or environment variables.
 
+    EXPERIMENTAL. Use sentry_sdk.continue_trace() instead.
+
     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.
@@ -160,6 +175,8 @@ def new_trace() -> None:
     """
     Resets the propagation context, forcing a new trace.
 
+    EXPERIMENTAL.
+
     This function sets the propagation context on the scope. Any span started
     in the updated scope will start its own trace.
 
@@ -189,8 +206,12 @@ class StreamedSpan:
         "_parent_span_id",
         "_segment",
         "_parent_sampled",
+        "_start_timestamp",
+        "_start_timestamp_monotonic_ns",
+        "_timestamp",
         "_status",
         "_scope",
+        "_previous_span_on_scope",
         "_baggage",
     )
 
@@ -223,11 +244,23 @@ def __init__(
         self._parent_sampled = parent_sampled
         self._baggage = baggage
 
+        self._start_timestamp = datetime.now(timezone.utc)
+        self._timestamp: "Optional[datetime]" = None
+
+        try:
+            # profiling depends on this value and requires that
+            # it is measured in nanoseconds
+            self._start_timestamp_monotonic_ns = nanosecond_time()
+        except AttributeError:
+            pass
+
         self._span_id: "Optional[str]" = None
 
         self._status = SpanStatus.OK.value
         self.set_attribute("sentry.span.source", SegmentSource.CUSTOM.value)
 
+        self._start()
+
     def __repr__(self) -> str:
         return (
             f"<{self.__class__.__name__}("
@@ -244,7 +277,79 @@ def __enter__(self) -> "StreamedSpan":
     def __exit__(
         self, ty: "Optional[Any]", value: "Optional[Any]", tb: "Optional[Any]"
     ) -> None:
-        pass
+        if value is not None and should_be_treated_as_error(ty, value):
+            self.status = SpanStatus.ERROR
+
+        self._end()
+
+    def end(self, end_timestamp: "Optional[Union[float, datetime]]" = None) -> None:
+        """
+        Finish this span and queue it for sending.
+
+        :param end_timestamp: End timestamp to use instead of current time.
+        :type end_timestamp: "Optional[Union[float, datetime]]"
+        """
+        self._end(end_timestamp)
+
+    def finish(self, end_timestamp: "Optional[Union[float, datetime]]" = None) -> None:
+        warnings.warn(
+            "span.finish() is deprecated. Use span.end() instead.",
+            stacklevel=2,
+            category=DeprecationWarning,
+        )
+
+        self.end(end_timestamp)
+
+    def _start(self) -> None:
+        if self._active:
+            old_span = self._scope.span
+            self._scope.span = self  # type: ignore
+            self._previous_span_on_scope = old_span
+
+    def _end(self, end_timestamp: "Optional[Union[float, datetime]]" = None) -> None:
+        if self._timestamp is not None:
+            # This span is already finished, ignore.
+            return
+
+        # Detach from scope
+        if self._active:
+            with capture_internal_exceptions():
+                old_span = self._previous_span_on_scope
+                del self._previous_span_on_scope
+                self._scope.span = old_span
+
+        # Set attributes from the segment
+        self.set_attribute("sentry.segment.id", self._segment.span_id)
+        self.set_attribute("sentry.segment.name", self._segment.name)
+
+        # Set the end timestamp
+        if end_timestamp is not None:
+            if isinstance(end_timestamp, (float, int)):
+                try:
+                    end_timestamp = datetime.fromtimestamp(end_timestamp, timezone.utc)
+                except Exception:
+                    pass
+
+            if isinstance(end_timestamp, datetime):
+                self._timestamp = end_timestamp
+            else:
+                logger.debug("Failed to set end_timestamp. Using current time instead.")
+
+        if self._timestamp is None:
+            try:
+                elapsed = nanosecond_time() - self._start_timestamp_monotonic_ns
+                self._timestamp = self._start_timestamp + timedelta(
+                    microseconds=elapsed / 1000
+                )
+            except AttributeError:
+                self._timestamp = datetime.now(timezone.utc)
+
+        client = sentry_sdk.get_client()
+        if not client.is_active():
+            return
+
+        # Finally, queue the span for sending to Sentry
+        self._scope._capture_span(self)
 
     def get_attributes(self) -> "Attributes":
         return self._attributes
@@ -309,10 +414,28 @@ def trace_id(self) -> str:
     def sampled(self) -> "Optional[bool]":
         return True
 
+    @property
+    def start_timestamp(self) -> "Optional[datetime]":
+        return self._start_timestamp
+
+    @property
+    def timestamp(self) -> "Optional[datetime]":
+        return self._timestamp
+
 
 class NoOpStreamedSpan(StreamedSpan):
-    def __init__(self) -> None:
-        pass
+    __slots__ = (
+        "_scope",
+        "_previous_span_on_scope",
+    )
+
+    def __init__(
+        self,
+        scope: "Optional[sentry_sdk.Scope]" = None,
+    ) -> None:
+        self._scope = scope  # type: ignore[assignment]
+
+        self._start()
 
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__}(sampled={self.sampled})>"
@@ -323,7 +446,36 @@ def __enter__(self) -> "NoOpStreamedSpan":
     def __exit__(
         self, ty: "Optional[Any]", value: "Optional[Any]", tb: "Optional[Any]"
     ) -> None:
-        pass
+        self._end()
+
+    def _start(self) -> None:
+        if self._scope is None:
+            return
+
+        old_span = self._scope.span
+        self._scope.span = self  # type: ignore
+        self._previous_span_on_scope = old_span
+
+    def _end(self, end_timestamp: "Optional[Union[float, datetime]]" = None) -> None:
+        if self._scope is None:
+            return
+
+        with capture_internal_exceptions():
+            old_span = self._previous_span_on_scope
+            del self._previous_span_on_scope
+            self._scope.span = old_span
+
+    def end(self, end_timestamp: "Optional[Union[float, datetime]]" = None) -> None:
+        self._end()
+
+    def finish(self, end_timestamp: "Optional[Union[float, datetime]]" = None) -> None:
+        warnings.warn(
+            "span.finish() is deprecated. Use span.end() instead.",
+            stacklevel=2,
+            category=DeprecationWarning,
+        )
+
+        self._end()
 
     def get_attributes(self) -> "Attributes":
         return {}
@@ -369,6 +521,14 @@ def trace_id(self) -> str:
     def sampled(self) -> "Optional[bool]":
         return False
 
+    @property
+    def start_timestamp(self) -> "Optional[datetime]":
+        return None
+
+    @property
+    def timestamp(self) -> "Optional[datetime]":
+        return None
+
 
 def trace(
     func: "Optional[Callable[P, R]]" = None,
@@ -380,6 +540,8 @@ def trace(
     """
     Decorator to start a span around a function call.
 
+    EXPERIMENTAL. Use @sentry_sdk.trace instead.
+
     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.
 
@@ -427,7 +589,9 @@ def make_db_query(sql):
             # Function implementation
             pass
     """
-    from sentry_sdk.tracing_utils import create_streaming_span_decorator
+    from sentry_sdk.tracing_utils import (
+        create_streaming_span_decorator,
+    )
 
     decorator = create_streaming_span_decorator(
         name=name,

sentry_sdk/tracing_utils.py

@@ -4,6 +4,7 @@
 import os
 import re
 import sys
+import warnings
 from collections.abc import Mapping, MutableMapping
 from datetime import timedelta
 from random import Random
@@ -958,6 +959,14 @@ def span_decorator(f: "Any") -> "Any":
 
         @functools.wraps(f)
         async def async_wrapper(*args: "Any", **kwargs: "Any") -> "Any":
+            client = sentry_sdk.get_client()
+            if not has_span_streaming_enabled(client.options):
+                warnings.warn(
+                    "Using span streaming API in non-span-streaming mode. Use "
+                    "@sentry_sdk.trace instead.",
+                    stacklevel=2,
+                )
+
             span_name = name or qualname_from_function(f) or ""
 
             with start_streaming_span(
@@ -973,6 +982,14 @@ async def async_wrapper(*args: "Any", **kwargs: "Any") -> "Any":
 
         @functools.wraps(f)
         def sync_wrapper(*args: "Any", **kwargs: "Any") -> "Any":
+            client = sentry_sdk.get_client()
+            if not has_span_streaming_enabled(client.options):
+                warnings.warn(
+                    "Using span streaming API in non-span-streaming mode. Use "
+                    "@sentry_sdk.trace instead.",
+                    stacklevel=2,
+                )
+
             span_name = name or qualname_from_function(f) or ""
 
             with start_streaming_span(