Repository: getsentry/sentry-python

Issue:
Add `name` as alias to `description` to `start_span()`.
To align our API more with the OpenTelementry API we will add a `name` parameter to the `start_span()` function. Currently `start_span()` has a `description` parameter. The old parameter will still work and the new parameter is an alias to the old one. If users use the old parameter a deprecation message should be logged.

We also need to update the docs to tell new people to use `name` instead of `description` everywhere: https://docs.sentry.io/platforms/python/tracing/instrumentation/custom-instrumentation/#add-spans-to-a-transaction



Discussion:
codecov[bot]: ### :x: 12 Tests Failed:
| Tests completed | Failed | Passed | Skipped |
|---|---|---|---|
| 16351 | 12 | 16339 | 2268 |
<details><summary>View the top 3 failed tests by shortest run time</summary>

> 
> ```
> tests.tracing.test_misc test_transaction_naming
> ```
> 
> <details><summary>Stack Traces | 0.066s run time</summary>
> 
> > 
> > ```
> > tests/tracing/test_misc.py:41: in test_transaction_naming
> >     start_span(name="foo")
> > E   Failed: DID NOT RAISE &lt;class 'TypeError'&gt;
> > ```
> 
> </details>


> 
> ```
> tests.tracing.test_misc test_transaction_naming
> ```
> 
> <details><summary>Stack Traces | 0.067s run time</summary>
> 
> > 
> > ```
> > tests/tracing/test_misc.py:41: in test_transaction_naming
> >     start_span(name="foo")
> > E   Failed: DID NOT RAISE &lt;class 'TypeError'&gt;
> > ```
> 
> </details>


> 
> ```
> tests.tracing.test_misc test_transaction_naming
> ```
> 
> <details><summary>Stack Traces | 0.067s run time</summary>
> 
> > 
> > ```
> > tests/tracing/test_misc.py:41: in test_transaction_naming
> >     start_span(name="foo")
> > E   Failed: DID NOT RAISE &lt;class 'TypeError'&gt;
> > ```
> 
> </details>

</details>

To view individual test run time comparison to the main branch, go to the [Test Analytics Dashboard](https://app.codecov.io/gh/getsentry/sentry-python/tests/antonpirker%2Fstart_span-name-description)

Patch:
diff --git a/sentry_sdk/scope.py b/sentry_sdk/scope.py
index b6a23253..adae8dc8 100644
--- 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 @@ class Scope:
         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
index 41525b46..036e6619 100644
--- a/sentry_sdk/tracing.py
+++ b/sentry_sdk/tracing.py
@@ -70,7 +70,7 @@ if TYPE_CHECKING:
         """
 
         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 @@ if TYPE_CHECKING:
         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 @@ class Span:
         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 @@ class Span:
         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 @@ class Span:
         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]


Test patch:
diff --git a/tests/tracing/test_misc.py b/tests/tracing/test_misc.py
index 02966642..de2f7825 100644
--- 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
new file mode 100644
index 00000000..9c176899
--- /dev/null
+++ 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"