ref(am): Introduce start_transaction

sentry_sdk/api.py

@@ -17,7 +17,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])
@@ -38,6 +38,7 @@ def overload(x):
  "flush",
  "last_event_id",
  "start_span",
+ "start_transaction",
  "set_tag",
  "set_context",
  "set_extra",
@@ -255,3 +256,15 @@ def start_span(
  # TODO: All other functions in this module check for
  # `Hub.current is None`. That actually should never happen?
  return Hub.current.start_span(span=span, **kwargs)
+
+
+@hubmethod
+def start_transaction(
+ span_or_name=None, # type: Optional[Union[Span, str]]
+ **kwargs # type: Any
+):
+ # type: (...) -> Transaction
+
+ # TODO: All other functions in this module check for
+ # `Hub.current is None`. That actually should never happen?
+ return Hub.current.start_transaction(span_or_name=span_or_name, **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,56 @@ 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,
+ span_or_name=None, # type: Optional[Union[Span, str]]
+ **kwargs # type: Any
+ ):
+ # type: (...) -> Transaction
+ """
+ Create a new transaction detached from the current span. The return
+ value is the `Transaction` object which for the most part works like a
+ span.
+ """
+
+ kwargs.setdefault("hub", self)
+
+ if isinstance(span_or_name, str):
+ if "name" in kwargs:
+ raise ValueError("Cannot specify transaction name twice.")
+ kwargs["name"] = span_or_name
+ transaction = Transaction(**kwargs)
+
+ elif span_or_name is None and "name" in kwargs:
+ transaction = Transaction(**kwargs)
+
+ elif isinstance(span_or_name, Transaction):
+ transaction = span_or_name
+
+ elif span_or_name is None and "span" in kwargs:
+ transaction = kwargs.pop("span")
+
+ else:
+ raise ValueError("transaction object or name required.")
+
+ 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,
@@ -85,13 +85,15 @@ 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"
+ span = 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(span):
  try:
  response = await old_handle(self, request)
  except HTTPException as e:

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,17 @@ 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)
+ span = Transaction.continue_from_headers(
+ dict(scope["headers"]),
+ name=_DEFAULT_TRANSACTION_NAME,
+ op="{}.server".format(ty),
+ )
  else:
- span = Span()
- span.op = "asgi.server"
+ span = Transaction(name=_DEFAULT_TRANSACTION_NAME, op="asgi.server")
 
  span.set_tag("asgi.type", ty)
- span.transaction = _DEFAULT_TRANSACTION_NAME
 
- with hub.start_span(span) as span:
+ with hub.start_transaction(span):
  # 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"
+ span = 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")
 
  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
+ span.name = task.name
 
- with hub.start_span(span):
+ with hub.start_transaction(span):
  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 {}
+ span = 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
+ span.name = job.func_name
 
- with hub.start_span(span):
+ with hub.start_transaction(span):
  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,11 +113,11 @@ 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"
+ span = Transaction.continue_from_environ(
+  environ, op="http.server", name="generic WSGI request"
+ )
 
- with hub.start_span(span) as span:
+ with hub.start_transaction(span) as span:
  try:
  rv = self.app(
  environ,
@@ -133,7 +133,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