docs: Document Transaction and Span kwargs typed dicts

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
     )
 
 

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):

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.

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",