APIs

function init(options: InitOptions): Client | undefined

Initialize the SDK with the given options. See Options for the options you can pass to init.

function getClient(): Client | undefined

Returns the currently active client.

function setCurrentClient(client: Client): void

Make the given client the current client. You do not need this if you use init(), this is only necessary if you are manually setting up a client.

function lastEventId(): string | undefined

Returns the ID of the last sent error event. Note that this does not guarantee that this event ID exists, as it may have been dropped along the way.

function flush(timeout?: number): Promise<boolean>

number

Flushes all pending events.

function isEnabled(): boolean

Returns true if the SDK is initialized & enabled.

function close(timeout?: number): Promise<boolean>

number

Flushes all pending events and disables the SDK. Note that this does not remove any listeners the SDK may have set up. After a call to close, the current client cannot be used anymore. It's important to only call close immediately before shutting down the application.

Alternatively, the flush method drains the event queue while keeping the client enabled for continued use.

function addEventProcessor(processor: EventProcessor): void

(event: Event, hint: EventHint) => Event | null | Promise<Event | null>

Adds an event processor to the SDK. An event processor receives every event before it is sent to Sentry. It can either mutate the event (and return it) or return null to discard the event. Event processors can also return a promise, but it is recommended to use this only when necessary as it slows down event processing.

Event processors added via Sentry.addEventProcessor() will be applied to all events in your application. If you want to add an event processor that only applies to certain events, you can also add one to a scope as follows:

Sentry.withScope((scope) => {
  scope.addEventProcessor((event) => {
    // this will only be applied to events captured within this scope
    return event;
  });

  Sentry.captureException(new Error("test"));
});

function addIntegration(integration: Integration): void

Adds an integration to the SDK. This can be used to conditionally add integrations after Sentry.init() has been called. Note that it is recommended to pass integrations to init instead of calling this method, where possible.

See Integrations for more information on how to use integrations.

function captureException(
exception: unknown,
captureContext?: CaptureContext
): EventId

unknown

CaptureContext {
user?: User {
id?: string | number,
email?: string,
ip_address?: string,
username?: string,
}
level?: "fatal" | "error" | "warning" | "log" | "info" | "debug",
// Additional data that should be sent with the exception.
extra?: Record<string, unknown>,
// Additional tags that should be sent with the exception.
tags?: Record<string, string>,
contexts?: Record<string, Record<string, unknown>>,
fingerprint?: string[],
}

Capture an exception event and send it to Sentry. Note that you can pass not only Error objects, but also other objects as exception - in that case, the SDK will attempt to serialize the object for you, and the stack trace will be generated by the SDK and may be less accurate.

function captureMessage(
message: string,
captureContext?: CaptureContext | SeverityLevel
): EventId

string

CaptureContext {
user?: User {
id?: string | number,
email?: string,
ip_address?: string,
username?: string,
}
level?: "fatal" | "error" | "warning" | "log" | "info" | "debug",
// Additional data that should be sent with the exception.
extra?: Record<string, unknown>,
// Additional tags that should be sent with the exception.
tags?: Record<string, string>,
contexts?: Record<string, Record<string, unknown>>,
fingerprint?: string[],
}

Capture a message event and send it to Sentry. Optionally, instead of a CaptureContext, you can also pass a SeverityLevel as second argument, e.g. "error" or "warning".

Messages show up as issues on your issue stream, with the message as the issue name.

function setTag(key: string, value: string): void

Set a tag to be sent with Sentry events.

function setTags(tags: Record<string, string>): void

Set multiple tags to be sent with Sentry events.

function setContext(name: string, context: Record<string, unknown>): void

Set a context to be sent with Sentry events. Custom contexts allow you to attach arbitrary data to an event. You cannot search these, but they are viewable on the issue page - if you need to be able to filter for certain data, use tags instead.

There are no restrictions on context name. In the context object, all keys are allowed except for type, which is used internally.

By default, Sentry SDKs normalize nested structured context data up to three levels deep. Any data beyond this depth will be trimmed and marked using its type instead. To adjust this default, use the normalizeDepth SDK option.

Learn more about conventions for common contexts in the contexts interface developer documentation.

Sentry.setContext("character", {
  name: "Mighty Fighter",
  age: 19,
  attack_type: "melee",
});

function setExtra(name: string, extra: unknown): void

