ref: Improve start_transaction docs

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.