Scope

Holds additional event information and context data

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: '[e-mail]',
  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;
}

Related

• User Types
• Breadcrumb Types
• Event Types
• Client