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_kwargs)[source]

Alias for sentry_sdk.Scope.capture_event()

Captures an event.

Merges given scope data and calls sentry_sdk.client._Client.capture_event().

Parameters:

  • event (Event) – A ready-made event that can be directly sent to Sentry.

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

  • scope (Optional[Any]) – An optional sentry_sdk.Scope to apply to events. The scope and scope_kwargs parameters are mutually exclusive.

  • scope_kwargs (Any) – Optional data to apply to event. For supported **scope_kwargs see sentry_sdk.Scope.update_from_kwargs(). The scope and scope_kwargs parameters are mutually exclusive.

Return type:

Optional[str]

Returns:

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

sentry_sdk.api.capture_exception(error=None, scope=None, **scope_kwargs)[source]

Alias for sentry_sdk.Scope.capture_exception()

Captures an exception.

Parameters:
Return type:

Optional[str]

Returns:

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

sentry_sdk.api.capture_message(message, level=None, scope=None, **scope_kwargs)[source]

Alias for sentry_sdk.Scope.capture_message()

Captures a message.

Parameters:

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

  • level (Optional[Literal['fatal', 'critical', 'error', 'warning', 'info', 'debug']]) – If no level is provided, the default level is info.

  • scope (Optional[Any]) – An optional sentry_sdk.Scope to apply to events. The scope and scope_kwargs parameters are mutually exclusive.

  • scope_kwargs (Any) – Optional data to apply to event. For supported **scope_kwargs see sentry_sdk.Scope.update_from_kwargs(). The scope and scope_kwargs parameters are mutually exclusive.

Return type:

Optional[str]

Returns:

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

Enriching Events

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

Alias for sentry_sdk.Scope.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)[source]

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)[source]

Alias for sentry_sdk.Scope.set_extra()

Sets an extra key to a specific value.

Return type:

None

sentry_sdk.api.set_level(value)[source]

Alias for sentry_sdk.Scope.set_level()

Sets the level for the scope.

Parameters:

value (Literal['fatal', 'critical', 'error', 'warning', 'info', 'debug']) – The level to set.

Return type:

None

sentry_sdk.api.set_tag(key, value)[source]

Alias for sentry_sdk.Scope.set_tag()

Sets a tag for a key to a specific value.

Parameters:

  • key (str) – Key of the tag to set.

  • value (Any) – Value of the tag to set.

Return type:

None

sentry_sdk.api.set_user(value)[source]

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, origin='manual')[source]

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

Return type:

Transaction

sentry_sdk.api.get_current_span(scope=None)[source]

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

Return type:

Optional[Span]

sentry_sdk.api.start_span(**kwargs)[source]

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

The instrumenter parameter is deprecated for user code, and it will be removed in the next major version. Going forward, it should only be used by the SDK itself.

Return type:

Span

sentry_sdk.api.start_transaction(transaction=None, instrumenter='sentry', custom_sampling_context=None, **kwargs)[source]

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

Parameters:

  • transaction (Optional[Transaction]) – The transaction to start. If omitted, we create and start a new transaction.

  • instrumenter (str) – This parameter is meant for internal use only. It will be removed in the next major version.

  • custom_sampling_context (Optional[Dict[str, Any]]) – The transaction’s custom sampling context.

  • kwargs (Unpack[TransactionKwargs]) – Optional keyword arguments to be passed to the Transaction constructor. See sentry_sdk.tracing.Transaction for available arguments.

Return type:

Union[Transaction, NoOpSpan]

Distributed Tracing

sentry_sdk.api.get_baggage()[source]

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

Return type:

Optional[str]

sentry_sdk.api.get_traceparent()[source]

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

Return type:

Optional[str]

Client Management

sentry_sdk.api.is_initialized()[source]
Return type:

bool

Added in version 2.0.0.

Returns whether Sentry has been initialized or not.

If a client is available and the client is active (meaning it is configured to send data) then Sentry is initialized.

sentry_sdk.api.get_client()[source]

Alias for sentry_sdk.Scope.get_client() :rtype: BaseClient

Added in version 2.0.0.

Returns the currently used sentry_sdk.Client. This checks the current scope, the isolation scope and the global scope for a client. If no client is available a sentry_sdk.client.NonRecordingClient is returned.

Managing Scope (advanced)

sentry_sdk.api.configure_scope(callback=None)[source]

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)[source]

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.

sentry_sdk.api.new_scope()[source]
Return type:

Generator[Scope, None, None]

Added in version 2.0.0.

Context manager that forks the current scope and runs the wrapped code in it. After the wrapped code is executed, the original scope is restored.

Example Usage:

import sentry_sdk

with sentry_sdk.new_scope() as scope:
    scope.set_tag("color", "green")
    sentry_sdk.capture_message("hello") # will include `color` tag.

sentry_sdk.capture_message("hello, again") # will NOT include `color` tag.