@sentry/react-native
Version:
Official Sentry SDK for react-native
522 lines (521 loc) • 21.2 kB
TypeScript
import type { makeFetchTransport } from '@sentry/browser';
import type { CaptureContext, ClientOptions, Event, EventHint, Options } from '@sentry/core';
import type { BrowserOptions, Profiler } from '@sentry/react';
import type * as React from 'react';
import type { TouchEventBoundaryProps } from './touchevents';
type ProfilerProps = React.ComponentProps<typeof Profiler>;
type BrowserTransportOptions = Parameters<typeof makeFetchTransport>[0];
type BrowserExperiments = NonNullable<BrowserOptions['_experiments']>;
type SharedExperimentsSubset = BrowserExperiments;
export interface BaseReactNativeOptions {
/**
* Enables native transport + device info + offline caching.
* Be careful, disabling this also breaks automatic release setting.
* This means you have to manage setting the release yourself.
* Defaults to `true`.
*/
enableNative?: boolean;
/**
* Enables native crashHandling. This only works if `enableNative` is `true`.
* Defaults to `true`.
*/
enableNativeCrashHandling?: boolean;
/**
* Initializes the native SDK on init.
* Set this to `false` if you have an existing native SDK and don't want to re-initialize.
*
* NOTE: Be careful and only use this if you know what you are doing.
* If you use this flag, make sure a native SDK is running before the JS Engine initializes or events might not be captured.
* Also, make sure the DSN on both the React Native side and the native side are the same one.
* We strongly recommend checking the documentation if you need to use this.
*
* @default true
*/
autoInitializeNativeSdk?: boolean;
/** Should the native nagger alert be shown or not. */
enableNativeNagger?: boolean;
/** Should sessions be tracked to Sentry Health or not. */
enableAutoSessionTracking?: boolean;
/** The interval to end a session if the App goes to the background. */
sessionTrackingIntervalMillis?: number;
/** Enable NDK on Android
*
* @default true
* @platform android
*/
enableNdk?: boolean;
/**
* When enabled, the SDK captures native crashes using Android's ApplicationExitInfo
* (REASON_CRASH_NATIVE) available on Android 12+. This provides more detailed crash
* information including thread details.
*
* @default false
* @platform android
*/
enableTombstone?: boolean;
/**
* When enabled, the SDK reports historical tombstones from Android's
* ApplicationExitInfo system API, as opposed to reporting only the tombstone
* of the latest application run. Historical events are reported without
* current scope data (e.g. breadcrumbs), as it's not possible to know
* the state of the app at the time they happened.
*
* Only has an effect if `enableTombstone` is `true`.
*
* @default false
* @platform android
*/
enableHistoricalTombstoneReporting?: boolean;
/** Enable scope sync from Java to NDK on Android
* Only has an effect if `enableNdk` is `true`.
*
* @platform android
*/
enableNdkScopeSync?: boolean;
/**
* When enabled, ANR events whose stacktraces contain only system frames
* (e.g. `java.lang`, `android.os`) are assigned a static fingerprint and
* grouped into a single issue instead of creating many separate issues.
*
* Enabled by default in the Android SDK since v8.35.0.
* Set to `false` to restore per-stacktrace ANR grouping.
*
* @default true
* @platform android
*/
enableAnrFingerprinting?: boolean;
/**
* When enabled, all the threads are automatically attached to all logged events on Android
*
* @platform android
*/
attachThreads?: boolean;
/**
* When enabled, full stack traces for all threads are attached to all captured events.
*
* @default false
* @platform ios
*/
attachAllThreads?: boolean;
/**
* When enabled, certain personally identifiable information (PII) is added by active integrations.
*
* @default false
*/
sendDefaultPii?: boolean;
/**
* Callback that is called after the RN SDK on the JS Layer has made contact with the Native Layer.
*/
onReady?: (response: {
/** `true` if the native SDK has been initialized, `false` otherwise. */
didCallNativeInit: boolean;
}) => void;
/** Enable auto performance tracking by default. Renamed from `enableAutoPerformanceTracking` in v5. */
enableAutoPerformanceTracing?: boolean;
/**
* Enables Out of Memory Tracking for iOS and macCatalyst.
* See the following link for more information and possible restrictions:
* https://docs.sentry.io/platforms/apple/guides/ios/configuration/out-of-memory/
*
* Renamed from `enableOutOfMemoryTracking` in v5.
*
* @default true
* @platform ios
*/
enableWatchdogTerminationTracking?: boolean;
/**
* Set data to the inital scope
* @deprecated Use `Sentry.getGlobalScope().setTag(...)`, `Sentry.getGlobalScope().setUser(...)`, etc. instead.
*/
initialScope?: CaptureContext;
/**
* When enabled, Sentry will overwrite the global Promise instance to ensure that unhandled rejections are correctly tracked.
* If you run into issues with Promise polyfills such as `core-js`, make sure you polyfill after Sentry is initialized.
* Read more at https://docs.sentry.io/platforms/react-native/troubleshooting/#unhandled-promise-rejections
*
* When disabled, this option will not disable unhandled rejection tracking. Set `onunhandledrejection: false` on the `ReactNativeErrorHandlers` integration instead.
*
* @default true
*/
patchGlobalPromise?: boolean;
/**
* The max cache items for capping the number of envelopes.
*
* @default 30
*/
maxCacheItems?: number;
/**
* When enabled, the SDK tracks when the application stops responding for a specific amount of
* time defined by the `appHangTimeoutInterval` option.
*
* iOS only
*
* @default true
* @platform ios
*/
enableAppHangTracking?: boolean;
/**
* The minimum amount of time an app should be unresponsive to be classified as an App Hanging.
* The actual amount may be a little longer.
* Avoid using values lower than 100ms, which may cause a lot of app hangs events being transmitted.
* Value should be in seconds.
*
* iOS only
*
* @default 2
* @platform ios
*/
appHangTimeoutInterval?: number;
/**
* The max queue size for capping the number of envelopes waiting to be sent by Transport.
*/
maxQueueSize?: number;
/**
* When enabled and a user experiences an error, Sentry provides the ability to take a screenshot and include it as an attachment.
*
* @default false
*/
attachScreenshot?: boolean;
/**
* Options for configuring screenshot masking on error screenshots.
* When `attachScreenshot` is enabled, these options control what gets masked in the screenshot.
*/
screenshot?: {
/**
* Mask all text content in error screenshots.
*
* @default true
*/
maskAllText?: boolean;
/**
* Mask all images in error screenshots.
*
* @default true
*/
maskAllImages?: boolean;
/**
* A list of native view class names to mask in error screenshots.
* Useful for masking views from third-party native libraries (e.g., map views, payment forms).
*
* @example ['com.example.MyCustomView'] // Android
* @example ['MKMapView'] // iOS
*/
maskedViewClasses?: string[];
/**
* A list of native view class names to exclude from masking in error screenshots.
*/
unmaskedViewClasses?: string[];
};
/**
* When enabled Sentry includes the current view hierarchy in the error attachments.
*
* @default false
*/
attachViewHierarchy?: boolean;
/**
* When enabled, Sentry will capture failed XHR/Fetch requests. This option also enabled HTTP Errors on iOS.
* [Sentry Android Gradle Plugin](https://docs.sentry.io/platforms/android/configuration/integrations/okhttp/)
* is needed to capture HTTP Errors on Android.
*
* @default false
*/
enableCaptureFailedRequests?: boolean;
/**
* 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/
*
* NOTE: Spotlight is automatically disabled in production builds (when __DEV__ is false).
* If you need Spotlight in non-development environments, you must manually add
* spotlightIntegration() to your integrations array. However, this is not recommended
* as Spotlight requires a local Sidecar server and is designed for development only.
*/
spotlight?: boolean | string;
/**
* Sets a callback which is executed before capturing screenshots. Only
* relevant if `attachScreenshot` is set to true. When false is returned
* from the function, no screenshot will be attached.
*/
beforeScreenshot?: (event: Event, hint: EventHint) => boolean;
/**
* Track the app start time by adding measurements to the first route transaction. If there is no routing instrumentation
* an app start transaction will be started.
*
* Requires performance monitoring to be enabled.
*
* @default true
*/
enableAppStartTracking?: boolean;
/**
* Track the slow and frozen frames in the application. Enabling this options will add
* slow and frozen frames measurements to all created root spans (transactions).
*
* @default true
*/
enableNativeFramesTracking?: boolean;
/**
* Track when and how long the JS event loop stalls for. Adds stalls as measurements to all transactions.
*
* @default true
*/
enableStallTracking?: boolean;
/**
* Install Sentry's native `TurboModulePerfLogger` and forward every Turbo
* Module lifecycle callback (`moduleCreate*`, sync/async method call
* start/end/fail, execution start/end/fail) to the higher-level Sentry
* instrumentation (crash attribution, per-module spans, aggregated stats).
*
* Only takes effect on React Native 0.75+ New Architecture. On Old Architecture
* this option is a no-op.
*
* The native perf logger is installed lazily on the first opt-in: while
* this flag is off (the default), Sentry never claims React Native's
* `NativeModulePerfLogger` slot and incurs no native-library mapping
* cost. The first `initNativeSdk` call with `enableTurboModuleTracking:
* true` loads the native library, installs the logger, and starts
* forwarding callbacks to the Sentry sink. Off by default because the
* higher-level features building on top of this hook ship in follow-up
* releases.
*
* @default false
* @experimental
*/
enableTurboModuleTracking?: boolean;
/**
* Trace User Interaction events like touch and gestures.
*
* @default false
*/
enableUserInteractionTracing?: boolean;
/**
* The sample rate for profiling
* 1.0 will profile all transactions and 0 will profile none.
*/
profilesSampleRate?: number;
/**
* The sample rate for session-long replays.
* 1.0 will record all sessions and 0 will record none.
*/
replaysSessionSampleRate?: number;
/**
* The sample rate for sessions that has had an error occur.
* This is independent of `sessionSampleRate`.
* 1.0 will record all sessions and 0 will record none.
*/
replaysOnErrorSampleRate?: number;
/**
* 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.
*/
shutdownTimeout?: number;
/**
* Defines the quality of the session replay. The higher the quality, the more accurate the replay
* will be, but also more data to transfer and more CPU load.
*
* @default 'medium'
*/
replaysSessionQuality?: SentryReplayQuality;
/**
* Options which are in beta, or otherwise not guaranteed to be stable.
*/
_experiments?: SharedExperimentsSubset & {
[key: string]: unknown;
/**
* @deprecated Use `replaysSessionSampleRate` in the options root instead.
*
* This will be removed in the next major version.
*/
replaysSessionSampleRate?: number;
/**
* @deprecated Use `replaysOnErrorSampleRate` in the options root instead.
*
* This will be removed in the next major version.
*/
replaysOnErrorSampleRate?: number;
/**
* Experiment: A more reliable way to report unhandled C++ exceptions in iOS.
*
* This approach hooks into all instances of the `__cxa_throw` function, which provides a more comprehensive and consistent exception handling across an app's runtime, regardless of the number of C++ modules or how they're linked. It helps in obtaining accurate stack traces.
*
* - Note: The mechanism of hooking into `__cxa_throw` could cause issues with symbolication on iOS due to caching of symbol references.
*
* @default false
* @platform ios
*/
enableUnhandledCPPExceptionsV2?: boolean;
/**
* Configuration options for UI profiling.
* It supports two modes: `manual` and `trace`.
* - In `trace` mode, the profiler runs based on active sampled spans.
* - In `manual` mode, profiling is controlled via start/stop API calls.
*
* @experimental
*/
profilingOptions?: ProfilingOptions;
/**
* Configuration options for Android UI profiling.
* It supports two modes: `manual` and `trace`.
* - In `trace` mode, the profiler runs based on active sampled spans.
* - In `manual` mode, profiling is controlled via start/stop API calls.
*
* @experimental
* @deprecated Use `profilingOptions` instead. This option will be removed in the next major version.
*/
androidProfilingOptions?: ProfilingOptions;
/**
* Sends app start as a dedicated standalone `app.start` transaction instead of
* attaching app start data to the first navigation (`ui.load`) transaction.
*
* This decouples app start data from the navigation transaction lifecycle, so it
* is no longer lost when no qualifying navigation transaction is sent. The standalone
* transaction uses op `app.start`, name `App Start`, and the span attributes
* `app.vitals.start.value` (duration) and `app.vitals.start.type` (`cold` / `warm`).
*
* Note: the standalone transaction still respects `tracesSampleRate`. A dedicated
* app start sample rate is not yet available.
*
* Requires `enableAppStartTracking` and performance monitoring to be enabled.
*
* @experimental
* @default false
*/
enableStandaloneAppStartTracing?: boolean;
};
/**
* This options changes the placement of the attached stacktrace of `captureMessage` in the event.
*
* @default false
* @deprecated This option will be removed in the next major version. Use `beforeSend` instead.
*/
useThreadsForMessageStack?: boolean;
/**
* 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 {@link 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.
*
* @see https://www.w3.org/TR/trace-context/
*
* @default false
*/
propagateTraceparent?: boolean;
/**
* Controls which log origin is captured when `enableLogs` is set to true.
* 'all' will log all origins.
* 'js' will capture only JavaScript logs.
* 'native' will capture only native logs.
*
* @default 'all'
*/
logsOrigin?: 'all' | 'js' | 'native';
/**
* When `enableLogs` is true, the SDK automatically captures `console.*` calls
* as logs via the `ConsoleLogs` integration. Set this to `false` to disable
* the automatic console capture while still being able to send logs manually
* via `Sentry.logger.*`.
*
* Has no effect when `enableLogs` is false or `logsOrigin` is `'native'`.
*
* @default true
*/
enableAutoConsoleLogs?: boolean;
/**
* A callback that is invoked when the native SDK emits a log message.
* This is useful for surfacing native SDK logs (e.g., transport errors like HTTP 413)
* in the JavaScript console.
*
* Only works when `debug: true` is set.
*
* @example
* ```typescript
* Sentry.init({
* debug: true,
* onNativeLog: ({ level, component, message }) => {
* console.log(`[Sentry Native] [${level}] [${component}] ${message}`);
* },
* });
* ```
*/
onNativeLog?: (log: NativeLogEntry) => void;
}
/**
* Represents a log entry from the native SDK.
*/
export interface NativeLogEntry {
level: string;
component: string;
message: string;
}
export type SentryReplayQuality = 'low' | 'medium' | 'high';
/**
* UI profiling lifecycle modes.
* - `trace`: Profiler runs based on active sampled spans
* - `manual`: Profiler is controlled manually via start/stop API calls
*/
export type ProfilingLifecycle = 'trace' | 'manual';
/**
* Configuration options for UI profiling.
*
* @experimental
*/
export interface ProfilingOptions {
/**
* Sample rate for profiling sessions.
* This is evaluated once per session and determines if profiling should be enabled for that session.
* 1.0 will enable profiling for all sessions, 0.0 will disable profiling.
*
* @default undefined (profiling disabled)
*/
profileSessionSampleRate?: number;
/**
* Profiling lifecycle mode.
* - `trace`: Profiler runs while there is at least one active sampled span
* - `manual`: Profiler is controlled manually via Sentry.profiler.startProfiler/stopProfiler
*
* @default 'manual'
*/
lifecycle?: ProfilingLifecycle;
/**
* Enable profiling on app start.
* - In `trace` mode: The app start profile stops automatically when the app start root span finishes
* - In `manual` mode: The app start profile must be stopped through Sentry.profiler.stopProfiler()
*
* @default false
*/
startOnAppStart?: boolean;
}
export interface ReactNativeTransportOptions extends BrowserTransportOptions {
/**
* @deprecated use `maxQueueSize` in the root of the SDK options.
*/
bufferSize?: number;
}
/**
* Configuration options for the Sentry ReactNative SDK.
* @see ReactNativeFrontend for more information.
*/
export interface ReactNativeOptions extends Omit<Options<ReactNativeTransportOptions>, '_experiments' | 'dataCollection'>, BaseReactNativeOptions {
}
export interface ReactNativeClientOptions extends Omit<ClientOptions<ReactNativeTransportOptions>, 'tunnel' | '_experiments' | 'dataCollection'>, BaseReactNativeOptions {
}
export interface ReactNativeWrapperOptions {
/** Props for the root React profiler */
profilerProps?: Omit<ProfilerProps, 'updateProps' | 'children' | 'name'>;
/** Props for the root touch event boundary */
touchEventBoundaryProps?: TouchEventBoundaryProps;
}
/**
* If the user has not explicitly set `enableNativeNagger`
* the function enables native nagging based on the current
* environment.
*/
export declare function shouldEnableNativeNagger(userOptions: unknown): boolean;
export {};
//# sourceMappingURL=options.d.ts.map