Scopes

When an event is captured and sent to Sentry, SDKs will merge that event data with extra information from the current scope. SDKs will typically automatically manage the scopes for you in the framework integrations and you don't need to think about them. However, you should know what a scope is and how you can use it to your advantage.

What's a Scope?

Scopes hold useful information that gets sent along with the event. For instance, contexts and breadcrumbs are stored on the scope. When a scope is forked, it inherits all data from its parent scope.

How Scopes Work

Scopes are basically stacks of data that are attached to events. When an event is captured, the SDK will merge the data from the active scopes into the event. This allows you to attach data to events that is relevant to the context in which the event was captured.

When you call a global function such as Sentry.captureException, Sentry automatically discovers the active scopes and applies them when capturing the event.

Different Kinds of Scopes

The Sentry SDK has three different kinds of scopes:

• Global scope
• Isolation scope
• Current scope

The Android SDK does not fork scopes on its own so you may set data on any of the scopes. The Android SDK writes to current scope by default when using top level API like Sentry.setTag.

Global Scope

The global scope is applied to all events, no matter where they originate. You can use it to store data that should apply to all events, such as environmental information.

Isolation Scope

The isolation scope is used to isolate events from each other. For example, each request in a web server might get its own isolation scope, so that events from one request don't interfere with events from another request.

Current Scope

The current scope is the local scope that is currently active. You can modify the current scope via Sentry.configureScope(scope -> { ... }).

How Scope Data is Applied to Events

Global scope, isolation scope, and current scope are combined before an event (like an error or transaction) gets sent to Sentry. In most cases, setting something on current scope replaces the same thing that may have been set on isolation or global scope. If it hasn't been set on current scope, the value on isolation scope takes precedence over the one from global scope. If there also isn't any value on isolation scope, the one from global scope is used if present.

Note, there are exceptions to this, where values from all scopes are merged. This is the case for breadcrumbs, tags, extras, contexts, attachments, and event processors.

Sentry.configureScope(ScopeType.GLOBAL, scope -> {
  scope.setExtra("shared", "global");
  scope.setExtra("global", "data");
});

Sentry.configureScope(ScopeType.ISOLATION, scope -> {
  scope.setExtra("shared", "isolation");
  scope.setExtra("isolation", "data");
});

Sentry.configureScope(ScopeType.CURRENT, scope -> {
  scope.setExtra("shared", "current");
  scope.setExtra("current", "data");
});

Sentry.captureException(new Exception("my error"));
// --> Will have the following extra:
// { shared: 'current', global: 'data', isolation: 'data', current: 'data' }

Configuring the Scope

There are two main ways to interact with the scope. You can modify the current scope via Sentry.configureScope(scope -> { ... }) and use setters on the resulting scope, or you can use global methods like Sentry.setTag() directly, which will set on the respective scope under the hood (which will be the isolation scope).

You can, for instance, add custom tags or inform Sentry about the currently authenticated user.

import io.sentry.Sentry;
import io.sentry.protocol.User;

Sentry.configureScope(scope -> {
  scope.setTag("my-tag", "my value");
  User user = new User();
  user.setId("42");
  user.setEmail("john.doe@example.com");
  scope.setUser(user);
});

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

import io.sentry.Sentry;

Sentry.configureScope(scope -> {
  scope.setUser(null);
});

Scope Synchronization

If you want to set context data in the Java layer, then receive that context data when a native (C/C++) crash happens, you need to synchronize the Java Scope with the native Scope. This feature was introduced in version 3.0.0 of the Android SDK and requires an opt-in:

<application>
    <meta-data
    android:name="io.sentry.ndk.scope-sync.enable"
    android:value="true"
  />
</application>

To learn what useful information can be associated with scopes see context, tags, users and breadcrumbs.

Local Scopes

We also support pushing and configuring a scope within a single call. This is typically called withScope, pushScope or implemented as a function parameter on the capture methods, depending on the SDK. It's very helpful if you only want to send data for one specific event.

Using Scope Callback Parameter

In the following example we use the scope callback parameter that is available for all capture methods to attach a level and a tag to only one specific error:

import io.sentry.Sentry;
import io.sentry.SentryLevel;

// will be tagged with my-tag="my value"
Sentry.captureException(new Exception("my error"), scope -> {
  scope.setTag("my-tag", "my value");
  scope.setLevel(SentryLevel.WARNING);
});

// will not be tagged with my-tag
Sentry.captureException(new Exception("my error"));

Before the callback is invoked the SDK creates a clone of the current scope, and the changes made will stay isolated within the callback function. This allows you to more easily isolate pieces of context information to specific locations in your code or even call clear to briefly remove all context information.