Skip to content

Commit b1b16b0

Browse files
antonpirkerantonpirker
authored
Added name parameter to start_span() and deprecated description parameter. (#3524)
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)
1 parent a581542 commit b1b16b0

4 files changed

Lines changed: 85 additions & 10 deletions

File tree

‎sentry_sdk/scope.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import os
22
import sys
3+
import warnings
34
from copy import copy
45
from collections import deque
56
from contextlib import contextmanager
@@ -1067,6 +1068,13 @@ def start_span(self, instrumenter=INSTRUMENTER.SENTRY, **kwargs):
10671068
be removed in the next major version. Going forward, it should only
10681069
be used by the SDK itself.
10691070
"""
1071+
if kwargs.get("description") is not None:
1072+
warnings.warn(
1073+
"The `description` parameter is deprecated. Please use `name` instead.",
1074+
DeprecationWarning,
1075+
stacklevel=2,
1076+
)
1077+
10701078
with new_scope():
10711079
kwargs.setdefault("scope", self)
10721080

‎sentry_sdk/tracing.py‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ class SpanKwargs(TypedDict, total=False):
7070
"""
7171

7272
description: str
73-
"""A description of what operation is being performed within the span."""
73+
"""A description of what operation is being performed within the span. This argument is DEPRECATED. Please use the `name` parameter, instead."""
7474

7575
hub: Optional["sentry_sdk.Hub"]
7676
"""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):
9797
Default "manual".
9898
"""
9999

100-
class TransactionKwargs(SpanKwargs, total=False):
101100
name: str
102-
"""Identifier of the transaction. Will show up in the Sentry UI."""
101+
"""A string describing what operation is being performed within the span/transaction."""
103102

103+
class TransactionKwargs(SpanKwargs, total=False):
104104
source: str
105105
"""
106106
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:
227227
:param op: The span's operation. A list of recommended values is available here:
228228
https://develop.sentry.dev/sdk/performance/span-operations/
229229
:param description: A description of what operation is being performed within the span.
230+
231+
.. deprecated:: 2.X.X
232+
Please use the `name` parameter, instead.
233+
:param name: A string describing what operation is being performed within the span.
230234
:param hub: The hub to use for this span.
231235
232236
.. deprecated:: 2.0.0
@@ -261,6 +265,7 @@ class Span:
261265
"_local_aggregator",
262266
"scope",
263267
"origin",
268+
"name",
264269
)
265270

266271
def __init__(
@@ -278,6 +283,7 @@ def __init__(
278283
start_timestamp=None, # type: Optional[Union[datetime, float]]
279284
scope=None, # type: Optional[sentry_sdk.Scope]
280285
origin="manual", # type: str
286+
name=None, # type: Optional[str]
281287
):
282288
# type: (...) -> None
283289
self.trace_id = trace_id or uuid.uuid4().hex
@@ -286,7 +292,7 @@ def __init__(
286292
self.same_process_as_parent = same_process_as_parent
287293
self.sampled = sampled
288294
self.op = op
289-
self.description = description
295+
self.description = name or description
290296
self.status = status
291297
self.hub = hub # backwards compatibility
292298
self.scope = scope
@@ -400,6 +406,13 @@ def start_child(self, instrumenter=INSTRUMENTER.SENTRY, **kwargs):
400406
be removed in the next major version. Going forward, it should only
401407
be used by the SDK itself.
402408
"""
409+
if kwargs.get("description") is not None:
410+
warnings.warn(
411+
"The `description` parameter is deprecated. Please use `name` instead.",
412+
DeprecationWarning,
413+
stacklevel=2,
414+
)
415+
403416
configuration_instrumenter = sentry_sdk.get_client().options["instrumenter"]
404417

405418
if instrumenter != configuration_instrumenter:
@@ -750,7 +763,7 @@ class Transaction(Span):
750763
"_baggage",
751764
)
752765

753-
def __init__(
766+
def __init__( # type: ignore[misc]
754767
self,
755768
name="", # type: str
756769
parent_sampled=None, # type: Optional[bool]

‎tests/tracing/test_misc.py‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,6 @@ def test_transaction_naming(sentry_init, capture_events):
3636
sentry_init(traces_sample_rate=1.0)
3737
events = capture_events()
3838

39-
# only transactions have names - spans don't
40-
with pytest.raises(TypeError):
41-
start_span(name="foo")
42-
assert len(events) == 0
43-
4439
# default name in event if no name is passed
4540
with start_transaction() as transaction:
4641
pass

‎tests/tracing/test_span_name.py‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
import pytest
2+
3+
import sentry_sdk
4+
5+
6+
def test_start_span_description(sentry_init, capture_events):
7+
sentry_init(traces_sample_rate=1.0)
8+
events = capture_events()
9+
10+
with sentry_sdk.start_transaction(name="hi"):
11+
with pytest.deprecated_call():
12+
with sentry_sdk.start_span(op="foo", description="span-desc"):
13+
...
14+
15+
(event,) = events
16+
17+
assert event["spans"][0]["description"] == "span-desc"
18+
19+
20+
def test_start_span_name(sentry_init, capture_events):
21+
sentry_init(traces_sample_rate=1.0)
22+
events = capture_events()
23+
24+
with sentry_sdk.start_transaction(name="hi"):
25+
with sentry_sdk.start_span(op="foo", name="span-name"):
26+
...
27+
28+
(event,) = events
29+
30+
assert event["spans"][0]["description"] == "span-name"
31+
32+
33+
def test_start_child_description(sentry_init, capture_events):
34+
sentry_init(traces_sample_rate=1.0)
35+
events = capture_events()
36+
37+
with sentry_sdk.start_transaction(name="hi"):
38+
with pytest.deprecated_call():
39+
with sentry_sdk.start_span(op="foo", description="span-desc") as span:
40+
with span.start_child(op="bar", description="child-desc"):
41+
...
42+
43+
(event,) = events
44+
45+
assert event["spans"][-1]["description"] == "child-desc"
46+
47+
48+
def test_start_child_name(sentry_init, capture_events):
49+
sentry_init(traces_sample_rate=1.0)
50+
events = capture_events()
51+
52+
with sentry_sdk.start_transaction(name="hi"):
53+
with sentry_sdk.start_span(op="foo", name="span-name") as span:
54+
with span.start_child(op="bar", name="child-name"):
55+
...
56+
57+
(event,) = events
58+
59+
assert event["spans"][-1]["description"] == "child-name"

0 commit comments

Comments
 (0)