class Hub(with_metaclass(HubMeta)): # type: ignore
"""The hub wraps the concurrency management of the SDK. Each thread has
its own hub but the hub might transfer with the flow of execution if
context vars are available.
If the hub is used with a with statement it's temporarily activated.
"""
_stack = None # type: List[Tuple[Optional[Client], Scope]]
# Mypy doesn't pick up on the metaclass.
if MYPY:
current = None # type: Hub
main = None # type: Hub
def __init__(
self,
client_or_hub=None, # type: Optional[Union[Hub, Client]]
scope=None, # type: Optional[Any]
):
# type: (...) -> None
if isinstance(client_or_hub, Hub):
hub = client_or_hub
client, other_scope = hub._stack[-1]
if scope is None:
scope = copy.copy(other_scope)
else:
client = client_or_hub
if scope is None:
scope = Scope()
self._stack = [(client, scope)]
self._last_event_id = None # type: Optional[str]
self._old_hubs = [] # type: List[Hub]
def __enter__(self):
# type: () -> Hub
self._old_hubs.append(Hub.current)
_local.set(self)
return self
def __exit__(
self,
exc_type, # type: Optional[type]
exc_value, # type: Optional[BaseException]
tb, # type: Optional[Any]
):
# type: (...) -> None
old = self._old_hubs.pop()
_local.set(old)
def run(
self,
callback # type: Callable[[], T]
):
# type: (...) -> T
"""Runs a callback in the context of the hub. Alternatively the
with statement can be used on the hub directly.
"""
with self:
return callback()
def get_integration(
self,
name_or_class # type: Union[str, Type[Integration]]
):
# type: (...) -> Any
"""Returns the integration for this hub by name or class. If there
is no client bound or the client does not have that integration
then `None` is returned.
If the return value is not `None` the hub is guaranteed to have a
client attached.
"""
if isinstance(name_or_class, str):
integration_name = name_or_class
elif name_or_class.identifier is not None:
integration_name = name_or_class.identifier
else:
raise ValueError("Integration has no name")
client = self.client
if client is not None:
rv = client.integrations.get(integration_name)
if rv is not None:
return rv
@property
def client(self):
# type: () -> Optional[Client]
"""Returns the current client on the hub."""
return self._stack[-1][0]
@property
def scope(self):
# type: () -> Scope
"""Returns the current scope on the hub."""
return self._stack[-1][1]
def last_event_id(self):
# type: () -> Optional[str]
"""Returns the last event ID."""
return self._last_event_id
def bind_client(
self,
new # type: Optional[Client]
):
# type: (...) -> None
"""Binds a new client to the hub."""
top = self._stack[-1]
self._stack[-1] = (new, top[1])
def capture_event(
self,
event, # type: Event
hint=None, # type: Optional[Hint]
scope=None, # type: Optional[Any]
**scope_args # type: Dict[str, Any]
):
# type: (...) -> Optional[str]
"""Captures an event. Alias of :py:meth:`sentry_sdk.Client.capture_event`.
"""
client, top_scope = self._stack[-1]
scope = _update_scope(top_scope, scope, scope_args)
if client is not None:
rv = client.capture_event(event, hint, scope)
if rv is not None:
self._last_event_id = rv
return rv
return None
def capture_message(
self,
message, # type: str
level=None, # type: Optional[str]
scope=None, # type: Optional[Any]
**scope_args # type: Dict[str, Any]
):
# type: (...) -> Optional[str]
"""Captures a message. The message is just a string. If no level
is provided the default level is `info`.
:returns: An `event_id` if the SDK decided to send the event (see :py:meth:`sentry_sdk.Client.capture_event`).
"""
if self.client is None:
return None
if level is None:
level = "info"
return self.capture_event({
"message": message,
"level": level
},
scope=scope,
**scope_args)
def capture_exception(
self,
error=None, # type: Optional[Union[BaseException, ExcInfo]]
scope=None, # type: Optional[Any]
**scope_args # type: Dict[str, Any]
):
# type: (...) -> Optional[str]
"""Captures an exception.
:param error: An exception to catch. If `None`, `sys.exc_info()` will be used.
:returns: An `event_id` if the SDK decided to send the event (see :py:meth:`sentry_sdk.Client.capture_event`).
"""
client = self.client
if client is None:
return None
if error is not None:
exc_info = exc_info_from_error(error)
else:
exc_info = sys.exc_info()
event, hint = event_from_exception(exc_info,
client_options=client.options)
try:
return self.capture_event(event,
hint=hint,
scope=scope,
**scope_args)
except Exception:
self._capture_internal_exception(sys.exc_info())
return None
def _capture_internal_exception(
self,
exc_info # type: Any
):
# type: (...) -> Any
"""
Capture an exception that is likely caused by a bug in the SDK
itself.
These exceptions do not end up in Sentry and are just logged instead.
"""
logger.error("Internal error in sentry_sdk", exc_info=exc_info)
def add_breadcrumb(
self,
crumb=None, # type: Optional[Breadcrumb]
hint=None, # type: Optional[BreadcrumbHint]
**kwargs # type: Any
):
# type: (...) -> None
"""
Adds a breadcrumb.
:param crumb: Dictionary with the data as the sentry v7/v8 protocol expects.
:param hint: An optional value that can be used by `before_breadcrumb`
to customize the breadcrumbs that are emitted.
"""
client, scope = self._stack[-1]
if client is None:
logger.info("Dropped breadcrumb because no client bound")
return
crumb = dict(crumb or ()) # type: Breadcrumb
crumb.update(kwargs)
if not crumb:
return
hint = dict(hint or ()) # type: Hint
if crumb.get("timestamp") is None:
crumb["timestamp"] = datetime.utcnow()
if crumb.get("type") is None:
crumb["type"] = "default"
if client.options["before_breadcrumb"] is not None:
new_crumb = client.options["before_breadcrumb"](crumb, hint)
else:
new_crumb = crumb
if new_crumb is not None:
scope._breadcrumbs.append(new_crumb)
else:
logger.info("before breadcrumb dropped breadcrumb (%s)", crumb)
max_breadcrumbs = client.options["max_breadcrumbs"] # type: int
while len(scope._breadcrumbs) > max_breadcrumbs:
scope._breadcrumbs.popleft()
def start_span(
self,
span=None, # type: Optional[Span]
**kwargs # type: Any
):
# type: (...) -> Span
"""
Create a new span whose parent span is the currently active
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.
"""
client, scope = self._stack[-1]
kwargs.setdefault("hub", self)
if span is None:
span = scope.span
if span is not None:
span = span.new_span(**kwargs)
else:
span = Span(**kwargs)
if span.sampled is None and span.transaction is not None:
sample_rate = client and client.options["traces_sample_rate"] or 0
span.sampled = random.random() < sample_rate
if span.sampled:
max_spans = (client
and client.options["_experiments"].get("max_spans")
or 1000)
span.init_finished_spans(maxlen=max_spans)
return span
@overload # noqa
def push_scope(
self,
callback=None # type: Optional[None]
):
# type: (...) -> ContextManager[Scope]
pass
@overload # noqa
def push_scope(
self,
callback # type: Callable[[Scope], None]
):
# type: (...) -> None
pass
def push_scope( # noqa
self,
callback=None # type: Optional[Callable[[Scope], None]]
):
# type: (...) -> Optional[ContextManager[Scope]]
"""
Pushes a new layer on the scope stack.
:param callback: If provided, this method pushes a scope, calls
`callback`, and pops the scope again.
:returns: If no `callback` is provided, a context manager that should
be used to pop the scope again.
"""
if callback is not None:
with self.push_scope() as scope:
callback(scope)
return None
client, scope = self._stack[-1]
new_layer = (client, copy.copy(scope))
self._stack.append(new_layer)
return _ScopeManager(self)
def pop_scope_unsafe(self):
# type: () -> Tuple[Optional[Client], Scope]
"""
Pops a scope layer from the stack.
Try to use the context manager :py:meth:`push_scope` instead.
"""
rv = self._stack.pop()
assert self._stack, "stack must have at least one layer"
return rv
@overload # noqa
def configure_scope(
self,
callback=None # type: Optional[None]
):
# type: (...) -> ContextManager[Scope]
pass
@overload # noqa
def configure_scope(
self,
callback # type: Callable[[Scope], None]
):
# type: (...) -> None
pass
def configure_scope( # noqa
self,
callback=None # type: Optional[Callable[[Scope], None]]
): # noqa
# type: (...) -> Optional[ContextManager[Scope]]
"""
Reconfigures the scope.
:param callback: If provided, call the callback with the current scope.
:returns: If no callback is provided, returns a context manager that returns the scope.
"""
client, scope = self._stack[-1]
if callback is not None:
if client is not None:
callback(scope)
return None
@contextmanager
def inner():
# type: () -> Generator[Scope, None, None]
if client is not None:
yield scope
else:
yield Scope()
return inner()
def start_session(self):
# type: (...) -> None
"""Starts a new session."""
self.end_session()
client, scope = self._stack[-1]
scope._session = Session(
release=client.options["release"] if client else None,
environment=client.options["environment"] if client else None,
user=scope._user,
)
def end_session(self):
# type: (...) -> None
"""Ends the current session if there is one."""
client, scope = self._stack[-1]
session = scope._session
if session is not None:
session.close()
if client is not None:
client.capture_session(session)
self.scope._session = None
def stop_auto_session_tracking(self):
# type: (...) -> None
"""Stops automatic session tracking.
This temporarily session tracking for the current scope when called.
To resume session tracking call `resume_auto_session_tracking`.
"""
self.end_session()
client, scope = self._stack[-1]
scope._force_auto_session_tracking = False
def resume_auto_session_tracking(self):
# type: (...) -> None
"""Resumes automatic session tracking for the current scope if
disabled earlier. This requires that generally automatic session
tracking is enabled.
"""
client, scope = self._stack[-1]
scope._force_auto_session_tracking = None
def flush(
self,
timeout=None, # type: Optional[float]
callback=None, # type: Optional[Callable[[int, float], None]]
):
# type: (...) -> None
"""
Alias for :py:meth:`sentry_sdk.Client.flush`
"""
client, scope = self._stack[-1]
if client is not None:
return client.flush(timeout=timeout, callback=callback)
def iter_trace_propagation_headers(self):
# type: () -> Generator[Tuple[str, str], None, None]
# TODO: Document
client, scope = self._stack[-1]
span = scope.span
if span is None:
return
propagate_traces = client and client.options["propagate_traces"]
if not propagate_traces:
return
if client and client.options["traceparent_v2"]:
traceparent = span.to_traceparent()
else:
traceparent = span.to_legacy_traceparent()
yield "sentry-trace", traceparent
class Hub(with_metaclass(HubMeta)): # type: ignore
"""The hub wraps the concurrency management of the SDK. Each thread has
its own hub but the hub might transfer with the flow of execution if
context vars are available.
If the hub is used with a with statement it's temporarily activated.
"""
_stack = None # type: List[Tuple[Optional[Client], Scope]]
# Mypy doesn't pick up on the metaclass.
if MYPY:
current = None # type: Hub
main = None # type: Hub
def __init__(
self,
client_or_hub=None, # type: Optional[Union[Hub, Client]]
scope=None, # type: Optional[Any]
):
# type: (...) -> None
if isinstance(client_or_hub, Hub):
hub = client_or_hub
client, other_scope = hub._stack[-1]
if scope is None:
scope = copy.copy(other_scope)
else:
client = client_or_hub
if scope is None:
scope = Scope()
self._stack = [(client, scope)]
self._last_event_id = None # type: Optional[str]
self._old_hubs = [] # type: List[Hub]
def __enter__(self):
# type: () -> Hub
self._old_hubs.append(Hub.current)
_local.set(self)
return self
def __exit__(
self,
exc_type, # type: Optional[type]
exc_value, # type: Optional[BaseException]
tb, # type: Optional[Any]
):
# type: (...) -> None
old = self._old_hubs.pop()
_local.set(old)
def run(
self,
callback # type: Callable[[], T]
):
# type: (...) -> T
"""Runs a callback in the context of the hub. Alternatively the
with statement can be used on the hub directly.
"""
with self:
return callback()
def get_integration(
self,
name_or_class # type: Union[str, Type[Integration]]
):
# type: (...) -> Any
"""Returns the integration for this hub by name or class. If there
is no client bound or the client does not have that integration
then `None` is returned.
If the return value is not `None` the hub is guaranteed to have a
client attached.
"""
if isinstance(name_or_class, str):
integration_name = name_or_class
elif name_or_class.identifier is not None:
integration_name = name_or_class.identifier
else:
raise ValueError("Integration has no name")
client = self._stack[-1][0]
if client is not None:
rv = client.integrations.get(integration_name)
if rv is not None:
return rv
if _initial_client is not None:
initial_client = _initial_client()
else:
initial_client = None
if (initial_client is not None and initial_client is not client and
initial_client.integrations.get(integration_name) is not None):
warning = ("Integration %r attempted to run but it was only "
"enabled on init() but not the client that "
"was bound to the current flow. Earlier versions of "
"the SDK would consider these integrations enabled but "
"this is no longer the case." % (name_or_class, ))
warn(Warning(warning), stacklevel=3)
logger.warning(warning)
@property
def client(self):
# type: () -> Optional[Client]
"""Returns the current client on the hub."""
return self._stack[-1][0]
def last_event_id(self):
# type: () -> Optional[str]
"""Returns the last event ID."""
return self._last_event_id
def bind_client(
self,
new # type: Optional[Client]
):
# type: (...) -> None
"""Binds a new client to the hub."""
top = self._stack[-1]
self._stack[-1] = (new, top[1])
def capture_event(
self,
event, # type: Event
hint=None, # type: Optional[Hint]
):
# type: (...) -> Optional[str]
"""Captures an event. Alias of :py:meth:`sentry_sdk.Client.capture_event`.
"""
client, scope = self._stack[-1]
if client is not None:
rv = client.capture_event(event, hint, scope)
if rv is not None:
self._last_event_id = rv
return rv
return None
def capture_message(
self,
message, # type: str
level=None, # type: Optional[str]
):
# type: (...) -> Optional[str]
"""Captures a message. The message is just a string. If no level
is provided the default level is `info`.
:returns: An `event_id` if the SDK decided to send the event (see :py:meth:`sentry_sdk.Client.capture_event`).
"""
if self.client is None:
return None
if level is None:
level = "info"
return self.capture_event({"message": message, "level": level})
def capture_exception(
self,
error=None # type: Optional[Union[BaseException, ExcInfo]]
):
# type: (...) -> Optional[str]
"""Captures an exception.
:param error: An exception to catch. If `None`, `sys.exc_info()` will be used.
:returns: An `event_id` if the SDK decided to send the event (see :py:meth:`sentry_sdk.Client.capture_event`).
"""
client = self.client
if client is None:
return None
if error is None:
exc_info = sys.exc_info()
else:
exc_info = exc_info_from_error(error)
event, hint = event_from_exception(exc_info,
client_options=client.options)
try:
return self.capture_event(event, hint=hint)
except Exception:
self._capture_internal_exception(sys.exc_info())
return None
def _capture_internal_exception(
self,
exc_info # type: Any
):
# type: (...) -> Any
"""
Capture an exception that is likely caused by a bug in the SDK
itself.
These exceptions do not end up in Sentry and are just logged instead.
"""
logger.error("Internal error in sentry_sdk",
exc_info=exc_info) # type: ignore
def add_breadcrumb(
self,
crumb=None, # type: Optional[Breadcrumb]
hint=None, # type: Optional[BreadcrumbHint]
**kwargs # type: Any
):
# type: (...) -> None
"""
Adds a breadcrumb.
:param crumb: Dictionary with the data as the sentry v7/v8 protocol expects.
:param hint: An optional value that can be used by `before_breadcrumb`
to customize the breadcrumbs that are emitted.
"""
client, scope = self._stack[-1]
if client is None:
logger.info("Dropped breadcrumb because no client bound")
return
crumb = dict(crumb or ()) # type: Breadcrumb
crumb.update(kwargs)
if not crumb:
return
hint = dict(hint or ()) # type: Hint
if crumb.get("timestamp") is None:
crumb["timestamp"] = datetime.utcnow()
if crumb.get("type") is None:
crumb["type"] = "default"
if client.options["before_breadcrumb"] is not None:
new_crumb = client.options["before_breadcrumb"](crumb, hint)
else:
new_crumb = crumb
if new_crumb is not None:
scope._breadcrumbs.append(new_crumb)
else:
logger.info("before breadcrumb dropped breadcrumb (%s)", crumb)
max_breadcrumbs = client.options["max_breadcrumbs"] # type: int
while len(scope._breadcrumbs) > max_breadcrumbs:
scope._breadcrumbs.popleft()
@contextmanager
def span(
self,
span=None, # type: Optional[Span]
**kwargs # type: Any
):
# type: (...) -> Generator[Span, None, None]
# TODO: Document
span = self.start_span(span=span, **kwargs)
_, scope = self._stack[-1]
old_span = scope.span
scope.span = span
try:
yield span
except Exception:
span.set_failure()
raise
else:
span.set_success()
finally:
try:
span.finish()
maybe_create_breadcrumbs_from_span(self, span)
self.finish_span(span)
except Exception:
self._capture_internal_exception(sys.exc_info())
scope.span = old_span
def start_span(
self,
span=None, # type: Optional[Span]
**kwargs # type: Any
):
# type: (...) -> Span
# TODO: Document
client, scope = self._stack[-1]
if span is None:
if scope.span is not None:
span = scope.span.new_span(**kwargs)
else:
span = Span(**kwargs)
if span.sampled is None and span.transaction is not None:
sample_rate = client and client.options["traces_sample_rate"] or 0
span.sampled = random.random() < sample_rate
if span.sampled:
span.init_finished_spans()
return span
def finish_span(
self,
span # type: Span
):
# type: (...) -> Optional[str]
# TODO: Document
if span.timestamp is None:
# This transaction is not yet finished so we just finish it.
span.finish()
if span.transaction is None:
# If this has no transaction set we assume there's a parent
# transaction for this span that would be flushed out eventually.
return None
if self.client is None:
# We have no client and therefore nowhere to send this transaction
# event.
return None
if not span.sampled:
# At this point a `sampled = None` should have already been
# resolved to a concrete decision. If `sampled` is `None`, it's
# likely that somebody used `with Hub.span(..)` on a
# non-transaction span and later decided to make it a transaction.
assert (span.sampled
is not None), "Need to set transaction when entering span!"
return None
return self.capture_event({
"type":
"transaction",
"transaction":
span.transaction,
"contexts": {
"trace": span.get_trace_context()
},
"timestamp":
span.timestamp,
"start_timestamp":
span.start_timestamp,
"spans": [
s.to_json() for s in (span._finished_spans or ())
if s is not span
],
})
@overload # noqa
def push_scope(
self,
callback=None # type: Optional[None]
):
# type: (...) -> ContextManager[Scope]
pass
@overload # noqa
def push_scope(
self,
callback # type: Callable[[Scope], None]
):
# type: (...) -> None
pass
def push_scope( # noqa
self,
callback=None # type: Optional[Callable[[Scope], None]]
):
# type: (...) -> Optional[ContextManager[Scope]]
"""
Pushes a new layer on the scope stack.
:param callback: If provided, this method pushes a scope, calls
`callback`, and pops the scope again.
:returns: If no `callback` is provided, a context manager that should
be used to pop the scope again.
"""
if callback is not None:
with self.push_scope() as scope:
callback(scope)
return None
client, scope = self._stack[-1]
new_layer = (client, copy.copy(scope))
self._stack.append(new_layer)
return _ScopeManager(self)
scope = push_scope
def pop_scope_unsafe(self):
# type: () -> Tuple[Optional[Client], Scope]
"""
Pops a scope layer from the stack.
Try to use the context manager :py:meth:`push_scope` instead.
"""
rv = self._stack.pop()
assert self._stack, "stack must have at least one layer"
return rv
@overload # noqa
def configure_scope(
self,
callback=None # type: Optional[None]
):
# type: (...) -> ContextManager[Scope]
pass
@overload # noqa
def configure_scope(
self,
callback # type: Callable[[Scope], None]
):
# type: (...) -> None
pass
def configure_scope( # noqa
self,
callback=None # type: Optional[Callable[[Scope], None]]
): # noqa
# type: (...) -> Optional[ContextManager[Scope]]
"""
Reconfigures the scope.
:param callback: If provided, call the callback with the current scope.
:returns: If no callback is provided, returns a context manager that returns the scope.
"""
client, scope = self._stack[-1]
if callback is not None:
if client is not None:
callback(scope)
return None
@contextmanager
def inner():
# type: () -> Generator[Scope, None, None]
if client is not None:
yield scope
else:
yield Scope()
return inner()
def flush(
self,
timeout=None, # type: Optional[float]
callback=None, # type: Optional[Callable[[int, float], None]]
):
# type: (...) -> None
"""
Alias for :py:meth:`sentry_sdk.Client.flush`
"""
client, scope = self._stack[-1]
if client is not None:
return client.flush(timeout=timeout, callback=callback)
def iter_trace_propagation_headers(self):
# type: () -> Generator[Tuple[str, str], None, None]
# TODO: Document
client, scope = self._stack[-1]
if scope._span is None:
return
propagate_traces = client and client.options["propagate_traces"]
if not propagate_traces:
return
if client and client.options["traceparent_v2"]:
traceparent = scope._span.to_traceparent()
else:
traceparent = scope._span.to_legacy_traceparent()
yield "sentry-trace", traceparent
class Hub(with_metaclass(HubMeta)): # type: ignore
"""The hub wraps the concurrency management of the SDK. Each thread has
its own hub but the hub might transfer with the flow of execution if
context vars are available.
If the hub is used with a with statement it's temporarily activated.
"""
_stack = None # type: List[Tuple[Optional[Client], Scope]]
# Mypy doesn't pick up on the metaclass.
if MYPY:
current = None # type: Hub
main = None # type: Hub
def __init__(
self,
client_or_hub=None, # type: Optional[Union[Hub, Client]]
scope=None, # type: Optional[Any]
):
# type: (...) -> None
if isinstance(client_or_hub, Hub):
hub = client_or_hub
client, other_scope = hub._stack[-1]
if scope is None:
scope = copy.copy(other_scope)
else:
client = client_or_hub
if scope is None:
scope = Scope()
self._stack = [(client, scope)]
self._last_event_id = None # type: Optional[str]
self._old_hubs = [] # type: List[Hub]
def __enter__(self):
# type: () -> Hub
self._old_hubs.append(Hub.current)
_local.set(self)
return self
def __exit__(
self,
exc_type, # type: Optional[type]
exc_value, # type: Optional[BaseException]
tb, # type: Optional[Any]
):
# type: (...) -> None
old = self._old_hubs.pop()
_local.set(old)
def run(
self,
callback # type: Callable[[], T]
):
# type: (...) -> T
"""Runs a callback in the context of the hub. Alternatively the
with statement can be used on the hub directly.
"""
with self:
return callback()
def get_integration(
self,
name_or_class # type: Union[str, Type[Integration]]
):
# type: (...) -> Any
"""Returns the integration for this hub by name or class. If there
is no client bound or the client does not have that integration
then `None` is returned.
If the return value is not `None` the hub is guaranteed to have a
client attached.
"""
if isinstance(name_or_class, str):
integration_name = name_or_class
elif name_or_class.identifier is not None:
integration_name = name_or_class.identifier
else:
raise ValueError("Integration has no name")
client = self.client
if client is not None:
rv = client.integrations.get(integration_name)
if rv is not None:
return rv
@property
def client(self):
# type: () -> Optional[Client]
"""Returns the current client on the hub."""
return self._stack[-1][0]
@property
def scope(self):
# type: () -> Scope
"""Returns the current scope on the hub."""
return self._stack[-1][1]
def last_event_id(self):
# type: () -> Optional[str]
"""Returns the last event ID."""
return self._last_event_id
def bind_client(
self,
new # type: Optional[Client]
):
# type: (...) -> None
"""Binds a new client to the hub."""
top = self._stack[-1]
self._stack[-1] = (new, top[1])
def capture_event(
self,
event, # type: Event
hint=None, # type: Optional[Hint]
scope=None, # type: Optional[Any]
**scope_args # type: Any
):
# type: (...) -> Optional[str]
"""Captures an event. Alias of :py:meth:`sentry_sdk.Client.capture_event`."""
client, top_scope = self._stack[-1]
scope = _update_scope(top_scope, scope, scope_args)
if client is not None:
rv = client.capture_event(event, hint, scope)
if rv is not None:
self._last_event_id = rv
return rv
return None
def capture_message(
self,
message, # type: str
level=None, # type: Optional[str]
scope=None, # type: Optional[Any]
**scope_args # type: Any
):
# type: (...) -> Optional[str]
"""Captures a message. The message is just a string. If no level
is provided the default level is `info`.
:returns: An `event_id` if the SDK decided to send the event (see :py:meth:`sentry_sdk.Client.capture_event`).
"""
if self.client is None:
return None
if level is None:
level = "info"
return self.capture_event({
"message": message,
"level": level
},
scope=scope,
**scope_args)
def capture_exception(
self,
error=None, # type: Optional[Union[BaseException, ExcInfo]]
scope=None, # type: Optional[Any]
**scope_args # type: Any
):
# type: (...) -> Optional[str]
"""Captures an exception.
:param error: An exception to catch. If `None`, `sys.exc_info()` will be used.
:returns: An `event_id` if the SDK decided to send the event (see :py:meth:`sentry_sdk.Client.capture_event`).
"""
client = self.client
if client is None:
return None
if error is not None:
exc_info = exc_info_from_error(error)
else:
exc_info = sys.exc_info()
event, hint = event_from_exception(exc_info,
client_options=client.options)
try:
return self.capture_event(event,
hint=hint,
scope=scope,
**scope_args)
except Exception:
self._capture_internal_exception(sys.exc_info())
return None
def _capture_internal_exception(
self,
exc_info # type: Any
):
# type: (...) -> Any
"""
Capture an exception that is likely caused by a bug in the SDK
itself.
These exceptions do not end up in Sentry and are just logged instead.
"""
logger.error("Internal error in sentry_sdk", exc_info=exc_info)
def add_breadcrumb(
self,
crumb=None, # type: Optional[Breadcrumb]
hint=None, # type: Optional[BreadcrumbHint]
**kwargs # type: Any
):
# type: (...) -> None
"""
Adds a breadcrumb.
:param crumb: Dictionary with the data as the sentry v7/v8 protocol expects.
:param hint: An optional value that can be used by `before_breadcrumb`
to customize the breadcrumbs that are emitted.
"""
client, scope = self._stack[-1]
if client is None:
logger.info("Dropped breadcrumb because no client bound")
return
crumb = dict(crumb or ()) # type: Breadcrumb
crumb.update(kwargs)
if not crumb:
return
hint = dict(hint or ()) # type: Hint
if crumb.get("timestamp") is None:
crumb["timestamp"] = datetime.utcnow()
if crumb.get("type") is None:
crumb["type"] = "default"
if client.options["before_breadcrumb"] is not None:
new_crumb = client.options["before_breadcrumb"](crumb, hint)
else:
new_crumb = crumb
if new_crumb is not None:
scope._breadcrumbs.append(new_crumb)
else:
logger.info("before breadcrumb dropped breadcrumb (%s)", crumb)
max_breadcrumbs = client.options["max_breadcrumbs"] # type: int
while len(scope._breadcrumbs) > max_breadcrumbs:
scope._breadcrumbs.popleft()
def start_span(
self,
span=None, # type: Optional[Span]
**kwargs # type: Any
):
# type: (...) -> Span
"""
Create and start timing a new span whose parent is the currently active
span or transaction, if any. The return value is a span instance,
typically used as a context manager to start and stop timing in a `with`
block.
Only spans contained in a transaction are sent to Sentry. Most
integrations start a transaction at the appropriate time, for example
for every incoming HTTP request. Use `start_transaction` to start a new
transaction when one is not already in progress.
"""
# TODO: consider removing this in a future release.
# This is for backwards compatibility with releases before
# start_transaction existed, to allow for a smoother transition.
if isinstance(span, Transaction) or "transaction" in kwargs:
deprecation_msg = (
"Deprecated: use start_transaction to start transactions and "
"Transaction.start_child to start spans.")
if isinstance(span, Transaction):
logger.warning(deprecation_msg)
return self.start_transaction(span)
if "transaction" in kwargs:
logger.warning(deprecation_msg)
name = kwargs.pop("transaction")
return self.start_transaction(name=name, **kwargs)
if span is not None:
return span
kwargs.setdefault("hub", self)
span = self.scope.span
if span is not None:
return span.start_child(**kwargs)
return Span(**kwargs)
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.
This is the entry point to manual tracing instrumentation.
A tree structure can be built by adding child spans to the transaction,
and child spans to other spans. To start a new child span within the
transaction or any span, call the respective `.start_child()` method.
Every child span must be finished before the transaction is finished,
otherwise the unfinished spans are discarded.
When used as context managers, spans and transactions are automatically
finished at the end of the `with` block. If not using context managers,
call the `.finish()` method.
When the transaction is finished, it will be sent to Sentry with all its
finished child spans.
"""
custom_sampling_context = kwargs.pop("custom_sampling_context", {})
# if we haven't been given a transaction, make one
if transaction is None:
kwargs.setdefault("hub", self)
transaction = Transaction(**kwargs)
# use traces_sample_rate, traces_sampler, and/or inheritance to make a
# sampling decision
sampling_context = {
"transaction_context": transaction.to_json(),
"parent_sampled": transaction.parent_sampled,
}
sampling_context.update(custom_sampling_context)
transaction._set_initial_sampling_decision(
sampling_context=sampling_context)
# we don't bother to keep spans if we already know we're not going to
# send the transaction
if transaction.sampled:
max_spans = (
self.client and
self.client.options["_experiments"].get("max_spans")) or 1000
transaction.init_span_recorder(maxlen=max_spans)
return transaction
@overload
def push_scope( # noqa: F811
self,
callback=None # type: Optional[None]
):
# type: (...) -> ContextManager[Scope]
pass
@overload
def push_scope( # noqa: F811
self,
callback # type: Callable[[Scope], None]
):
# type: (...) -> None
pass
def push_scope( # noqa
self,
callback=None # type: Optional[Callable[[Scope], None]]
):
# type: (...) -> Optional[ContextManager[Scope]]
"""
Pushes a new layer on the scope stack.
:param callback: If provided, this method pushes a scope, calls
`callback`, and pops the scope again.
:returns: If no `callback` is provided, a context manager that should
be used to pop the scope again.
"""
if callback is not None:
with self.push_scope() as scope:
callback(scope)
return None
client, scope = self._stack[-1]
new_layer = (client, copy.copy(scope))
self._stack.append(new_layer)
return _ScopeManager(self)
def pop_scope_unsafe(self):
# type: () -> Tuple[Optional[Client], Scope]
"""
Pops a scope layer from the stack.
Try to use the context manager :py:meth:`push_scope` instead.
"""
rv = self._stack.pop()
assert self._stack, "stack must have at least one layer"
return rv
@overload
def configure_scope( # noqa: F811
self,
callback=None # type: Optional[None]
):
# type: (...) -> ContextManager[Scope]
pass
@overload
def configure_scope( # noqa: F811
self,
callback # type: Callable[[Scope], None]
):
# type: (...) -> None
pass
def configure_scope( # noqa
self,
callback=None # type: Optional[Callable[[Scope], None]]
): # noqa
# type: (...) -> Optional[ContextManager[Scope]]
"""
Reconfigures the scope.
:param callback: If provided, call the callback with the current scope.
:returns: If no callback is provided, returns a context manager that returns the scope.
"""
client, scope = self._stack[-1]
if callback is not None:
if client is not None:
callback(scope)
return None
@contextmanager
def inner():
# type: () -> Generator[Scope, None, None]
if client is not None:
yield scope
else:
yield Scope()
return inner()
def start_session(
self,
session_mode="application" # type: str
):
# type: (...) -> None
"""Starts a new session."""
self.end_session()
client, scope = self._stack[-1]
scope._session = Session(
release=client.options["release"] if client else None,
environment=client.options["environment"] if client else None,
user=scope._user,
session_mode=session_mode,
)
def end_session(self):
# type: (...) -> None
"""Ends the current session if there is one."""
client, scope = self._stack[-1]
session = scope._session
self.scope._session = None
if session is not None:
session.close()
if client is not None:
client.capture_session(session)
def stop_auto_session_tracking(self):
# type: (...) -> None
"""Stops automatic session tracking.
This temporarily session tracking for the current scope when called.
To resume session tracking call `resume_auto_session_tracking`.
"""
self.end_session()
client, scope = self._stack[-1]
scope._force_auto_session_tracking = False
def resume_auto_session_tracking(self):
# type: (...) -> None
"""Resumes automatic session tracking for the current scope if
disabled earlier. This requires that generally automatic session
tracking is enabled.
"""
client, scope = self._stack[-1]
scope._force_auto_session_tracking = None
def flush(
self,
timeout=None, # type: Optional[float]
callback=None, # type: Optional[Callable[[int, float], None]]
):
# type: (...) -> None
"""
Alias for :py:meth:`sentry_sdk.Client.flush`
"""
client, scope = self._stack[-1]
if client is not None:
return client.flush(timeout=timeout, callback=callback)
def iter_trace_propagation_headers(self, span=None):
# type: (Optional[Span]) -> Generator[Tuple[str, str], None, None]
"""
Return HTTP headers which allow propagation of trace data. Data taken
from the span representing the request, if available, or the current
span on the scope if not.
"""
span = span or self.scope.span
if not span:
return
client = self._stack[-1][0]
propagate_traces = client and client.options["propagate_traces"]
if not propagate_traces:
return
yield "sentry-trace", span.to_traceparent()
class Hub(with_metaclass(HubMeta)): # type: ignore
"""The hub wraps the concurrency management of the SDK. Each thread has
its own hub but the hub might transfer with the flow of execution if
context vars are available.
If the hub is used with a with statement it's temporarily activated.
"""
_stack = None # type: List[Tuple[Optional[Client], Scope]]
def __init__(self, client_or_hub=None, scope=None):
# type: (Union[Hub, Client], Optional[Any]) -> None
if isinstance(client_or_hub, Hub):
hub = client_or_hub
client, other_scope = hub._stack[-1]
if scope is None:
scope = copy.copy(other_scope)
else:
client = client_or_hub
if scope is None:
scope = Scope()
self._stack = [(client, scope)]
self._last_event_id = None # type: Optional[str]
self._old_hubs = [] # type: List[Hub]
def __enter__(self):
# type: () -> Hub
self._old_hubs.append(Hub.current)
_local.set(self)
return self
def __exit__(
self,
exc_type, # type: Optional[type]
exc_value, # type: Optional[BaseException]
tb, # type: Optional[Any]
):
# type: (...) -> None
old = self._old_hubs.pop()
_local.set(old)
def run(self, callback):
"""Runs a callback in the context of the hub. Alternatively the
with statement can be used on the hub directly.
"""
with self:
return callback()
def get_integration(self, name_or_class):
# type: (Union[str, Integration]) -> Any
"""Returns the integration for this hub by name or class. If there
is no client bound or the client does not have that integration
then `None` is returned.
If the return value is not `None` the hub is guaranteed to have a
client attached.
"""
if isinstance(name_or_class, str):
integration_name = name_or_class
elif name_or_class.identifier is not None:
integration_name = name_or_class.identifier
else:
raise ValueError("Integration has no name")
client = self._stack[-1][0]
if client is not None:
rv = client.integrations.get(integration_name)
if rv is not None:
return rv
initial_client = _initial_client
if initial_client is not None:
initial_client = initial_client()
if (initial_client is not None and initial_client is not client and
initial_client.integrations.get(name_or_class) is not None):
warning = ("Integration %r attempted to run but it was only "
"enabled on init() but not the client that "
"was bound to the current flow. Earlier versions of "
"the SDK would consider these integrations enabled but "
"this is no longer the case." % (name_or_class, ))
warn(Warning(warning), stacklevel=3)
logger.warning(warning)
@property
def client(self):
# type: () -> Optional[Client]
"""Returns the current client on the hub."""
return self._stack[-1][0]
def last_event_id(self):
# type: () -> Optional[str]
"""Returns the last event ID."""
return self._last_event_id
def bind_client(self, new):
"""Binds a new client to the hub."""
top = self._stack[-1]
self._stack[-1] = (new, top[1])
def capture_event(self, event, hint=None):
# type: (Event, Hint) -> Optional[str]
"""Captures an event. The return value is the ID of the event.
The event is a dictionary following the Sentry v7/v8 protocol
specification. Optionally an event hint dict can be passed that
is used by processors to extract additional information from it.
Typically the event hint object would contain exception information.
"""
client, scope = self._stack[-1]
if client is not None:
rv = client.capture_event(event, hint, scope)
if rv is not None:
self._last_event_id = rv
return rv
return None
def capture_message(self, message, level=None):
# type: (str, Optional[str]) -> Optional[str]
"""Captures a message. The message is just a string. If no level
is provided the default level is `info`.
"""
if self.client is None:
return None
if level is None:
level = "info"
return self.capture_event({"message": message, "level": level})
def capture_exception(self, error=None):
# type: (Optional[BaseException]) -> Optional[str]
"""Captures an exception.
The argument passed can be `None` in which case the last exception
will be reported, otherwise an exception object or an `exc_info`
tuple.
"""
client = self.client
if client is None:
return None
if error is None:
exc_info = sys.exc_info()
else:
exc_info = exc_info_from_error(error)
event, hint = event_from_exception(exc_info,
client_options=client.options)
try:
return self.capture_event(event, hint=hint)
except Exception:
self._capture_internal_exception(sys.exc_info())
return None
def _capture_internal_exception(self, exc_info):
"""Capture an exception that is likely caused by a bug in the SDK
itself."""
logger.error("Internal error in sentry_sdk", exc_info=exc_info)
def add_breadcrumb(self, crumb=None, hint=None, **kwargs):
# type: (Optional[Breadcrumb], Optional[BreadcrumbHint], **Any) -> None
"""Adds a breadcrumb. The breadcrumbs are a dictionary with the
data as the sentry v7/v8 protocol expects. `hint` is an optional
value that can be used by `before_breadcrumb` to customize the
breadcrumbs that are emitted.
"""
client, scope = self._stack[-1]
if client is None:
logger.info("Dropped breadcrumb because no client bound")
return
crumb = dict(crumb or ()) # type: Breadcrumb
crumb.update(kwargs)
if not crumb:
return
hint = dict(hint or ()) # type: Hint
if crumb.get("timestamp") is None:
crumb["timestamp"] = datetime.utcnow()
if crumb.get("type") is None:
crumb["type"] = "default"
if client.options["before_breadcrumb"] is not None:
new_crumb = client.options["before_breadcrumb"](crumb, hint)
else:
new_crumb = crumb
if new_crumb is not None:
scope._breadcrumbs.append(new_crumb)
else:
logger.info("before breadcrumb dropped breadcrumb (%s)", crumb)
max_breadcrumbs = client.options["max_breadcrumbs"] # type: int
while len(scope._breadcrumbs) > max_breadcrumbs:
scope._breadcrumbs.popleft()
@overload # noqa
def push_scope(self):
# type: () -> ContextManager[Scope]
pass
@overload # noqa
def push_scope(self, callback):
# type: (Callable[[Scope], None]) -> None
pass
def push_scope(self, callback=None): # noqa
"""Pushes a new layer on the scope stack. Returns a context manager
that should be used to pop the scope again. Alternatively a callback
can be provided that is executed in the context of the scope.
"""
if callback is not None:
with self.push_scope() as scope:
callback(scope)
return None
client, scope = self._stack[-1]
new_layer = (client, copy.copy(scope))
self._stack.append(new_layer)
return _ScopeManager(self)
scope = push_scope
def pop_scope_unsafe(self):
"""Pops a scope layer from the stack. Try to use the context manager
`push_scope()` instead."""
rv = self._stack.pop()
assert self._stack, "stack must have at least one layer"
return rv
@overload # noqa
def configure_scope(self):
# type: () -> ContextManager[Scope]
pass
@overload # noqa
def configure_scope(self, callback):
# type: (Callable[[Scope], None]) -> None
pass
def configure_scope(self, callback=None): # noqa
"""Reconfigures the scope."""
client, scope = self._stack[-1]
if callback is not None:
if client is not None:
callback(scope)
return None
@contextmanager
def inner():
if client is not None:
yield scope
else:
yield Scope()
return inner()
def flush(self, timeout=None, callback=None):
# type: (Optional[float], Optional[Callable[[int, float], None]]) -> None
"""Alias for self.client.flush"""
client, scope = self._stack[-1]
if client is not None:
return client.flush(timeout=timeout, callback=callback)
def iter_trace_propagation_headers(self):
# type: () -> Generator[Tuple[str, str], None, None]
client, scope = self._stack[-1]
if scope._span is None:
return
propagate_traces = client and client.options["propagate_traces"]
if not propagate_traces:
return
for item in scope._span.iter_headers():
yield item
class Hub(with_metaclass(HubMeta)):
"""The hub wraps the concurrency management of the SDK. Each thread has
its own hub but the hub might transfer with the flow of execution if
context vars are available.
If the hub is used with a with statement it's temporarily activated.
"""
def __init__(self, client_or_hub=None, scope=None):
if isinstance(client_or_hub, Hub):
hub = client_or_hub
client, other_scope = hub._stack[-1]
if scope is None:
scope = copy.copy(other_scope)
else:
client = client_or_hub
if scope is None:
scope = Scope()
self._stack = [(client, scope)]
self._last_event_id = None
self._old_hubs = []
def __enter__(self):
self._old_hubs.append(Hub.current)
_local.set(self)
return self
def __exit__(self, exc_type, exc_value, tb):
old = self._old_hubs.pop()
_local.set(old)
def run(self, callback):
"""Runs a callback in the context of the hub. Alternatively the
with statement can be used on the hub directly.
"""
with self:
return callback()
@property
def client(self):
"""Returns the current client on the hub."""
return self._stack[-1][0]
def last_event_id(self):
"""Returns the last event ID."""
return self._last_event_id
def bind_client(self, new):
"""Binds a new client to the hub."""
top = self._stack[-1]
self._stack[-1] = (new, top[1])
def capture_event(self, event, hint=None):
"""Captures an event. The return value is the ID of the event.
The event is a dictionary following the Sentry v7/v8 protocol
specification. Optionally an event hint dict can be passed that
is used by processors to extract additional information from it.
Typically the event hint object would contain exception information.
"""
client, scope = self._stack[-1]
if client is not None:
rv = client.capture_event(event, hint, scope)
if rv is not None:
self._last_event_id = rv
return rv
def capture_message(self, message, level=None):
"""Captures a message. The message is just a string. If no level
is provided the default level is `info`.
"""
if self.client is None:
return
if level is None:
level = "info"
return self.capture_event({"message": message, "level": level})
def capture_exception(self, error=None):
"""Captures an exception.
The argument passed can be `None` in which case the last exception
will be reported, otherwise an exception object or an `exc_info`
tuple.
"""
client = self.client
if client is None:
return
if error is None:
exc_info = sys.exc_info()
else:
exc_info = exc_info_from_error(error)
event, hint = event_from_exception(
exc_info, with_locals=client.options["with_locals"])
try:
return self.capture_event(event, hint=hint)
except Exception:
self._capture_internal_exception(sys.exc_info())
def _capture_internal_exception(self, exc_info):
"""Capture an exception that is likely caused by a bug in the SDK
itself."""
logger.debug("Internal error in sentry_sdk", exc_info=exc_info)
def add_breadcrumb(self, crumb=None, hint=None, **kwargs):
"""Adds a breadcrumb. The breadcrumbs are a dictionary with the
data as the sentry v7/v8 protocol expects. `hint` is an optional
value that can be used by `before_breadcrumb` to customize the
breadcrumbs that are emitted.
"""
client, scope = self._stack[-1]
if client is None:
logger.info("Dropped breadcrumb because no client bound")
return
crumb = dict(crumb or ())
crumb.update(kwargs)
if not crumb:
return
hint = dict(hint or ())
if crumb.get("timestamp") is None:
crumb["timestamp"] = datetime.utcnow()
if crumb.get("type") is None:
crumb["type"] = "default"
original_crumb = crumb
if client.options["before_breadcrumb"] is not None:
crumb = client.options["before_breadcrumb"](crumb, hint)
if crumb is not None:
scope._breadcrumbs.append(crumb)
else:
logger.info("before breadcrumb dropped breadcrumb (%s)",
original_crumb)
while len(scope._breadcrumbs) > client.options["max_breadcrumbs"]:
scope._breadcrumbs.popleft()
def push_scope(self, callback=None):
"""Pushes a new layer on the scope stack. Returns a context manager
that should be used to pop the scope again. Alternatively a callback
can be provided that is executed in the context of the scope.
"""
client, scope = self._stack[-1]
new_layer = (client, copy.copy(scope))
self._stack.append(new_layer)
if callback is not None:
if client is not None:
callback(scope)
else:
return _ScopeManager(self, new_layer)
def pop_scope_unsafe(self):
"""Pops a scope layer from the stack. Try to use the context manager
`push_scope()` instead."""
rv = self._stack.pop()
assert self._stack
return rv
def configure_scope(self, callback=None):
"""Reconfigures the scope."""
client, scope = self._stack[-1]
if callback is not None:
if client is not None:
callback(scope)
return
@contextmanager
def inner():
if client is not None:
yield scope
else:
yield Scope()
return inner()
def scope(self, callback=None):
"""Pushes a new scope and yields it for configuration.
The scope is dropped at the end of the with statement. Alternatively
a callback can be provided similar to `configure_scope`.
"""
with self.push_scope():
client, scope = self._stack[-1]
return self.configure_scope(callback)
