Scopes

The implementation in each SDK MUST consist of three types of scopes:

• The global scope
• The isolation scope
• The current scope

Users MUST be able to add data such as tags, breadcrumbs, and context to any scope, regardless of its type.

Choosing the Right Scope

Global Scope

The global scope functions as a persistent global variable throughout the application's execution. Any data assigned to this scope is automatically applied to all events emitted by the SDK.

It is typically used to store application-wide data, such as the release, environment, and similar context.

Isolation Scope

The isolation scope MUST contain data specific to the current execution context: a single request (on a server), a single tab (in a browser), or a single user session (on mobile). Top-level SDK APIs, such as sentry.setTag() and sentry.setContext() MUST write to the isolation scope.

The isolation scope SHOULD be implemented using a context variable, thread-local storage, async-local storage, or an equivalent mechanism appropriate for the platform.

SDK integrations MUST handle the forking of isolation scopes automatically. Users MUST NOT need to manage or be concerned with the details of scope isolation or its forking process.

Current Scope

The current scope MUST maintain data for the active span. When a new span is started, the current scope of the parent span is forked (i.e., duplicated), transferring all data from the parent span to the new span. This allows modifications or additions specific to the new span without affecting the parent span. This behavior aligns with a "copy-on-write" model.

Any changes made to the current scope after forking MUST NOT impact the forked scope.

The current scope SHOULD be implemented using a context variable, thread-local storage, async-local storage, or an equivalent mechanism appropriate for the platform.

Users MAY fork the current scope explicitly by invoking sentry.withScope() or implicitly by starting a new span.

Applying Scope Data to Events

Data from all three scope types MUST be merged in a specific order before being applied to an event. The process is as follows:

1. data from the global scope is...
2. merged with data from the isolation scope, which is...
3. merged with data from the current scope, which is ...
4. applied to the event

Scope Methods

Setting Attributes

Users MUST be able to attach attributes to any scope using a dedicated method (e.g., scope.setAttributes() or scope.setAttribute()). These attributes follow the structure defined in the Attributes documentation.

Attributes are key-value pairs where each value is either an attribute value or an object containing:

• value: The actual attribute value, which MUST match the specified type
• unit (optional): The unit of measurement. See Units for the full list of supported units.
  • SDKs MAY delay adding support for units for the moment, but MUST be able to do so at a later date without a breaking change.
• type (optional): The type of the attribute. See Supported Types for the full list. SDKs SHOULD NOT expose this to users if they can reliably infer the type from the value. If not, SDKs MAY allow or require users to set the type explicitly.

Example Usage

Sentry.getGlobalScope().setAttributes({
  "app.feature_flag.enabled": true,
  "app.session_duration": {
    value: 3600,
    unit: "second",
  },
});

Method Signature

The method SHOULD accept a dictionary/map/object where:

• Keys are attribute names (strings)
• Values are either directly values or attribute objects/dictionaries with value, and optionally unit properties (see example).
• The SDK SHOULD infer the type of the attribute at serialization time to spare users from setting a (potentially incorrect) type. Depending on platform or constraints, the SDK MAY instead also allow or require users to set the type explicitly.

Behavior

• Attributes set on the global scope MUST be applied to all logs and metrics
• Attributes set on the isolation scope MUST be applied to all logs and metrics in that execution context
• Attributes set on the current scope MUST be applied only to the logs and metrics that are captured while that current scope is active
• When the same attribute key exists in multiple scopes, the more specific scope's value takes precedence (current > isolation > global)
• When the same attribute key exists on the current log or metric, it MUST take precedence over an attribute with the same key set on any scope (log/metric > current > isolation > global)
• The SDK SHOULD keep the attribute format consistent with the user-set format until user-provided processing callbacks like before_send_log have been called. This ensures compatibility with already existing callbacks and avoids unexpected changes to the attribute format.
• Calling scope.clear() MUST remove all attributes from the corresponding scope.

See Attributes for detailed information about attribute structure, supported types, units, and common attribute keys. Also see Sentry Conventions for the complete attribute registry.

Removing Attributes

Users MUST be able to remove attributes set on any scope using a dedicated method, e.g. scope.removeAttribute().

Example Usage

Sentry.getGlobalScope().removeAttribute("app.feature_flag.enabled");

Related Documents

This document provides a concise summary of the Hub & Scope Refactoring, focusing on implementation details and expected features. The original document remains unchanged, offering additional historical context and migration strategies.