Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/getsentry/sentry-javascript/llms.txt

Use this file to discover all available pages before exploring further.

The Scope class holds additional event information such as breadcrumbs, user context, tags, and extra data. Scopes are used to attach metadata to events.

​
Overview

Scopes contain:
  • User information
  • Breadcrumbs trail
  • Tags and extra data
  • Context data
  • Event processors
  • Propagation context for distributed tracing

​
Class Definition

export class Scope {
  protected _eventProcessors: EventProcessor[];
  protected _breadcrumbs: Breadcrumb[];
  protected _user: User;
  protected _tags: { [key: string]: Primitive };
  protected _attributes: RawAttributes<Record<string, unknown>>;
  protected _extra: Extras;
  protected _contexts: Contexts;
  protected _attachments: Attachment[];
  protected _propagationContext: PropagationContext;
  protected _sdkProcessingMetadata: SdkProcessingMetadata;
  protected _fingerprint?: string[];
  protected _level?: SeverityLevel;
  protected _transactionName?: string;
  protected _session?: Session;
  protected _client?: Client;
  protected _lastEventId?: string;
  protected _conversationId?: string;

  public constructor();
}

​
Constructor

Creates a new Scope instance with default values. 
const scope = new Scope();

​
Methods

​
clone

Clone all data from this scope into a new scope. 
public clone(): Scope
Returns: A new Scope instance with copied data. Example: 
const newScope = scope.clone();
newScope.setTag('cloned', 'true');

​
setUser

Set the user for this scope. 
public setUser(user: User | null): this
​
user
User | null
required
User information. Set to null to unset the user.
Returns: The Scope instance for chaining. Example: 
scope.setUser({
  id: '123',
  email: 'user@example.com',
  username: 'johndoe',
  ip_address: '{{auto}}'
});

​
getUser

Get the user from this scope. 
public getUser(): User | undefined
Returns: The user object or undefined.

​
setTag

Set a tag on the scope. 
public setTag(key: string, value: Primitive): this
​
key
string
required
The tag name.
​
value
Primitive
required
The tag value (string, number, boolean, null, or undefined).
Example: 
scope
  .setTag('environment', 'production')
  .setTag('version', '1.2.3')
  .setTag('userId', 12345);

​
setTags

Set multiple tags at once. 
public setTags(tags: { [key: string]: Primitive }): this
​
tags
Record<string, Primitive>
required
Object containing tag key-value pairs.
Example: 
scope.setTags({
  environment: 'production',
  version: '1.2.3',
  server: 'web-01'
});

​
setExtra

Set extra data on the scope. 
public setExtra(key: string, extra: Extra): this
​
key
string
required
The extra data key.
​
extra
Extra
required
Any value to attach as extra data.
Example: 
scope.setExtra('requestData', {
  body: req.body,
  query: req.query,
  params: req.params
});

​
setExtras

Set multiple extra data fields at once. 
public setExtras(extras: Extras): this
​
extras
Extras
required
Object containing extra data key-value pairs.

​
setContext

Set context data. 
public setContext(key: string, context: Context | null): this
​
key
string
required
The context key (e.g., ‘os’, ‘device’, ‘app’).
​
context
Context | null
required
Context data object. Set to null to remove the context.
Example: 
scope.setContext('app', {
  app_name: 'my-app',
  app_version: '1.0.0',
  app_build: '123'
});

scope.setContext('device', {
  name: 'iPhone 14',
  family: 'iOS',
  model: 'iPhone14,3'
});

​
setContexts

Set multiple contexts at once. 
public setContexts(contexts: Contexts): this
​
contexts
Contexts
required
Object containing context data.

​
setLevel

Set the severity level. 
public setLevel(level: SeverityLevel): this
​
level
SeverityLevel
required
One of: 'fatal', 'error', 'warning', 'info', 'debug', or 'log'.
Example: 
scope.setLevel('warning');

​
setFingerprint

Set the fingerprint for grouping events. 
public setFingerprint(fingerprint: string[]): this
​
fingerprint
string[]
required
Array of strings to group events by.
Example: 
// Group by custom logic
scope.setFingerprint(['{{ default }}', 'custom-group']);

// Force separate issue
scope.setFingerprint(['database-connection-error', dbHost]);

​
addBreadcrumb

Add a breadcrumb to the scope. 
public addBreadcrumb(
  breadcrumb: Breadcrumb,
  maxBreadcrumbs?: number
): this
​
breadcrumb
Breadcrumb
required
The breadcrumb to add. See Breadcrumb Types for details.
​
maxBreadcrumbs
number
Maximum number of breadcrumbs to store. Defaults to 100.
Example: 
scope.addBreadcrumb({
  type: 'http',
  category: 'fetch',
  message: 'GET /api/users',
  level: 'info',
  data: {
    url: '/api/users',
    method: 'GET',
    status_code: 200
  },
  timestamp: Date.now() / 1000
});

​
getLastBreadcrumb

Get the most recent breadcrumb. 
public getLastBreadcrumb(): Breadcrumb | undefined
Returns: The last breadcrumb or undefined.

​
clearBreadcrumbs

Clear all breadcrumbs from the scope. 
public clearBreadcrumbs(): this

​
addEventProcessor

Add an event processor to the scope. 
public addEventProcessor(callback: EventProcessor): this
​
callback
EventProcessor
required
Function that processes events before they are sent.
Example: 
scope.addEventProcessor((event) => {
  // Filter out sensitive data
  if (event.request?.data) {
    delete event.request.data.password;
  }
  return event;
});

​
addAttachment

Add an attachment to the scope. 
public addAttachment(attachment: Attachment): this
​
attachment
Attachment
required
File attachment to include with events.
Example: 
scope.addAttachment({
  filename: 'log.txt',
  data: logBuffer,
  contentType: 'text/plain'
});

​
clear

Clear all data from the scope. 
public clear(): this

​
getPropagationContext

Get the propagation context for distributed tracing. 
public getPropagationContext(): PropagationContext
Returns: The propagation context containing trace and span IDs.

​
setPropagationContext

Set the propagation context. 
public setPropagationContext(context: PropagationContext): this
​
context
PropagationContext
required
Propagation context with traceId, spanId, and other tracing data.

​
Scope Data

The scope data interface represents the normalized data: 
export interface ScopeData {
  eventProcessors: EventProcessor[];
  breadcrumbs: Breadcrumb[];
  user: User;
  tags: { [key: string]: Primitive };
  attributes?: RawAttributes<Record<string, unknown>>;
  extra: Extras;
  contexts: Contexts;
  attachments: Attachment[];
  propagationContext: PropagationContext;
  sdkProcessingMetadata: SdkProcessingMetadata;
  fingerprint: string[];
  level?: SeverityLevel;
  transactionName?: string;
  span?: Span;
  conversationId?: string;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us