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