Main API

class sentry_sdk.Client(dsn=None, with_locals=True, max_breadcrumbs=100, release=None, environment=None, server_name=None, shutdown_timeout=2, integrations=[], in_app_include=[], in_app_exclude=[], default_integrations=True, dist=None, transport=None, transport_queue_size=100, sample_rate=1.0, send_default_pii=False, http_proxy=None, https_proxy=None, ignore_errors=[], request_bodies='medium', before_send=None, before_breadcrumb=None, debug=False, attach_stacktrace=False, ca_certs=None, propagate_traces=True, traces_sample_rate=None, traces_sampler=None, auto_enabling_integrations=True, auto_session_tracking=True, send_client_reports=True, _experiments={})

capture_event(event, hint=None, scope=None)

Captures an event.

Parameters

• event (Dict[str, Any]) – A ready-made event that can be directly sent to Sentry.

• hint (Optional[Dict[str, Any], None]) – Contains metadata about the event that can be read from before_send, such as the original exception object or a HTTP request object.

Return type

Optional[str, None]

Returns

An event ID. May be None if there is no DSN set or of if the SDK decided to discard the event for other reasons. In such situations setting debug=True on init() may help.

close(timeout=None, callback=None)

Close the client and shut down the transport. Arguments have the same semantics as Client.flush().

Return type

None

property dsn

Returns the configured DSN as string.

Return type

Optional[str, None]

flush(timeout=None, callback=None)

Wait for the current events to be sent.

Parameters

• timeout (Optional[float, None]) – Wait for at most timeout seconds. If no timeout is provided, the shutdown_timeout option value is used.

• callback (Optional[Callable[[int, float], None], None]) – Is invoked with the number of pending events and the configured timeout.

Return type

None

class sentry_sdk.HttpTransport(options)

The default HTTP transport.

capture_envelope(envelope)

Send an envelope to Sentry.

Envelopes are a data container format that can hold any type of data submitted to Sentry. We use it for transactions and sessions, but regular “error” events should go through capture_event for backwards compat.

Return type

None

capture_event(event)

This gets invoked with the event dictionary when an event should be sent to sentry.

Return type

None

flush(timeout, callback=None)

Wait timeout seconds for the current events to be sent out.

Return type

None

kill()

Forcefully kills the transport.

Return type

None

record_lost_event(reason, data_category=None, item=None)

This increments a counter for event loss by reason and data category.

Return type

None

class sentry_sdk.Hub(client_or_hub=None, scope=None)

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.

add_breadcrumb(crumb=None, hint=None, **kwargs)

Adds a breadcrumb.

Parameters

• crumb (Optional[Dict[str, Any], None]) – Dictionary with the data as the sentry v7/v8 protocol expects.

• hint (Optional[Dict[str, Any], None]) – An optional value that can be used by before_breadcrumb to customize the breadcrumbs that are emitted.

Return type

None

bind_client(new)

Binds a new client to the hub.

Return type

None

capture_event(event, hint=None, scope=None, **scope_args)

Captures an event. Alias of sentry_sdk.Client.capture_event().

Return type

Optional[str, None]

capture_exception(error=None, scope=None, **scope_args)

Captures an exception.

Parameters

error (Union[BaseException, Tuple[Optional[Type[BaseException], None], Optional[BaseException, None], Optional[traceback, None]], None]) – An exception to catch. If None, sys.exc_info() will be used.

Return type

Optional[str, None]

Returns

An event_id if the SDK decided to send the event (see sentry_sdk.Client.capture_event()).

capture_message(message, level=None, scope=None, **scope_args)

Captures a message. The message is just a string. If no level is provided the default level is info.

Return type

Optional[str, None]

Returns

An event_id if the SDK decided to send the event (see sentry_sdk.Client.capture_event()).

property client

Returns the current client on the hub.

Return type

Optional[Client, None]

configure_scope(callback=None)

configure_scope(callback)

Reconfigures the scope.

Parameters

callback (Optional[Callable[[Scope], None], None]) – If provided, call the callback with the current scope.

Return type

Optional[ContextManager[Scope], None]

Returns

If no callback is provided, returns a context manager that returns the scope.

