Client

Base implementation for all JavaScript SDK clients

The Client class is the base implementation for all JavaScript SDK clients. It handles event capture, transport, integrations, and lifecycle management.

Overview

The Client is responsible for:

• Capturing exceptions, messages, and events
• Managing integrations and event processors
• Sending data to Sentry via transports
• Managing scope and session data

Class Definition

export abstract class Client<O extends ClientOptions = ClientOptions> {
  protected readonly _options: O;
  protected readonly _dsn?: DsnComponents;
  protected readonly _transport?: Transport;
  protected _integrations: IntegrationIndex;
  protected _numProcessing: number;
  protected _eventProcessors: EventProcessor[];
  protected _outcomes: { [key: string]: number };
  protected _hooks: Record<string, Set<Function>>;
  protected _promiseBuffer: PromiseBuffer<unknown>;

  protected constructor(options: O);
}

Constructor

options · ClientOptions · required

Configuration options for the client. See Configuration Options for details.

Methods

captureException

Captures an exception event and sends it to Sentry.

public captureException(
  exception: unknown,
  hint?: EventHint,
  scope?: Scope
): string

exception · unknown · required

The exception to capture. Can be an Error object or any value.

hint · EventHint

Additional information about the exception context.

scope · Scope

The scope containing event metadata. If not provided, uses the current scope.

Returns: string - The event ID of the captured exception.

Example:

const client = new NodeClient(options);
const eventId = client.captureException(new Error('Something went wrong'), {
  originalException: error,
  data: { userId: '123' }
}, scope);

captureMessage

Captures a message event and sends it to Sentry.

public captureMessage(
  message: ParameterizedString,
  level?: SeverityLevel,
  hint?: EventHint,
  currentScope?: Scope
): string

message · ParameterizedString | string · required

The message to capture.

level · SeverityLevel

The severity level: 'fatal', 'error', 'warning', 'info', or 'debug'.

hint · EventHint

Additional information about the message context.

currentScope · Scope

The scope containing event metadata.

Returns: string - The event ID of the captured message.

Example:

const eventId = client.captureMessage(
  'User login failed',
  'warning',
  { data: { username: 'john' } }
);

captureEvent

Captures a manually created event and sends it to Sentry.

public captureEvent(
  event: Event,
  hint?: EventHint,
  currentScope?: Scope
): string

event · Event · required

The event object to send. See Event Types for structure.

hint · EventHint

Additional metadata about the event.

currentScope · Scope

The scope containing event metadata.

Returns: string - The event ID.

flush

Wait for all events to be sent or the timeout to expire.

public async flush(timeout?: number): Promise<boolean>

timeout · number

Maximum time in milliseconds to wait. Omitting this will wait until all events are sent.

Returns: Promise<boolean> - true if all events are sent before timeout, false otherwise.

Example:

// Flush with 5 second timeout
const success = await client.flush(5000);
if (!success) {
  console.warn('Some events were not sent');
}

close

Flush the event queue and disable the client.

public async close(timeout?: number): Promise<boolean>

timeout · number

Maximum time in milliseconds to wait before shutting down.

Returns: Promise<boolean> - true if flush completes successfully, false otherwise.

Example:

// Clean shutdown
await client.close(2000);

getDsn

Get the current DSN.

public getDsn(): DsnComponents | undefined

Returns: The parsed DSN components or undefined if no DSN is configured.

getOptions

Get the client options.

public getOptions(): O

Returns: The options passed to the client constructor.

getTransport

Get the transport used by the client.

public getTransport(): Transport | undefined

Returns: The transport instance or undefined if not initialized.

addIntegration

Add an integration to the client at runtime.

public addIntegration(integration: Integration): void

integration · Integration · required

The integration to add.

Example:

import { httpIntegration } from '@sentry/node';

client.addIntegration(httpIntegration());

getIntegrationByName

Get an installed integration by name.

public getIntegrationByName<T extends Integration = Integration>(
  integrationName: string
): T | undefined

integrationName · string · required

The name of the integration.

Returns: The integration instance or undefined.

addEventProcessor

Add an event processor that applies to all events.

public addEventProcessor(eventProcessor: EventProcessor): void

eventProcessor · EventProcessor · required

A function that processes events before they are sent.

Example:

client.addEventProcessor((event, hint) => {
  // Modify event before sending
  event.tags = { ...event.tags, processed: 'true' };
  return event;
});

on

Register a callback for lifecycle hooks.

public on(
  hook: 'spanStart' | 'spanEnd' | 'beforeSendEvent' | 'flush' | ...,
  callback: Function
): () => void

Returns: A function that removes the registered callback.

Example:

const unsubscribe = client.on('spanStart', (span) => {
  console.log('Span started:', span.spanContext().spanId);
});

// Later, remove the callback
unsubscribe();

emit

Emit a hook event.

public emit(hook: string, ...args: unknown[]): void

Hooks

The Client supports various lifecycle hooks:

• spanStart - Fired when a span starts
• spanEnd - Fired when a span ends
• beforeSendEvent - Fired before sending an event
• afterSendEvent - Fired after sending an event
• beforeAddBreadcrumb - Fired before adding a breadcrumb
• flush - Fired when flushing
• close - Fired when closing

Related

• Configuration Options
• Transport
• Scope
• Integrations