diff --git a/sentry_sdk/scope.py b/sentry_sdk/scope.py index b6a23253e8..adae8dc888 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 @@ 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 index 41525b4676..036e6619f6 100644 --- 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 index 02966642fd..de2f782538 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 0000000000..9c1768990a --- /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"