Set additional data to be sent with Sentry events.

function setExtras(extras: Record<string, unknown>): void

Set multiple additional data entries to be sent with Sentry events.

function setUser(user: User | null): void

User {
// Your internal identifier for the user
id?: string | number,
// Sentry is aware of email addresses and can display things such as Gravatars and unlock messaging capabilities
email?: string,
// Typically used as a better label than the internal id
username?: string,
// The user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user
ip_address?: string,
}

Set a user to be sent with Sentry events. Set to null to unset the user. In addition to the specified properties of the User object, you can also add additional arbitrary key/value pairs.

function addBreadcrumb(breadcrumb: Breadcrumb, hint?: Hint): void

Breadcrumb {
// If a message is provided, it is rendered as text with all whitespace preserved.
message?: string,
// The type influences how a breadcrumb is rendered in Sentry. When in doubt, leave it at `default`.
type?: "default" | "debug" | "error" | "info" | "navigation" | "http" | "query" | "ui" | "user",
// The level is used in the UI to emphasize or deemphasize the breadcrumb.
level?: "fatal" | "error" | "warning" | "log" | "info" | "debug",
// Typically it is a module name or a descriptive string. For instance, `ui.click` could be used to indicate that a click happened
category?: string,
// Additional data that should be sent with the breadcrumb.
data?: Record<string, unknown>,
}

Record<string, unknown>

You can manually add breadcrumbs whenever something interesting happens. For example, you might manually record a breadcrumb if the user authenticates or another state change occurs.

function startSpan<T>(options: StartSpanOptions, callback: (span: Span) => T): T

StartSpanOptions {
name: string,
// Attributes to add to the span.
attributes?: Record<string, string | number | boolean | null | undefined>,
// The timestamp to use for the span start. If not provided, the current time will be used.
startTime?: number,
// The operation name for the span. This is used to group spans in the UI
op?: string,
// If true, the span will be forced to be sent as a transaction, even if it is not the root span.
forceTransaction?: boolean,
// The parent span for the new span. If not provided, the current span will be used.
parentSpan?: Span | null,
// If true, the span will only be created if there is an active span.
onlyIfParent?: boolean,
}

(span: Span) => T

Starts a new span, that is active in the provided callback. This span will be a child of the currently active span, if there is one.

Any spans created inside of the callback will be children of this span.

The started span will automatically be ended when the callback returns, and will thus measure the duration of the callback. The callback cann also be an async function.

// Synchronous example
Sentry.startSpan({ name: "my-span" }, (span) => {
  measureThis();
});

// Asynchronous example
const status = await Sentry.startSpan(
  { name: "my-span" },
  async (span) => {
    const status = await doSomething();
    return status;
  },
);

See Tracing Instrumentation for more information on how to work with spans.

function startInactiveSpan<T>(options: StartSpanOptions): Span

StartSpanOptions {
name: string,
// Attributes to add to the span.
attributes?: Record<string, string | number | boolean | null | undefined>,
// The timestamp to use for the span start. If not provided, the current time will be used.
startTime?: number,
// The operation name for the span. This is used to group spans in the UI
op?: string,
// If true, the span will be forced to be sent as a transaction, even if it is not the root span.
forceTransaction?: boolean,
// The parent span for the new span. If not provided, the current span will be used.
parentSpan?: Span | null,
// If true, the span will only be created if there is an active span.
onlyIfParent?: boolean,
}

Starts a new span. This span will be a child of the currently active span, if there is one. The returned span has to be ended manually via span.end() when the span is done.

const span = Sentry.startInactiveSpan({ name: "my-span" });
doSomething();
span.end();

See Tracing Instrumentation for more information on how to work with spans.

function startSpanManual<T>(options: StartSpanOptions, callback: (span: Span) => T): T

StartSpanOptions {
name: string,
// Attributes to add to the span.
attributes?: Record<string, string | number | boolean | null | undefined>,
// The timestamp to use for the span start. If not provided, the current time will be used.
startTime?: number,
// The operation name for the span. This is used to group spans in the UI
op?: string,
// If true, the span will be forced to be sent as a transaction, even if it is not the root span.
forceTransaction?: boolean,
// The parent span for the new span. If not provided, the current span will be used.
parentSpan?: Span | null,
// If true, the span will only be created if there is an active span.
onlyIfParent?: boolean,
}

