Interface NodeOptions

Options which are in beta, or otherwise not guaranteed to be stable.

Set of metadata about the SDK that can be internally used to enhance envelopes and events, and provide additional data about every request.

This option is not part of the public API and is subject to change at any time.

A pattern for error URLs which should exclusively be sent to Sentry. This is the opposite of CoreOptions.denyUrls. By default, all errors will be sent.

Behavior of the allowUrls option is controlled by the Sentry.eventFiltersIntegration integration. If the event filters integration is not installed, the allowUrls option will not have any effect.

When enabled, stack traces are automatically attached to all events captured with Sentry.captureMessage.

Grouping in Sentry is different for events with stack traces and without. As a result, you will get new groups as you enable or disable this flag for certain events.

A callback invoked when adding a breadcrumb, allowing to optionally modify it before adding it to future events.

Note that you must return a valid breadcrumb from this callback. If you do not wish to modify the breadcrumb, simply return it at the end. Returning null will cause the breadcrumb to be dropped.

An event-processing callback for error and message events, guaranteed to be invoked after all other event processors, which allows an event to be modified or dropped.

Note that you must return a valid event from this callback. If you do not wish to modify the event, simply return it at the end. Returning null will cause the event to be dropped.

An event-processing callback for logs, guaranteed to be invoked after all other log processors. This allows a log to be modified or dropped before it's sent.

Note that you must return a valid log from this callback. If you do not wish to modify the log, simply return it at the end. Returning null will cause the log to be dropped.

An event-processing callback for metrics, guaranteed to be invoked after all other metric processors. This allows a metric to be modified or dropped before it's sent.

Note that you must return a valid metric from this callback. If you do not wish to modify the metric, simply return it at the end. Returning null will cause the metric to be dropped.

This function can be defined to modify a child span before it's sent.

An event-processing callback for transaction events, guaranteed to be invoked after all other event processors. This allows an event to be modified or dropped before it's sent.

Note that you must return a valid event from this callback. If you do not wish to modify the event, simply return it at the end. Returning null will cause the event to be dropped.

Configures in which interval client reports will be flushed. Defaults to 60_000 (milliseconds).

Enable debug functionality in the SDK itself. If debug is set to true the SDK will attempt to print out useful debugging information about what the SDK is doing.

If this is set to false, default integrations will not be added, otherwise this will internally be set to the recommended default integrations.

A pattern for error URLs which should not be sent to Sentry. To allow certain errors instead, use CoreOptions.allowUrls. By default, all errors will be sent.

Behavior of the denyUrls option is controlled by the Sentry.eventFiltersIntegration integration. If the event filters integration is not installed, the denyUrls option will not have any effect.

By default, the SDK will try to identify problems with your instrumentation setup and warn you about it. If you want to disable these warnings, set this to true.

Sets the distribution of the application. Distributions are used to disambiguate build or deployment variants of the same release of an application.

The DSN tells the SDK where to send the events. If this is not set, the SDK will not send any events to Sentry.

Specifies whether this SDK should send events to Sentry. Setting this to enabled: false doesn't prevent all overhead from Sentry instrumentation. To disable Sentry completely, depending on environment, call `Sentry.init conditionally.

If logs support should be enabled.

If metrics support should be enabled.

Controls whether and how to enhance fetch error messages by appending the request hostname. Generic fetch errors like "Failed to fetch" will be enhanced to include the hostname (e.g., "Failed to fetch (example.com)").

• 'always' (default): Modifies the actual error message directly. This may break third-party packages that rely on exact message matching (e.g., is-network-error, p-retry).
• 'report-only': Only enhances the message when sending to Sentry. The original error message remains unchanged, preserving compatibility with third-party packages.
• false: Disables hostname enhancement completely.

The current environment of your application (e.g. "production").

Environments are case-sensitive. The environment name can't contain newlines, spaces or forward slashes, can't be the string "None", or exceed 64 characters. You can't delete environments, but you can hide them.

A pattern for error messages which should not be sent to Sentry. By default, all errors will be sent.

Behavior of the ignoreErrors option is controlled by the Sentry.eventFiltersIntegration integration. If the event filters integration is not installed, the ignoreErrors option will not have any effect.

A list of span names or patterns to ignore.

