Top Level API

This is the user facing API of the SDK. It’s exposed as sentry_sdk. With this API you can implement a custom performance monitoring or error reporting solution.

Capturing Data

sentry_sdk.api.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().

Parameters:

scope_args (Any) – For supported **scope_args see sentry_sdk.Scope.update_from_kwargs().

Return type:

Optional[str]

sentry_sdk.api.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]], Optional[BaseException], Optional[TracebackType]], None]) – An exception to catch. If None, sys.exc_info() will be used.

• scope_args (Any) – For supported **scope_args see sentry_sdk.Scope.update_from_kwargs().

Return type:

Optional[str]

Returns:

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

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

Alias for sentry_sdk.Hub.capture_message()

Captures a message.

Parameters:

• message (str) – The string to send as the message.

• level (Optional[str]) – If no level is provided, the default level is info.

• scope (Optional[Any]) – An optional sentry_sdk.Scope to use.

• scope_args (Any) – For supported **scope_args see sentry_sdk.Scope.update_from_kwargs().

Return type:

Optional[str]

Returns:

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

Enriching Events

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

Alias for sentry_sdk.Hub.add_breadcrumb()

Adds a breadcrumb.

Parameters:

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

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

Return type:

None

sentry_sdk.api.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.api.set_extra(key, value)

Alias for sentry_sdk.Scope.set_extra()

Sets an extra key to a specific value.

Return type:

None

sentry_sdk.api.set_level(value)

Alias for sentry_sdk.Scope.set_level()

Sets the level for the scope.

Return type:

None

sentry_sdk.api.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.api.set_user(value)

Alias for sentry_sdk.Scope.set_user()

Sets a user for the scope.

Return type:

None

Performance Monitoring

sentry_sdk.api.continue_trace(environ_or_headers, op=None, name=None, source=None)

Sets the propagation context from environment or headers and returns a transaction.

Return type:

Transaction

sentry_sdk.api.get_current_span(hub=None)

Returns the currently active span if there is one running, otherwise None

Return type:

Optional[Span]

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

Alias for sentry_sdk.Hub.start_span()

Start a span whose parent is the currently active span or transaction, if any.

The return value is a sentry_sdk.tracing.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 sentry_sdk.start_transaction() to start a new transaction when one is not already in progress.

For supported **kwargs see sentry_sdk.tracing.Span.

Return type:

Span

sentry_sdk.api.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.

For supported **kwargs see sentry_sdk.tracing.Transaction.

Return type:

Union[Transaction, NoOpSpan]

Distributed Tracing

sentry_sdk.api.get_baggage()

Returns Baggage either from the active span or from the scope.

Return type:

Optional[str]

sentry_sdk.api.get_traceparent()

Returns the traceparent either from the active span or from the scope.

Return type:

Optional[str]

Managing Scope (advanced)

sentry_sdk.api.configure_scope(callback=None)

Alias for sentry_sdk.Hub.configure_scope()

Reconfigures the scope.

Parameters:

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

Return type:

Optional[ContextManager[Scope]]

Returns:

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

sentry_sdk.api.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]]) – If provided, this method pushes a scope, calls callback, and pops the scope again.

Return type:

Optional[ContextManager[Scope]]

Returns:

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