Scopes

Scopes store extra data that the SDK adds to your event when sending the event to Sentry. While the SDKs typically manage the scope automatically, understanding how scopes work and how you can manage them manually can be helpful.

What is a Scope?

A scope manages an event's data. For instance, the SDK stores contexts and breadcrumbs on the scope.

There are three types of scopes. Exactly one scope of each type will be active at a specific point in time.

• Global scope: A single globally-shared scope storing data relevant for the whole app (such as the release).
• Isolation scope: Thread-local scope created for each request-response lifecycle to store data relevant to the request.
• Current scope: Thread-local scope created for each span to store data relevant to the span.

The SDK and the SDK's built-in integrations automatically manage the scopes. For example, web framework integrations create an isolation scope for each request handled. When you call a top-level API function, such as set_tag, the SDK determines the correct scope on which to operate.

When sending an event to Sentry, the final data applied to the event is the result of merging the three scopes, applying data from each in turn. The global scope is applied first, followed by the isolation scope, and then the current scope.

Changing the Scope

We generally recommend using the top-level API to manage your scopes, since the SDK's automatic scope management handles most use cases.

However, if your use case requires direct access to the scope object, you can use the new_scope context manager. new_scope forks the current scope, allows you to modify the new scope while the context manager is active, and restores the original scope afterwards. Using new_scope allows you to send data for only one specific event, such as modifying the context. It is roughly equivalent to the push_scope context manager in earlier (1.x) versions of the SDK.

Using new_scope allows you to attach additional information, such as adding custom tags or informing Sentry about the currently authenticated user.

import sentry_sdk
from sentry_sdk.scope import Scope

scope = Scope.get_current_scope()
scope.set_tag("my-tag", "my value")
scope.user = {"id": 42, "email": "john.doe@example.com"}

# reset all scope data
scope.clear()

# Or:

sentry_sdk.set_tag("my-tag", "my value")
sentry_sdk.set_user({"id": 42, "email": "john.doe@example.com"})

You can also apply this configuration when unsetting a user at logout:

from sentry_sdk import set_user

set_user(None)

To learn what useful information can be associated with scopes see the context documentation.