If you specify a pattern IgnoreSpanFilter, at least one of the properties (op or name) must be set.

A pattern for transaction names which should not be sent to Sentry. By default, all transactions will be sent.

Behavior of the ignoreTransactions option is controlled by the Sentry.eventFiltersIntegration integration. If the event filters integration is not installed, the ignoreTransactions option will not have any effect.

Include local variables with stack traces.

Requires the LocalVariables integration.

If set to false, the SDK will not automatically detect the serverName.

This is useful if you are using the SDK in a CLI app or Electron where the hostname might be considered PII.

Initial data to populate scope.

List of integrations that should be installed after SDK was initialized. Accepts either a list of integrations or a function that receives default integrations and returns a new, updated list.

The maximum number of breadcrumbs sent with events. Sentry has a maximum payload size of 1MB and any events exceeding that payload size will be dropped.

The max. duration in seconds that the SDK will wait for parent spans to be finished before discarding a span. The SDK will automatically clean up spans that have no finished parent after this duration. This is necessary to prevent memory leaks in case of parent spans that are never finished or otherwise dropped/missing. However, if you have very long-running spans in your application, a shorter duration might cause spans to be discarded too early. In this case, you can increase this duration to a value that fits your expected data.

Defaults to 300 seconds (5 minutes).

Maximum number of chars a single value can have before it will be truncated.

Maximum number of levels that normalization algorithm will traverse in objects and arrays. Used when normalizing an event before sending, on all of the listed attributes:

• breadcrumbs.data
• user
• contexts
• extra

Maximum number of properties or elements that the normalization algorithm will output in any single array or object included in the normalized event. Used when normalizing an event before sending, on all of the listed attributes:

• breadcrumbs.data
• user
• contexts
• extra

Provide an array of OpenTelemetry Instrumentations that should be registered.

Use this option if you want to register OpenTelemetry instrumentation that the Sentry SDK does not yet have support for.

Provide an array of additional OpenTelemetry SpanProcessors that should be registered.

The organization ID for your Sentry project.

The SDK will try to extract the organization ID from the DSN. If it cannot be found, or if you need to override it, you can provide the ID with this option. The organization ID is used for trace propagation and for features like strictTraceContinuation.

If this is enabled, any spans started will always have their parent be the active root span, if there is any active span.

This is necessary because in some environments (e.g. browser), we cannot guarantee an accurate active span. Because we cannot properly isolate execution environments, you may get wrong results when using e.g. nested startSpan() calls.

To solve this, in these environments we'll by default enable this option.

Set the lifecycle mode of the profiler.

• manual: The profiler will be manually started and stopped via startProfiler/stopProfiler. If a session is sampled, is dependent on the profileSessionSampleRate.
• trace: The profiler will be automatically started when a root span exists and stopped when there are no more sampled root spans. Whether a session is sampled, is dependent on the profileSessionSampleRate and the existing sampling configuration for tracing (tracesSampleRate/tracesSampler).

Sets profiling session sample rate for the entire profiling session (evaluated once per SDK initialization).

Function to compute profiling sample rate dynamically and filter unwanted profiles.

Profiling is enabled if either this or profilesSampleRate is defined. If both are defined, profilesSampleRate is ignored.

Will automatically be passed a context object of default and optional custom data.

Sets profiling sample rate when @sentry/profiling-node is installed

If set to true, the SDK propagates the W3C traceparent header to any outgoing requests, in addition to the sentry-trace and baggage headers. Use the CoreOptions.tracePropagationTargets option to control to which outgoing requests the header will be attached.

Important: If you set this option to true, make sure that you configured your servers' CORS settings to allow the traceparent header. Otherwise, requests might get blocked.

Whether to register ESM loader hooks to automatically instrument libraries. This is necessary to auto instrument libraries that are loaded via ESM imports, but it can cause issues with certain libraries. If you run into problems running your app with this enabled, please raise an issue in https://github.com/getsentry/sentry-javascript.

Defaults to true.

Sets the release. Release names are strings, but some formats are detected by Sentry and might be rendered differently. Learn more about how to send release data so Sentry can tell you about regressions between releases and identify the potential source in the releases documentation

A global sample rate to apply to all error events.

0.0 = 0% chance of a given event being sent (send no events) 1.0 = 100% chance of a given event being sent (send all events)