end_session()

Ends the current session if there is one.

Return type

None

flush(timeout=None, callback=None)

Alias for sentry_sdk.Client.flush()

Return type

None

get_integration(name_or_class)

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.

Return type

Any

iter_trace_propagation_headers(span=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.

Return type

Generator[Tuple[str, str], None, None]

last_event_id()

Returns the last event ID.

Return type

Optional[str, None]

pop_scope_unsafe()

Pops a scope layer from the stack.

Try to use the context manager push_scope() instead.

Return type

Tuple[Optional[Client, None], Scope]

push_scope(callback=None)

push_scope(callback)

Pushes a new layer on the scope stack.

Parameters

callback (Optional[Callable[[Scope], None], None]) – If provided, this method pushes a scope, calls callback, and pops the scope again.

Return type

Optional[ContextManager[Scope], None]

Returns

If no callback is provided, a context manager that should be used to pop the scope again.

resume_auto_session_tracking()

Resumes automatic session tracking for the current scope if disabled earlier. This requires that generally automatic session tracking is enabled.

Return type

None

run(callback)

Runs a callback in the context of the hub. Alternatively the with statement can be used on the hub directly.

Return type

~T

property scope

Returns the current scope on the hub.

Return type

Scope

start_session(session_mode='application')

Starts a new session.

Return type

None

start_span(span=None, **kwargs)

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.

Return type

Span

start_transaction(transaction=None, **kwargs)

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.

Return type

Transaction

stop_auto_session_tracking()

Stops automatic session tracking.

This temporarily session tracking for the current scope when called. To resume session tracking call resume_auto_session_tracking.

Return type

None

trace_propagation_meta(span=None)

Return meta tags which should be injected into the HTML template to allow propagation of trace data.

Return type

str

class sentry_sdk.Scope

The scope holds extra information that should be sent with all events that belong to it.

add_attachment(bytes=None, filename=None, path=None, content_type=None, add_to_transactions=False)

Adds an attachment to future events sent.

Return type

None

add_error_processor(func, cls=None)

Register a scope local error processor on the scope.

Parameters

• func (Callable[[Dict[str, Any], Tuple[Optional[Type[BaseException], None], Optional[BaseException, None], Optional[traceback, None]]], Optional[Dict[str, Any], None]]) – A callback that works similar to an event processor but is invoked with the original exception info triple as second argument.

• cls (Optional[Type[BaseException], None]) – Optionally, only process exceptions of this type.

Return type

None

add_event_processor(func)

Register a scope local event processor on the scope.

Parameters

func (Callable[[Dict[str, Any], Dict[str, Any]], Optional[Dict[str, Any], None]]) – This function behaves like before_send.

Return type

None

apply_to_event(event, hint)

Applies the information contained on the scope to the given event.

Return type

Optional[Dict[str, Any], None]

clear()

Clears the entire scope.

Return type

None

clear_breadcrumbs()

Clears breadcrumb buffer.

Return type

None

property fingerprint

When set this overrides the default fingerprint.

property level

When set this overrides the level. Deprecated in favor of set_level.

remove_context(key)

Removes a context.

Return type

None

remove_extra(key)

Removes a specific extra key.

Return type

None

remove_tag(key)

Removes a specific tag.

Return type

None

set_context(key, value)

Binds a context at a certain key to a specific value.

Return type

None

set_extra(key, value)

Sets an extra key to a specific value.

Return type

None

set_level(value)

Sets the level for the scope.

Return type

None

set_tag(key, value)

Sets a tag for a key to a specific value.

Return type

None

set_transaction_name(name, source=None)

Set the transaction name and optionally the transaction source.

Return type

None

set_user(value)

Sets a user for the scope.

Return type

None

property span

Get/set current tracing span or transaction.

Return type

Optional[Span, None]

property transaction

Return the transaction (root span) in the scope, if any.

Return type

Any

property user

When set a specific user is bound to the scope. Deprecated in favor of set_user.

class sentry_sdk.Transport(options=None)

Baseclass for all transports.

A transport is used to send an event to sentry.

capture_envelope(envelope)

Send an envelope to Sentry.

Envelopes are a data container format that can hold any type of data submitted to Sentry. We use it for transactions and sessions, but regular “error” events should go through capture_event for backwards compat.

Return type

None

capture_event(event)

This gets invoked with the event dictionary when an event should be sent to sentry.

Return type

None

flush(timeout, callback=None)

Wait timeout seconds for the current events to be sent out.

Return type

None

kill()

Forcefully kills the transport.

Return type

None

record_lost_event(reason, data_category=None, item=None)

This increments a counter for event loss by reason and data category.

Return type

None

sentry_sdk.add_breadcrumb(crumb=None, hint=None, **kwargs)

Alias for sentry_sdk.Hub.add_breadcrumb()

Adds a breadcrumb.

Parameters

• crumb (Optional[Dict[str, Any], None]) – Dictionary with the data as the sentry v7/v8 protocol expects.

• hint (Optional[Dict[str, Any], None]) – An optional value that can be used by before_breadcrumb to customize the breadcrumbs that are emitted.

Return type

None

sentry_sdk.capture_event(event, hint=None, scope=None, **scope_args)

Alias for sentry_sdk.Hub.capture_event()

Captures an event. Alias of sentry_sdk.Client.capture_event().

Return type

Optional[str, None]

sentry_sdk.capture_exception(error=None, scope=None, **scope_args)

Alias for sentry_sdk.Hub.capture_exception()

Captures an exception.

Parameters

error (Union[BaseException, Tuple[Optional[Type[BaseException], None], Optional[BaseException, None], Optional[traceback, None]], None]) – An exception to catch. If None, sys.exc_info() will be used.

Return type

Optional[str, None]

Returns

An event_id if the SDK decided to send the event (see sentry_sdk.Client.capture_event()).

sentry_sdk.capture_message(message, level=None, scope=None, **scope_args)

Alias for sentry_sdk.Hub.capture_message()

Captures a message. The message is just a string. If no level is provided the default level is info.

Return type

Optional[str, None]

Returns

An event_id if the SDK decided to send the event (see sentry_sdk.Client.capture_event()).

sentry_sdk.configure_scope(callback=None)

Alias for sentry_sdk.Hub.configure_scope()

Reconfigures the scope.

Parameters

callback (Optional[Callable[[Scope], None], None]) – If provided, call the callback with the current scope.

Return type

Optional[ContextManager[Scope], None]

Returns

If no callback is provided, returns a context manager that returns the scope.

sentry_sdk.flush(timeout=None, callback=None)

Alias for sentry_sdk.Hub.flush()

Alias for sentry_sdk.Client.flush()

Return type

None

sentry_sdk.last_event_id()

Alias for sentry_sdk.Hub.last_event_id()

Returns the last event ID.

Return type

Optional[str, None]

sentry_sdk.push_scope(callback=None)

Alias for sentry_sdk.Hub.push_scope()

Pushes a new layer on the scope stack.

Parameters

callback (Optional[Callable[[Scope], None], None]) – If provided, this method pushes a scope, calls callback, and pops the scope again.

Return type

Optional[ContextManager[Scope], None]

Returns

If no callback is provided, a context manager that should be used to pop the scope again.

sentry_sdk.set_context(key, value)

Alias for sentry_sdk.Scope.set_context()

Binds a context at a certain key to a specific value.

Return type

None

sentry_sdk.set_extra(key, value)

Alias for sentry_sdk.Scope.set_extra()

Sets an extra key to a specific value.

Return type

None

sentry_sdk.set_level(value)

Alias for sentry_sdk.Scope.set_level()

Sets the level for the scope.

Return type

None

sentry_sdk.set_tag(key, value)

Alias for sentry_sdk.Scope.set_tag()

Sets a tag for a key to a specific value.

Return type

None

sentry_sdk.set_user(value)

Alias for sentry_sdk.Scope.set_user()

Sets a user for the scope.

Return type

None

sentry_sdk.start_span(span=None, **kwargs)

Alias for sentry_sdk.Hub.start_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.

Return type

Span

sentry_sdk.start_transaction(transaction=None, **kwargs)

Alias for sentry_sdk.Hub.start_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.

Return type

Transaction