ref: Add warnings to span streaming APIs (10)

sentry_sdk/traces.py

@@ -1,4 +1,6 @@
 """
+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
@@ -84,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
@@ -135,6 +140,17 @@ def start_span(
     :return: The span that has been started.
     :rtype: StreamedSpan
     """
+    from sentry_sdk.tracing_utils import has_span_streaming_enabled
+
+    if not has_span_streaming_enabled(sentry_sdk.get_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()
+
     return sentry_sdk.get_current_scope().start_streamed_span(
         name, attributes, parent_span, active
     )
@@ -144,6 +160,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.
@@ -168,6 +186,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.
 
@@ -537,6 +557,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.
 
@@ -584,7 +606,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(