diff --git a/sentry_sdk/api.py b/sentry_sdk/api.py index 9a6da5cac5..80fc245c16 100644 --- a/sentry_sdk/api.py +++ b/sentry_sdk/api.py @@ -29,9 +29,9 @@ ExcInfo, MeasurementUnit, LogLevelStr, + SamplingContext, ) - from sentry_sdk.scope import StartTransactionKwargs - from sentry_sdk.tracing import Span + from sentry_sdk.tracing import Span, TransactionKwargs T = TypeVar("T") F = TypeVar("F", bound=Callable[..., Any]) @@ -284,11 +284,12 @@ def start_span( def start_transaction( transaction=None, # type: Optional[Transaction] instrumenter=INSTRUMENTER.SENTRY, # type: str - **kwargs, # type: Unpack[StartTransactionKwargs] + custom_sampling_context=None, # type: Optional[SamplingContext] + **kwargs, # type: Unpack[TransactionKwargs] ): # type: (...) -> Union[Transaction, NoOpSpan] return Scope.get_current_scope().start_transaction( - transaction, instrumenter, **kwargs + transaction, instrumenter, custom_sampling_context, **kwargs ) diff --git a/sentry_sdk/hub.py b/sentry_sdk/hub.py index 8ac2348597..f5a87113c2 100644 --- a/sentry_sdk/hub.py +++ b/sentry_sdk/hub.py @@ -42,9 +42,10 @@ BreadcrumbHint, ExcInfo, LogLevelStr, + SamplingContext, ) from sentry_sdk.consts import ClientConstructor - from sentry_sdk.scope import StartTransactionKwargs + from sentry_sdk.tracing import TransactionKwargs T = TypeVar("T") @@ -472,9 +473,13 @@ def start_span(self, instrumenter=INSTRUMENTER.SENTRY, **kwargs): return scope.start_span(instrumenter=instrumenter, **kwargs) def start_transaction( - self, transaction=None, instrumenter=INSTRUMENTER.SENTRY, **kwargs + self, + transaction=None, + instrumenter=INSTRUMENTER.SENTRY, + custom_sampling_context=None, + **kwargs ): - # type: (Optional[Transaction], str, Unpack[StartTransactionKwargs]) -> Union[Transaction, NoOpSpan] + # type: (Optional[Transaction], str, Optional[SamplingContext], Unpack[TransactionKwargs]) -> Union[Transaction, NoOpSpan] """ .. deprecated:: 2.0.0 This function is deprecated and will be removed in a future release. @@ -511,7 +516,7 @@ def start_transaction( kwargs["hub"] = scope # type: ignore return scope.start_transaction( - transaction=transaction, instrumenter=instrumenter, **kwargs + transaction, instrumenter, custom_sampling_context, **kwargs ) def continue_trace(self, environ_or_headers, op=None, name=None, source=None): diff --git a/sentry_sdk/scope.py b/sentry_sdk/scope.py index b173e13303..3bcf99579c 100644 --- a/sentry_sdk/scope.py +++ b/sentry_sdk/scope.py @@ -70,10 +70,6 @@ import sentry_sdk - class StartTransactionKwargs(TransactionKwargs, total=False): - client: Optional["sentry_sdk.Client"] - custom_sampling_context: SamplingContext - P = ParamSpec("P") R = TypeVar("R") @@ -966,9 +962,13 @@ def add_breadcrumb(self, crumb=None, hint=None, **kwargs): self._breadcrumbs.popleft() def start_transaction( - self, transaction=None, instrumenter=INSTRUMENTER.SENTRY, **kwargs + self, + transaction=None, + instrumenter=INSTRUMENTER.SENTRY, + custom_sampling_context=None, + **kwargs ): - # type: (Optional[Transaction], str, Unpack[StartTransactionKwargs]) -> Union[Transaction, NoOpSpan] + # type: (Optional[Transaction], str, Optional[SamplingContext], Unpack[TransactionKwargs]) -> Union[Transaction, NoOpSpan] """ Start and return a transaction. @@ -991,7 +991,13 @@ def start_transaction( When the transaction is finished, it will be sent to Sentry with all its finished child spans. - For supported `**kwargs` see :py:class:`sentry_sdk.tracing.Transaction`. + :param transaction: The transaction to start. If omitted, we create and + start a new transaction. + :param instrumenter: This parameter is meant for internal use only. + :param custom_sampling_context: The transaction's custom sampling context. + :param kwargs: Optional keyword arguments to be passed to the Transaction + constructor. See :py:class:`sentry_sdk.tracing.Transaction` for + available arguments. """ kwargs.setdefault("scope", self) @@ -1002,7 +1008,7 @@ def start_transaction( if instrumenter != configuration_instrumenter: return NoOpSpan() - custom_sampling_context = kwargs.pop("custom_sampling_context", {}) + custom_sampling_context = custom_sampling_context or {} # kwargs at this point has type TransactionKwargs, since we have removed # the client and custom_sampling_context from it. diff --git a/sentry_sdk/tracing.py b/sentry_sdk/tracing.py index 8c8d7f08e2..54444dce7c 100644 --- a/sentry_sdk/tracing.py +++ b/sentry_sdk/tracing.py @@ -32,23 +32,69 @@ class SpanKwargs(TypedDict, total=False): trace_id: str + """ + The trace ID of the root span. If this new span is to be the root span, + omit this parameter, and a new trace ID will be generated. + """ + span_id: str + """The span ID of this span. If omitted, a new span ID will be generated.""" + parent_span_id: str + """The span ID of the parent span, if applicable.""" + same_process_as_parent: bool + """Whether this span is in the same process as the parent span.""" + sampled: bool + """ + Whether the span should be sampled. Overrides the default sampling decision + for this span when provided. + """ + op: str + """ + The span's operation. A list of recommended values is available here: + https://develop.sentry.dev/sdk/performance/span-operations/ + """ + description: str - # hub: Optional[sentry_sdk.Hub] is deprecated, and therefore omitted here! + """A description of what operation is being performed within the span.""" + + hub: Optional["sentry_sdk.Hub"] + """The hub to use for this span. This argument is DEPRECATED. Please use the `scope` parameter, instead.""" + status: str + """The span's status. Possible values are listed at https://develop.sentry.dev/sdk/event-payloads/span/""" + containing_transaction: Optional["Transaction"] + """The transaction that this span belongs to.""" + start_timestamp: Optional[Union[datetime, float]] + """ + The timestamp when the span started. If omitted, the current time + will be used. + """ + scope: "sentry_sdk.Scope" + """The scope to use for this span. If not provided, we use the current scope.""" class TransactionKwargs(SpanKwargs, total=False): name: str + """Identifier of the transaction. Will show up in the Sentry UI.""" + source: str + """ + A string describing the source of the transaction name. This will be used to determine the transaction's type. + See https://develop.sentry.dev/sdk/event-payloads/transaction/#transaction-annotations for more information. + Default "custom". + """ + parent_sampled: bool + """Whether the parent transaction was sampled. If True this transaction will be kept, if False it will be discarded.""" + baggage: "Baggage" + """The W3C baggage header value. (see https://www.w3.org/TR/baggage/)""" BAGGAGE_HEADER_NAME = "baggage" @@ -107,7 +153,29 @@ def add(self, span): class Span: """A span holds timing information of a block of code. - Spans can have multiple child spans thus forming a span tree.""" + Spans can have multiple child spans thus forming a span tree. + + :param trace_id: The trace ID of the root span. If this new span is to be the root span, + omit this parameter, and a new trace ID will be generated. + :param span_id: The span ID of this span. If omitted, a new span ID will be generated. + :param parent_span_id: The span ID of the parent span, if applicable. + :param same_process_as_parent: Whether this span is in the same process as the parent span. + :param sampled: Whether the span should be sampled. Overrides the default sampling decision + for this span when provided. + :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. + :param hub: The hub to use for this span. + + .. deprecated:: 2.0.0 + Please use the `scope` parameter, instead. + :param status: The span's status. Possible values are listed at + https://develop.sentry.dev/sdk/event-payloads/span/ + :param containing_transaction: The transaction that this span belongs to. + :param start_timestamp: The timestamp when the span started. If omitted, the current time + will be used. + :param scope: The scope to use for this span. If not provided, we use the current scope. + """ __slots__ = ( "trace_id",