ref(am): Introduce start_transaction

sentry_sdk/api.py

@@ -16,7 +16,7 @@
     from typing import Union
 
     from sentry_sdk._types import Event, Hint, Breadcrumb, BreadcrumbHint, ExcInfo
-    from sentry_sdk.tracing import Span
+    from sentry_sdk.tracing import Span, Transaction
 
     T = TypeVar("T")
     F = TypeVar("F", bound=Callable[..., Any])
@@ -37,6 +37,7 @@ def overload(x):
     "flush",
     "last_event_id",
     "start_span",
+    "start_transaction",
     "set_tag",
     "set_context",
     "set_extra",
@@ -201,3 +202,12 @@ def start_span(
 ):
     # type: (...) -> Span
     return Hub.current.start_span(span=span, **kwargs)
+
+
+@hubmethod
+def start_transaction(
+    transaction=None,  # type: Optional[Transaction]
+    **kwargs  # type: Any
+):
+    # type: (...) -> Transaction
+    return Hub.current.start_transaction(transaction, **kwargs)

sentry_sdk/hub.py

@@ -8,7 +8,7 @@
 from sentry_sdk._compat import with_metaclass
 from sentry_sdk.scope import Scope
 from sentry_sdk.client import Client
-from sentry_sdk.tracing import Span
+from sentry_sdk.tracing import Span, Transaction
 from sentry_sdk.sessions import Session
 from sentry_sdk.utils import (
     exc_info_from_error,
@@ -445,10 +445,9 @@ def start_span(
         span, if any. The return value is the span object that can
         be used as a context manager to start and stop timing.
 
-        Note that you will not see any span that is not contained
-        within a transaction. Create a transaction with
-        ``start_span(transaction="my transaction")`` if an
-        integration doesn't already do this for you.
+        Note that you will not see any span that is not contained within a
+        transaction. Most integrations already do this for you, but create a
+        transaction with `start_transaction` otherwise.
         """
 
         client, scope = self._stack[-1]
@@ -462,17 +461,63 @@ def start_span(
             else:
                 span = Span(**kwargs)
 
-        if span.sampled is None and span.transaction is not None:
+        elif isinstance(span, Transaction):
+            raise ValueError("Pass transactions to start_transaction instead")
+
+        return span
+
+    def start_transaction(
+        self,
+        transaction=None,  # type: Optional[Transaction]
+        **kwargs  # type: Any
+    ):
+        # type: (...) -> Transaction
+        """
+        Start and return a transaction.
+
+        Start an existing transaction if given, otherwise create and start a new
+        transaction with kwargs.
+        """
+        # XXX: should we always set transaction.hub = self?
+        # In a multi-hub program, what does it mean to write
+        #     hub1.start_transaction(Transaction(hub=hub2))
+        # ? Should the transaction be on hub1 or hub2?
+
+        # XXX: it is strange that both start_span and start_transaction take
+        # kwargs, but those are ignored if span/transaction are not None.
+        # Code such as:
+        #     hub.start_transaction(Transaction(name="foo"), name="bar")
+        #
+        # is clearly weird, but not so weird if we intentionally want to rename
+        # a transaction we got from somewhere else:
+        #     hub.start_transaction(transaction, name="new_name")
+        #
+        # Would be clearer if Hub was not involved:
+        #     transaction.name = "new_name"
+        #     with transaction:  # __enter__ => start, __exit__ => finish
+        #         with transaction.start_child(...):
+        #             pass
+        #         # alternatively, rely on transaction being in the current scope
+        #         with Span(...):
+        #             pass
+
+        if transaction is None:
+            kwargs.setdefault("hub", self)
+            transaction = Transaction(**kwargs)
+
+        client, scope = self._stack[-1]
+
+        if transaction.sampled is None:
             sample_rate = client and client.options["traces_sample_rate"] or 0
-            span.sampled = random.random() < sample_rate
+            transaction.sampled = random.random() < sample_rate
 
-        if span.sampled:
+        if transaction.sampled:
             max_spans = (
                 client and client.options["_experiments"].get("max_spans") or 1000
             )
-            span.init_finished_spans(maxlen=max_spans)
+            transaction.init_span_recorder(maxlen=max_spans)
 
-        return span
+        return transaction
 
     @overload  # noqa
     def push_scope(

sentry_sdk/integrations/aiohttp.py

@@ -9,7 +9,7 @@
     _filter_headers,
     request_body_within_bounds,
 )
-from sentry_sdk.tracing import Span
+from sentry_sdk.tracing import Transaction
 from sentry_sdk.utils import (
     capture_internal_exceptions,
     event_from_exception,
@@ -87,27 +87,29 @@ async def sentry_app_handle(self, request, *args, **kwargs):
                     scope.clear_breadcrumbs()
                     scope.add_event_processor(_make_request_processor(weak_request))
 
-                span = Span.continue_from_headers(request.headers)
-                span.op = "http.server"
-                # If this transaction name makes it to the UI, AIOHTTP's
-                # URL resolver did not find a route or died trying.
-                span.transaction = "generic AIOHTTP request"
+                transaction = Transaction.continue_from_headers(
+                    request.headers,
+                    op="http.server",
+                    # If this transaction name makes it to the UI, AIOHTTP's
+                    # URL resolver did not find a route or died trying.
+                    name="generic AIOHTTP request",
+                )
 
-                with hub.start_span(span):
+                with hub.start_transaction(transaction):
                     try:
                         response = await old_handle(self, request)
                     except HTTPException as e:
-                        span.set_http_status(e.status_code)
+                        transaction.set_http_status(e.status_code)
                         raise
                     except asyncio.CancelledError:
-                        span.set_status("cancelled")
+                        transaction.set_status("cancelled")
                         raise
                     except Exception:
                         # This will probably map to a 500 but seems like we
                         # have no way to tell. Do not set span status.
                         reraise(*_capture_exception(hub))
 
-                    span.set_http_status(response.status)
+                    transaction.set_http_status(response.status)
                     return response
 
         Application._handle = sentry_app_handle

sentry_sdk/integrations/asgi.py

@@ -19,7 +19,7 @@
     HAS_REAL_CONTEXTVARS,
     CONTEXTVARS_ERROR_MESSAGE,
 )
-from sentry_sdk.tracing import Span
+from sentry_sdk.tracing import Transaction
 
 if MYPY:
     from typing import Dict
@@ -123,16 +123,19 @@ async def _run_app(self, scope, callback):
                 ty = scope["type"]
 
                 if ty in ("http", "websocket"):
-                    span = Span.continue_from_headers(dict(scope["headers"]))
-                    span.op = "{}.server".format(ty)
+                    transaction = Transaction.continue_from_headers(
+                        dict(scope["headers"]),
+                        name=_DEFAULT_TRANSACTION_NAME,
+                        op="{}.server".format(ty),
+                    )
                 else:
-                    span = Span()
-                    span.op = "asgi.server"
+                    transaction = Transaction(
+                        name=_DEFAULT_TRANSACTION_NAME, op="asgi.server"
+                    )
 
-                span.set_tag("asgi.type", ty)
-                span.transaction = _DEFAULT_TRANSACTION_NAME
+                transaction.set_tag("asgi.type", ty)
 
-                with hub.start_span(span) as span:
+                with hub.start_transaction(transaction):
                     # XXX: Would be cool to have correct span status, but we
                     # would have to wrap send(). That is a bit hard to do with
                     # the current abstraction over ASGI 2/3.

sentry_sdk/integrations/celery.py

@@ -4,7 +4,7 @@
 
 from sentry_sdk.hub import Hub
 from sentry_sdk.utils import capture_internal_exceptions, event_from_exception
-from sentry_sdk.tracing import Span
+from sentry_sdk.tracing import Transaction
 from sentry_sdk._compat import reraise
 from sentry_sdk.integrations import Integration, DidNotEnable
 from sentry_sdk.integrations.logging import ignore_logger
@@ -130,19 +130,21 @@ def _inner(*args, **kwargs):
             scope.clear_breadcrumbs()
             scope.add_event_processor(_make_event_processor(task, *args, **kwargs))
 
-            span = Span.continue_from_headers(args[3].get("headers") or {})
-            span.op = "celery.task"
-            span.transaction = "unknown celery task"
+            transaction = Transaction.continue_from_headers(
+                args[3].get("headers") or {},
+                op="celery.task",
+                name="unknown celery task",
+            )
 
             # Could possibly use a better hook than this one
-            span.set_status("ok")
+            transaction.set_status("ok")
 
             with capture_internal_exceptions():
                 # Celery task objects are not a thing to be trusted. Even
                 # something such as attribute access can fail.
-                span.transaction = task.name
+                transaction.name = task.name
 
-            with hub.start_span(span):
+            with hub.start_transaction(transaction):
                 return f(*args, **kwargs)
 
     return _inner  # type: ignore

sentry_sdk/integrations/rq.py

@@ -4,7 +4,7 @@
 
 from sentry_sdk.hub import Hub
 from sentry_sdk.integrations import Integration, DidNotEnable
-from sentry_sdk.tracing import Span
+from sentry_sdk.tracing import Transaction
 from sentry_sdk.utils import capture_internal_exceptions, event_from_exception
 
 
@@ -61,15 +61,16 @@ def sentry_patched_perform_job(self, job, *args, **kwargs):
                 scope.clear_breadcrumbs()
                 scope.add_event_processor(_make_event_processor(weakref.ref(job)))
 
-                span = Span.continue_from_headers(
-                    job.meta.get("_sentry_trace_headers") or {}
+                transaction = Transaction.continue_from_headers(
+                    job.meta.get("_sentry_trace_headers") or {},
+                    op="rq.task",
+                    name="unknown RQ task",
                 )
-                span.op = "rq.task"
 
                 with capture_internal_exceptions():
-                    span.transaction = job.func_name
+                    transaction.name = job.func_name
 
-                with hub.start_span(span):
+                with hub.start_transaction(transaction):
                     rv = old_perform_job(self, job, *args, **kwargs)
 
             if self.is_horse:

sentry_sdk/integrations/wsgi.py

@@ -8,7 +8,7 @@
     event_from_exception,
 )
 from sentry_sdk._compat import PY2, reraise, iteritems
-from sentry_sdk.tracing import Span
+from sentry_sdk.tracing import Transaction
 from sentry_sdk.sessions import auto_session_tracking
 from sentry_sdk.integrations._wsgi_common import _filter_headers
 
@@ -113,15 +113,17 @@ def __call__(self, environ, start_response):
                                 _make_wsgi_event_processor(environ)
                             )
 
-                    span = Span.continue_from_environ(environ)
-                    span.op = "http.server"
-                    span.transaction = "generic WSGI request"
+                    transaction = Transaction.continue_from_environ(
+                        environ, op="http.server", name="generic WSGI request"
+                    )
 
-                    with hub.start_span(span) as span:
+                    with hub.start_transaction(transaction) as transaction:
                         try:
                             rv = self.app(
                                 environ,
-                                partial(_sentry_start_response, start_response, span),
+                                partial(
+                                    _sentry_start_response, start_response, transaction
+                                ),
                             )
                         except BaseException:
                             reraise(*_capture_exception(hub))
@@ -133,7 +135,7 @@ def __call__(self, environ, start_response):
 
 def _sentry_start_response(
     old_start_response,  # type: StartResponse
-    span,  # type: Span
+    span,  # type: Transaction
     status,  # type: str
     response_headers,  # type: WsgiResponseHeaders
     exc_info=None,  # type: Optional[WsgiExcInfo]

sentry_sdk/scope.py

@@ -5,6 +5,7 @@
 from sentry_sdk._functools import wraps
 from sentry_sdk._types import MYPY
 from sentry_sdk.utils import logger, capture_internal_exceptions
+from sentry_sdk.tracing import Transaction
 
 if MYPY:
     from typing import Any
@@ -140,8 +141,8 @@ def transaction(self, value):
         """When set this forces a specific transaction name to be set."""
         self._transaction = value
         span = self._span
-        if span:
-            span.transaction = value
+        if span and isinstance(span, Transaction) and value:
+            span.name = value
 
     @_attr_setter
     def user(self, value):
@@ -166,8 +167,8 @@ def span(self):
     def span(self, span):
         # type: (Optional[Span]) -> None
         self._span = span
-        if span is not None:
-            span_transaction = span.transaction
+        if isinstance(span, Transaction):
+            span_transaction = span.name
             if span_transaction:
                 self._transaction = span_transaction