(span: Span) => T

Starts a new span, that is active in the provided callback. This span will be a child of the currently active span, if there is one.

Any spans created inside of the callback will be children of this span.

The started span will not automatically end - you have to call span.end() when the span is done. Please note that the span will still only be the parent span of spans created inside of the callback, while the callback is active. In most cases, you will want to use startSpan or startInactiveSpan instead.

const status = await Sentry.startSpanManual(
  { name: "my-span" },
  async (span) => {
    const status = await doSomething();
    span.end();
    return status;
  },
);

See Tracing Instrumentation for more information on how to work with spans.

function continueTrace<T>(options: TraceOptions, callback: () => T): T

TraceOptions {
// The sentry-trace header.
sentryTrace?: string,
// The baggage header.
baggage?: string,
}

() => T

Continues a trace in the provided callback. Any spans created inside of the callback will be linked to the trace.

function suppressTracing<T>(callback: () => T): T

Ensure that all spans created inside of the provided callback are not sent to Sentry.

function startNewTrace<T>(callback: () => T): T

Start a new trace that is active in the provided callback.

function spanToJSON(span: Span): SpanJSON

Convert a span to a JSON object.

function updateSpanName(span: Span, name: string): void

Update the name of a span. Use this over span.updateName(name) to ensure that the span is updated in all backends.

function getActiveSpan(): Span | undefined

Get the currently active span.

function getRootSpan(span: Span): Span

Get the root span of a span.

function withActiveSpan<T>(span: Span | null, callback: () => T): T

Runs the provided callback with the given span as the active span. If null is provided, the callback will have no active span.

function startSession(): void

Starts a new session.

function endSession(): void

Ends the current session (but does not send it to Sentry).

function captureSession(end = false): void

Sends the current session on the scope to Sentry. Pass true as argument to end the session first.

function withScope(callback: (scope: Scope) => void): void

Forks the current scope and calls the callback with the forked scope.

function withIsolationScope(callback: (scope: Scope) => void): void

Forks the current isolation scope and calls the callback with the forked scope.

function getCurrentScope(): Scope

Returns the current scope.

Note that in most cases you should not use this API, but instead use withScope to generate and access a local scope. There are no guarantees about the consistency of getCurrentScope across different parts of your application, as scope forking may happen under the hood at various points.

function getIsolationScope(): Scope

Returns the current

.

function getGlobalScope(): Scope

Returns the

.

function captureFeedback(feedback: Feedback, hint?: Hint): string

Feedback {
message: string,
name?: string,
email?: string,
url?: string,
source?: string,
// The event id that this feedback is associated with.
associatedEventId?: string,
tags?: Record<string, string>,
}

Hint {
// Optional additional data to attach to the Sentry event.
captureContext?: CaptureContext {
user?: User {
id?: string | number,
email?: string,
ip_address?: string,
username?: string,
}
level?: "fatal" | "error" | "warning" | "log" | "info" | "debug",
// Additional data that should be sent with the exception.
extra?: Record<string, unknown>,
// Additional tags that should be sent with the exception.
tags?: Record<string, string>,
contexts?: Record<string, Record<string, unknown>>,
fingerprint?: string[],
}
}

Send user feedback to Sentry.

function getFeedback(): ReturnType<feedbackIntegration> | undefined

Get the feedback integration, if it has been added. This can be used to access the feedback integration in a type-safe way.

function sendFeedback(feedback: Feedback, hint?: Hint): Promise<string>

Feedback {
message: string,
name?: string,
email?: string,
url?: string,
source?: string,
// The event id that this feedback is associated with.
associatedEventId?: string,
tags?: Record<string, string>,
}

Hint {
// Optional additional data to attach to the Sentry event.
captureContext?: CaptureContext {
user?: User {
id?: string | number,
email?: string,
ip_address?: string,
username?: string,
}
level?: "fatal" | "error" | "warning" | "log" | "info" | "debug",
// Additional data that should be sent with the exception.
extra?: Record<string, unknown>,
// Additional tags that should be sent with the exception.
tags?: Record<string, string>,
contexts?: Record<string, Record<string, unknown>>,
fingerprint?: string[],
}
}

This method is similar to captureFeedback, but it returns a promise that resolves only when the feedback was successfully sent to Sentry. It will reject if the feedback cannot be sent.