Added name parameter to start_span() and deprecated description parameter. (getsentry#3524)

antonpirker · web-flow · commit b1b16b029ba9 · 2024-09-12T11:02:39.000+02:00
To align our API with OpenTelementry. In OTel a span has no description but a name.

This only changes to user facing API, under the hood there is still everything using the description. (This will then be changed with OTel)
diff --git a/sentry_sdk/scope.py b/sentry_sdk/scope.py
@@ -1,5 +1,6 @@
 import os
 import sys
+import warnings
 from copy import copy
 from collections import deque
 from contextlib import contextmanager
@@ -1067,6 +1068,13 @@ def start_span(self, instrumenter=INSTRUMENTER.SENTRY, **kwargs):
         be removed in the next major version. Going forward, it should only
         be used by the SDK itself.
         """
+        if kwargs.get("description") is not None:
+            warnings.warn(
+                "The `description` parameter is deprecated. Please use `name` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         with new_scope():
             kwargs.setdefault("scope", self)
 
diff --git a/sentry_sdk/tracing.py b/sentry_sdk/tracing.py
@@ -70,7 +70,7 @@ class SpanKwargs(TypedDict, total=False):
         """
 
         description: str
-        """A description of what operation is being performed within the span."""
+        """A description of what operation is being performed within the span. This argument is DEPRECATED. Please use the `name` parameter, instead."""
 
         hub: Optional["sentry_sdk.Hub"]
         """The hub to use for this span. This argument is DEPRECATED. Please use the `scope` parameter, instead."""
@@ -97,10 +97,10 @@ class SpanKwargs(TypedDict, total=False):
         Default "manual".
         """
 
-    class TransactionKwargs(SpanKwargs, total=False):
         name: str
-        """Identifier of the transaction. Will show up in the Sentry UI."""
+        """A string describing what operation is being performed within the span/transaction."""
 
+    class TransactionKwargs(SpanKwargs, total=False):
         source: str
         """
         A string describing the source of the transaction name. This will be used to determine the transaction's type.
@@ -227,6 +227,10 @@ class Span:
     :param op: The span's operation. A list of recommended values is available here:
         https://develop.sentry.dev/sdk/performance/span-operations/
     :param description: A description of what operation is being performed within the span.
+
+        .. deprecated:: 2.X.X
+            Please use the `name` parameter, instead.
+    :param name: A string describing what operation is being performed within the span.
     :param hub: The hub to use for this span.
 
         .. deprecated:: 2.0.0
@@ -261,6 +265,7 @@ class Span:
         "_local_aggregator",
         "scope",
         "origin",
+        "name",
     )
 
     def __init__(
@@ -278,6 +283,7 @@ def __init__(
         start_timestamp=None,  # type: Optional[Union[datetime, float]]
         scope=None,  # type: Optional[sentry_sdk.Scope]
         origin="manual",  # type: str
+        name=None,  # type: Optional[str]
     ):
         # type: (...) -> None
         self.trace_id = trace_id or uuid.uuid4().hex
@@ -286,7 +292,7 @@ def __init__(
         self.same_process_as_parent = same_process_as_parent
         self.sampled = sampled
         self.op = op
-        self.description = description
+        self.description = name or description
         self.status = status
         self.hub = hub  # backwards compatibility
         self.scope = scope
@@ -400,6 +406,13 @@ def start_child(self, instrumenter=INSTRUMENTER.SENTRY, **kwargs):
         be removed in the next major version. Going forward, it should only
         be used by the SDK itself.
         """
+        if kwargs.get("description") is not None:
+            warnings.warn(
+                "The `description` parameter is deprecated. Please use `name` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         configuration_instrumenter = sentry_sdk.get_client().options["instrumenter"]
 
         if instrumenter != configuration_instrumenter:
@@ -750,7 +763,7 @@ class Transaction(Span):
         "_baggage",
     )
 
-    def __init__(
+    def __init__(  # type: ignore[misc]
         self,
         name="",  # type: str
         parent_sampled=None,  # type: Optional[bool]
diff --git a/tests/tracing/test_misc.py b/tests/tracing/test_misc.py
@@ -36,11 +36,6 @@ def test_transaction_naming(sentry_init, capture_events):
     sentry_init(traces_sample_rate=1.0)
     events = capture_events()
 
-    # only transactions have names - spans don't
-    with pytest.raises(TypeError):
-        start_span(name="foo")
-    assert len(events) == 0
-
     # default name in event if no name is passed
     with start_transaction() as transaction:
         pass
diff --git a/tests/tracing/test_span_name.py b/tests/tracing/test_span_name.py
@@ -0,0 +1,59 @@
+import pytest
+
+import sentry_sdk
+
+
+def test_start_span_description(sentry_init, capture_events):
+    sentry_init(traces_sample_rate=1.0)
+    events = capture_events()
+
+    with sentry_sdk.start_transaction(name="hi"):
+        with pytest.deprecated_call():
+            with sentry_sdk.start_span(op="foo", description="span-desc"):
+                ...
+
+    (event,) = events
+
+    assert event["spans"][0]["description"] == "span-desc"
+
+
+def test_start_span_name(sentry_init, capture_events):
+    sentry_init(traces_sample_rate=1.0)
+    events = capture_events()
+
+    with sentry_sdk.start_transaction(name="hi"):
+        with sentry_sdk.start_span(op="foo", name="span-name"):
+            ...
+
+    (event,) = events
+
+    assert event["spans"][0]["description"] == "span-name"
+
+
+def test_start_child_description(sentry_init, capture_events):
+    sentry_init(traces_sample_rate=1.0)
+    events = capture_events()
+
+    with sentry_sdk.start_transaction(name="hi"):
+        with pytest.deprecated_call():
+            with sentry_sdk.start_span(op="foo", description="span-desc") as span:
+                with span.start_child(op="bar", description="child-desc"):
+                    ...
+
+    (event,) = events
+
+    assert event["spans"][-1]["description"] == "child-desc"
+
+
+def test_start_child_name(sentry_init, capture_events):
+    sentry_init(traces_sample_rate=1.0)
+    events = capture_events()
+
+    with sentry_sdk.start_transaction(name="hi"):
+        with sentry_sdk.start_span(op="foo", name="span-name") as span:
+            with span.start_child(op="bar", name="child-name"):
+                ...
+
+    (event,) = events
+
+    assert event["spans"][-1]["description"] == "child-name"
