Skip to main content
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: '[email protected]',
  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