Send SDK Client Reports, which are used to emit outcomes about events that the SDK dropped or failed to capture.

Controls if potentially sensitive data should be sent to Sentry by default. Note that this only applies to data that the SDK is sending by default but not data that was explicitly set (e.g. by calling Sentry.setUser()).

Sets an optional server name (device name).

This is useful for identifying which server or instance is sending events.

Controls how many milliseconds to wait before shutting down. The default is 2 seconds. Setting this too low can cause problems for sending events from command line applications. Setting it too high can cause the application to block for users with network connectivity problems.

If this is set to true, the SDK will not set up OpenTelemetry automatically. In this case, you have to ensure to set it up correctly yourself, including:

• The SentrySpanProcessor
• The SentryPropagator
• The SentryContextManager
• The SentrySampler

If you use Spotlight by Sentry during development, use this option to forward captured Sentry events to Spotlight.

Either set it to true, or provide a specific Spotlight Sidecar URL.

More details: https://spotlightjs.com/

IMPORTANT: Only set this option to true while developing, not in production!

A stack parser implementation or an array of stack line parsers By default, a stack parser is supplied for all supported browsers

If set to true, the SDK will only continue a trace if the organization ID of the incoming trace found in the baggage header matches the organization ID of the current Sentry client.

The client's organization ID is extracted from the DSN or can be set with the orgId option.

If the organization IDs do not match, the SDK will start a new trace instead of continuing the incoming one. This is useful to prevent traces of unknown third-party services from being continued in your application.

List of strings and/or Regular Expressions used to determine which outgoing requests will have sentry-trace and baggage headers attached.

Default: If this option is not provided, tracing headers will be attached to all outgoing requests. If you are using a browser SDK, by default, tracing headers will only be attached to outgoing requests to the same origin.

Disclaimer: Carelessly setting this option in browser environments may result into CORS errors! Only attach tracing headers to requests to the same origin, or to requests to services you can control CORS headers of. Cross-origin requests, meaning requests to a different domain, for example a request to https://api.example.com/ while you're on https://example.com/, take special care. If you are attaching headers to cross-origin requests, make sure the backend handling the request returns a "Access-Control-Allow-Headers: sentry-trace, baggage" header to ensure your requests aren't blocked.

If you provide a tracePropagationTargets array, the entries you provide will be matched against the entire URL of the outgoing request. If you are using a browser SDK, the entries will also be matched against the pathname of the outgoing requests. This is so you can have matchers for relative requests, for example, /^/api/ if you want to trace requests to your /api routes on the same domain.

If any of the two match any of the provided values, tracing headers will be attached to the outgoing request. Both, the string values, and the RegExes you provide in the array will match if they partially match the URL or pathname.

Examples:

• tracePropagationTargets: [/^/api/] and request to https://same-origin.com/api/posts:
  • Tracing headers will be attached because the request is sent to the same origin and the regex matches the pathname "/api/posts".
• tracePropagationTargets: [/^/api/] and request to https://different-origin.com/api/posts:
  • Tracing headers will not be attached because the pathname will only be compared when the request target lives on the same origin.
• tracePropagationTargets: [/^/api/, 'https://external-api.com'] and request to https://external-api.com/v1/data:
  • Tracing headers will be attached because the request URL matches the string 'https://external-api.com'.

Function to compute tracing sample rate dynamically and filter unwanted traces.

Tracing is enabled if either this or tracesSampleRate is defined. If both are defined, tracesSampleRate is ignored. Set this and tracesSampleRate to undefined to disable tracing.

Will automatically be passed a context object of default and optional custom data.

Sample rate to determine trace sampling.

0.0 = 0% chance of a given trace being sent (send no traces) 1.0 = 100% chance of a given trace being sent (send all traces).

Tracing is enabled if either this or tracesSampler is defined. If both are defined, tracesSampleRate is ignored. Set this and tracesSampler to undefined to disable tracing.

A function that takes transport options and returns the Transport object which is used to send events to Sentry. The function is invoked internally during SDK initialization. By default, the SDK initializes its default transports.

Options for the default transport that the SDK uses.

A URL to an envelope tunnel endpoint. An envelope tunnel is an HTTP endpoint that accepts Sentry envelopes for forwarding. This can be used to force data through a custom server independent of the type of data.