Scopes

Manage contextual data for events using Sentry’s scope system

Sentry uses a three-tier scope system to manage contextual data: Global Scope, Isolation Scope, and Current Scope. Understanding these scopes is essential for properly organizing your error tracking.

Scope Types

Global Scope

The global scope applies to all events in your application:

import * as Sentry from '@sentry/browser';

const globalScope = Sentry.getGlobalScope();
globalScope.setTag('app_version', '2.1.0');
globalScope.setUser({
  id: 'global-user',
  environment: 'production'
});

Isolation Scope

The isolation scope is active for the current execution context (e.g., per request in Node.js, per page in browsers):

const isolationScope = Sentry.getIsolationScope();
isolationScope.setTag('request_id', '123-456');
isolationScope.setContext('session', {
  started_at: Date.now(),
  page_views: 5
});

Current Scope

The current scope is the most local scope, typically used for individual operations:

const currentScope = Sentry.getCurrentScope();
currentScope.setTag('operation', 'checkout');

Data from all three scopes is merged when an event is sent. More specific scopes override less specific ones: Current Scope > Isolation Scope > Global Scope.

Working with Scopes

Creating Temporary Scopes

Use withScope() to create a temporary scope for specific operations:

Sentry.withScope((scope) => {
  scope.setTag('section', 'payment');
  scope.setLevel('warning');
  scope.setContext('payment', {
    method: 'credit_card',
    amount: 99.99
  });
  
  Sentry.captureMessage('Payment processed');
});
// Scope is automatically cleaned up here

Creating Isolation Scopes

Create a new isolation scope for separate execution contexts:

Sentry.withIsolationScope((isolationScope) => {
  isolationScope.setUser({
    id: 'user-123',
    email: '[e-mail]'
  });
  
  isolationScope.setTag('tenant', 'acme-corp');
  
  // All operations here share this isolation scope
  doWork();
});

Using withIsolationScope() in environments without an async context strategy (like browsers) may lead to unexpected behavior. This function is primarily designed for server-side environments.

Setting Scope Data

User Information

Set user information on any scope:

Sentry.setUser({
  id: 'user-123',
  email: '[e-mail]',
  username: 'john_doe',
  ip_address: '{{auto}}' // Use 'auto' for automatic IP detection
});

// Clear user data
Sentry.setUser(null);

Tags

Tags are searchable key-value pairs:

// Set a single tag
Sentry.setTag('environment', 'production');

// Set multiple tags
Sentry.setTags({
  environment: 'production',
  version: '2.1.0',
  feature: 'checkout'
});

// Unset a tag
Sentry.setTag('feature', undefined);

Extra Data

Extra data provides additional context (not searchable):

// Set a single extra field
Sentry.setExtra('cart_items', [
  { id: 1, name: 'Product A' },
  { id: 2, name: 'Product B' }
]);

// Set multiple extra fields
Sentry.setExtras({
  cart_total: 149.98,
  shipping_method: 'express',
  coupon_code: 'SAVE10'
});

Context

Context provides structured data for specific categories:

Sentry.setContext('character', {
  name: 'Mighty Fighter',
  level: 19,
  character_class: 'Warrior'
});

Sentry.setContext('device', {
  model: 'iPhone 14',
  os: 'iOS 16.0',
  memory: '6GB'
});

// Remove a context
Sentry.setContext('device', null);

Attributes

Attributes are applied to logs and metrics (and spans in the future):

import { getCurrentScope } from '@sentry/browser';

const scope = getCurrentScope();

// Set attributes
scope.setAttributes({
  is_admin: true,
  payment_selection: 'credit_card',
  render_duration: { value: 250, unit: 'ms' }
});

// Set a single attribute
scope.setAttribute('user_role', 'admin');

// Remove an attribute
scope.removeAttribute('user_role');

Currently, only strings, numbers, and boolean attributes are fully supported. More complex types will be added in future versions.

Scope Manipulation

Cloning Scopes

import { getCurrentScope } from '@sentry/browser';

const originalScope = getCurrentScope();
const clonedScope = originalScope.clone();

clonedScope.setTag('is_clone', true);

Clearing Scopes

import { getCurrentScope } from '@sentry/browser';

const scope = getCurrentScope();
scope.clear(); // Removes all data except the client

Updating Scopes

import { getCurrentScope } from '@sentry/browser';

const scope = getCurrentScope();

// Update with an object
scope.update({
  tags: { feature: 'beta' },
  user: { id: '123' },
  level: 'warning'
});

// Update with a function
scope.update((scope) => {
  scope.setTag('processed', true);
  return scope;
});

Scope Listeners

Listen to scope changes:

import { getCurrentScope } from '@sentry/browser';

const scope = getCurrentScope();

scope.addScopeListener((updatedScope) => {
  console.log('Scope updated:', updatedScope.getScopeData());
});

Advanced Patterns

Setting Transaction Names

import { getCurrentScope } from '@sentry/browser';

const scope = getCurrentScope();
scope.setTransactionName('/checkout/payment');

Setting the transaction name on the scope does NOT change the name of the active span. Use Sentry.updateSpanName() to change the active span’s name.

Fingerprinting

Group similar errors together:

import { getCurrentScope } from '@sentry/browser';

const scope = getCurrentScope();
scope.setFingerprint(['{{ default }}', 'payment-error']);

Setting Severity Level

import { getCurrentScope } from '@sentry/browser';

const scope = getCurrentScope();
scope.setLevel('warning');

Best Practices

1. Use the right scope: Global scope for app-wide data, isolation scope for request/session data, current scope for operation-specific data
2. Clean up temporary scopes: Always use withScope() for temporary data to ensure proper cleanup
3. Avoid polluting global scope: Only set truly global data on the global scope
4. Be mindful of async operations: Scope data may not persist across async boundaries in some environments

Next Steps

Context

Learn more about context types and structured data

Breadcrumbs

Add breadcrumbs to track user actions

Performance

Associate performance data with scopes

Error Monitoring

Capture errors with scope context