Sentry React Native

https://docs.sentry.io/platforms/react-native
Admin
Sentry React Native is an application monitoring SDK that provides real-time error tracking, crash...
Tokens:233,918
Snippets:1,977
Trust Score:9.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### setup(client)

Source: https://docs.sentry.io/platforms/react-native/guides/expo/integrations/custom

Documents the `setup` hook of a custom integration, which is called when the SDK is initialized.

```APIDOC
## setup(client)

### Description
The `setup` hook is called when the SDK is initialized. It receives the client instance as an argument. Use this to run code upon initialization.

### Parameters
- **client** (Client) - Required - The client instance being set up.

### Example
```javascript
const integration = {
  name: "MyAwesomeIntegration",
  setup(client) {
    setupCustomSentryListener(client);
  },
};
```
```

--------------------------------

### Android Setup: Initialize Sentry in MainApplication

Source: https://docs.sentry.io/platforms/react-native/guides/expo/manual-setup/app-start-error-capture

Initialize Sentry in the MainApplication class to capture app start crashes on Android. Call RNSentrySDK.init(this) in onCreate before the rest of your initialization code.

```kotlin
import io.sentry.react.RNSentrySDK

class MainApplication : Application(), ReactApplication {
    override fun onCreate() {
        super.onCreate()
        RNSentrySDK.init(this)
        // ... rest of your initialization code
    }
}
```

--------------------------------

### Use the setup hook in a custom integration

Source: https://docs.sentry.io/platforms/react-native/guides/expo/integrations/custom

Shows the setup hook, which is called when the SDK is initialized and receives the client instance. Use it to run code upon initialization, such as setting up a custom listener.

```javascript
const integration = {
  name: "MyAwesomeIntegration",
  setup(client) {
    setupCustomSentryListener(client);
  },
};
```

--------------------------------

### iOS Setup: Initialize Sentry in AppDelegate

Source: https://docs.sentry.io/platforms/react-native/guides/expo/manual-setup/app-start-error-capture

Initialize Sentry in the AppDelegate before starting React Native to capture app start crashes on iOS. Call [RNSentrySDK start] in didFinishLaunchingWithOptions.

```objective-c
#import <RNSentry/RNSentry.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [RNSentrySDK start];
    return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

@end
```

--------------------------------

### Manual Setup for Functional Components

Source: https://docs.sentry.io/platforms/react-native/guides/expo/tracing/instrumentation/time-to-display

Configure Sentry with reactNavigationIntegration and enableTimeToInitialDisplay. Register the navigation container in onReady to start TTID measurement.

```jsx
import * as Sentry from "@sentry/react-native";
import {
  NavigationContainer,
  createNavigationContainerRef,
} from "@react-navigation/native";

const navigationIntegration = Sentry.reactNavigationIntegration({
  enableTimeToInitialDisplay: true,
});

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  integrations: [navigationIntegration],
});

const App = () => {
  const containerRef = createNavigationContainerRef();

  return (
    <NavigationContainer
      ref={containerRef}
      onReady={() => {
        navigationIntegration.registerNavigationContainer(containerRef);
      }}
    ></NavigationContainer>
  );
};
```

--------------------------------

### Send count, gauge, and distribution metrics with Sentry.metrics

Source: https://docs.sentry.io/platforms/react-native/guides/expo/metrics

Shows how to send the three metric types (count, gauge, distribution) using Sentry.metrics.*. No setup beyond SDK initialization is required. The distribution example includes a unit option.

```javascript
import * as Sentry from "<sdk-package-name>";

// Count occurrences
Sentry.metrics.count("orders_created", 1);

// Track current values
Sentry.metrics.gauge("active_connections", 42);

// Track distributions
Sentry.metrics.distribution("api_latency", 187, {
  unit: "millisecond",
});
```

--------------------------------

### Wrap root component with Sentry.wrap

Source: https://docs.sentry.io/platforms/react-native/guides/expo/tracing

Wrap your root component with Sentry.wrap to get accurate App Start measurements and automatic instrumentation. Without it, App Start finishes when JavaScript initializes instead of when the first component mounts.

```javascript
export default Sentry.wrap(App);
```

--------------------------------

### Start or buffer replay recording

Source: https://docs.sentry.io/platforms/react-native/guides/expo/session-replay

Starts recording a full-session replay with start() or keeps the most recent segment in memory with startBuffering(). Explicit calls bypass configured replay sample rates. If a replay is already recording, both methods do nothing and log a debug message.

```javascript
// Start recording the whole session immediately.
Sentry.getReplay()?.start();

// Or start in buffer mode instead.
Sentry.getReplay()?.startBuffering();
```

--------------------------------

### Enable standalone app start tracing with _experiments.enableStandaloneAppStartTracing

Source: https://docs.sentry.io/platforms/react-native/guides/expo/tracing/instrumentation/automatic-instrumentation

Configure Sentry.init to enable the experimental standalone app start tracing feature. This sends a dedicated 'app.start' transaction instead of attaching app start data to navigation transactions. Requires SDK version 8.17.2 or later and is not available on web.

```javascript
import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  _experiments: {
    enableStandaloneAppStartTracing: true,
  },
});
```

--------------------------------

### Install @sentry/react-native

Source: https://docs.sentry.io/platforms/react-native/guides/expo/migration/sentry-expo

Installs the @sentry/react-native package using the Expo CLI.

```bash
npx expo install @sentry/react-native
```

--------------------------------

### replay.start()

Source: https://docs.sentry.io/platforms/react-native/guides/expo/session-replay

Starts a full-session replay. Bypasses configured replay sample rates. If a replay is already recording, does nothing.

```APIDOC
## replay.start()

### Description
Starts a full-session replay. Bypasses configured replay sample rates. If a replay is already recording, does nothing (a debug message is logged).

### Method
`start()`

### Example
```javascript
Sentry.getReplay()?.start();
```
```

--------------------------------

### Create and add a custom integration with Sentry.init

Source: https://docs.sentry.io/platforms/react-native/guides/expo/integrations/custom

Defines a custom integration function that returns an object with a name and an optional setup hook, then adds it to the SDK via Sentry.init's integrations array. The setup hook receives the client instance when the SDK is initialized.

```javascript
function myAwesomeIntegration() {
  return {
    name: "MyAwesomeIntegration",
    setup(client) {
      // Do something when the SDK is initialized
      // The client that is being setup is passed to the hook
    },
  };
}

Sentry.init({
  // ...
  integrations: [myAwesomeIntegration()],
});
```

--------------------------------

### Example of captured component names

Source: https://docs.sentry.io/platforms/react-native/guides/expo/integrations/component-names

Shows the component names with file references that appear after enabling component name capturing.

```html
MyCard (View, MyCard.ts) > MyButton (Touchable, MyCard.ts) > View > Text
```

--------------------------------

### Extend App Start with Sentry.extendAppStart()

Source: https://docs.sentry.io/platforms/react-native/guides/expo/tracing/instrumentation/automatic-instrumentation

Extends the app start transaction by calling Sentry.extendAppStart() right after Sentry.init() and before the root component mounts. Requires enableStandaloneAppStartTracing: true. Use getExtendedAppStartSpan() to create child spans and finishExtendedAppStart() when the app is ready.

```javascript
import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  _experiments: {
    enableStandaloneAppStartTracing: true,
  },
});

// Call extendAppStart() synchronously, right after init.
Sentry.extendAppStart();

// Metro doesn't support top-level await, so run the async launch work in a function.
async function prepareApp() {
  // Break the extended launch period down into child spans:
  const parentSpan = Sentry.getExtendedAppStartSpan();

  const configSpan = Sentry.startInactiveSpan({
    parentSpan,
    op: "app.init",
    name: "fetch remote config",
  });
  await fetchRemoteConfig();
  configSpan.end();

  // When your app is fully ready:
  await Sentry.finishExtendedAppStart();
}

prepareApp();
```

--------------------------------

### Set dedicated sample rate for standalone App Start transactions with tracesSampler

Source: https://docs.sentry.io/platforms/react-native/guides/expo/tracing/instrumentation/automatic-instrumentation

Configure Sentry.init with a custom tracesSampler that returns 1.0 for transactions named 'App Start' and 0.1 for all others. This allows sampling app starts independently without changing the overall sample rate.

```javascript
import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  _experiments: {
    enableStandaloneAppStartTracing: true,
  },
  tracesSampler: (samplingContext) => {
    if (samplingContext.name === "App Start") {
      return 1.0;
    }
    return 0.1;
  },
});
```

--------------------------------

### Example of generic element names

Source: https://docs.sentry.io/platforms/react-native/guides/expo/integrations/component-names

Shows the generic element names that appear without component name capturing.

```bash
View > Touchable > View > Text
```

--------------------------------

### replay.resume()

Source: https://docs.sentry.io/platforms/react-native/guides/expo/session-replay

Resumes recording after a pause. If replay is stopped, does nothing; call start() or startBuffering() to create a new replay.

```APIDOC
## replay.resume()

### Description
Resumes recording after a pause. If replay is stopped, does nothing; call `start()` or `startBuffering()` to create a new replay. Supported on iOS and Android only; on React Native Web it is a no-op (a debug message is logged).

### Method
`resume()`

### Example
```javascript
Sentry.getReplay()?.resume();
```
```

--------------------------------

### setupOnce()

Source: https://docs.sentry.io/platforms/react-native/guides/expo/integrations/custom

Documents the `setupOnce` hook, which runs only once even if the SDK is re-initialized.

```APIDOC
## setupOnce()

### Description
The `setupOnce` hook is similar to `setup`, but it's only run once, even if the SDK is re-initialized. It receives no arguments. Use it only when you need to ensure code runs only once across multiple `Sentry.init()` calls.

### Parameters
None.

### Example
```javascript
const integration = {
  name: "MyAwesomeIntegration",
  setupOnce() {
    wrapLibrary();
  },
};
```
```

--------------------------------

### Get replay ID

Source: https://docs.sentry.io/platforms/react-native/guides/expo/session-replay

Gets the ID of the active replay, for example to link it with support tooling. Returns the current replay ID or a nullish value if no replay is active.

```javascript
const replayId = Sentry.getReplay()?.getReplayId();
```

--------------------------------

### Get the Root Span with Sentry.getRootSpan

Source: https://docs.sentry.io/platforms/react-native/guides/expo/tracing/instrumentation/custom-instrumentation

Returns the root span of a given span. If the span is already the root span, it returns the span itself. The example uses getActiveSpan to obtain the span and then gets its root.

```javascript
const activeSpan = Sentry.getActiveSpan();
const rootSpan = activeSpan ? Sentry.getRootSpan(activeSpan) : undefined;
```

--------------------------------

### afterAllSetup(client)

Source: https://docs.sentry.io/platforms/react-native/guides/expo/integrations/custom

Documents the `afterAllSetup` hook, which runs after all integrations have been set up.

```APIDOC
## afterAllSetup(client)

### Description
The `afterAllSetup` hook is triggered after `setupOnce()` and `setup()` have been called for all integrations. It receives the client that is being set up. Use it to ensure all other integrations have run their setup hooks.

### Parameters
- **client** (Client) - Required - The client that is being set up.

### Example
```javascript
const integration = {
  name: "MyAwesomeIntegration",
  afterAllSetup(client) {
    startSomeThing(client);
  },
};
```
```

--------------------------------

### Run after all integrations with the afterAllSetup hook

Source: https://docs.sentry.io/platforms/react-native/guides/expo/integrations/custom

Shows the afterAllSetup hook, which is triggered after setupOnce() and setup() have been called for all integrations. It receives the client as the first argument and is useful when you need to ensure all other integrations have run.

```javascript
const integration = {
  name: "MyAwesomeIntegration",
  afterAllSetup(client) {
    // We can be sure that all other integrations
    // have run their `setup` and `setupOnce` hooks now
    startSomeThing(client);
  },
};
```

--------------------------------

### Run code once with the setupOnce hook

Source: https://docs.sentry.io/platforms/react-native/guides/expo/integrations/custom

Shows the setupOnce hook, which runs only once even if the SDK is re-initialized. It receives no arguments. Use it only when calling Sentry.init() multiple times and needing code to run once; otherwise prefer setup.

```javascript
const integration = {
  name: "MyAwesomeIntegration",
  setupOnce() {
    wrapLibrary();
  },
};
```

--------------------------------

### Redux Enhancer Setup with configureStore and createStore

Source: https://docs.sentry.io/platforms/react-native/integrations/redux

Use Sentry.createReduxEnhancer to add Sentry to your Redux store. The example shows both the configureStore and createStore APIs. Pass the enhancer directly to the store, not to applyMiddleware.

```javascript
import { configureStore, createStore, compose } from "redux";
import * as Sentry from "@sentry/react-native";

// ...

const sentryReduxEnhancer = Sentry.createReduxEnhancer({
  // Optionally pass options listed below
});

// If you are using the `configureStore` API, pass the enhancer as follows:
const store = configureStore({
  reducer,
  enhancers: (getDefaultEnhancers) => {
    return getDefaultEnhancers().concat(sentryReduxEnhancer);
  },
});

// If you are using the deprecated `createStore` API, pass the enhancer as follows:
const store = createStore(reducer, sentryReduxEnhancer);
```

--------------------------------

### Enable Spotlight with spotlight: true in Sentry.init()

Source: https://docs.sentry.io/platforms/react-native/guides/expo/integrations/spotlight

Recommended setup that adds the integration only in development (`__DEV__` mode). Connects to the default Spotlight Sidecar at `http://localhost:8969/stream`.

```javascript
import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  spotlight: true,
});
```

--------------------------------

### Start Active Spans with Sentry.startSpan()

Source: https://docs.sentry.io/platforms/react-native/guides/expo/tracing/instrumentation/custom-instrumentation

Use Sentry.startSpan() to create an active span that automatically ends when the callback completes. The callback can be synchronous or asynchronous; for async callbacks, the span ends when the promise resolves or rejects, and errors mark the span as failed. The third example shows nesting spans, where the child span is created inside the parent's callback.

```javascript
const result = Sentry.startSpan({ name: "Important Function" }, () => {
  return expensiveFunction();
});
```

```javascript
const result = await Sentry.startSpan(
  { name: "Important Function" },
  async () => {
    const res = await doSomethingAsync();
    return updateRes(res);
  },
);
```

```javascript
const result = await Sentry.startSpan(
  {
    name: "Important Function",
  },
  async () => {
    const res = await Sentry.startSpan({ name: "Child Span" }, () => {
      return expensiveAsyncFunction();
    });

    return updateRes(res);
  },
);
```

--------------------------------

### Initialize Sentry with networkDetailAllowUrls

Source: https://docs.sentry.io/platforms/react-native/guides/expo/session-replay

Initialize Sentry with mobile replay and network detail capture for URLs matching https://api.example.com. Sets both session and error replay sample rates to 1.0.

```javascript
import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  replaysSessionSampleRate: 1.0,
  replaysOnErrorSampleRate: 1.0,
  integrations: [
    Sentry.mobileReplayIntegration({
      networkDetailAllowUrls: ["https://api.example.com"],
    }),
  ],
});
```

--------------------------------

### Replace beforeNavigate with beforeStartSpan

Source: https://docs.sentry.io/platforms/react-native/guides/expo/migration/v5-to-v6

Migrate from the removed `beforeNavigate` option to `beforeStartSpan` in version 6. The `beforeStartSpan` function is called before starting a navigation span and can modify the span start options, but cannot stop the span from being started.

```javascript
Sentry.init({
  tracesSampleRate: 1.0,
  integrations: [
-    new Sentry.ReactNativeTracing({
-      beforeNavigate: (context) => {
+    Sentry.reactNativeTracingIntegration({
+      beforeStartSpan: (options) => {
         return {
           ...options,
            op: 'navigation',
         };
       },
    }),
  ],
});
```

--------------------------------

### Install @sentry/react-native

Source: https://docs.sentry.io/platforms/react-native/guides/expo/manual-setup/manual-setup

Installs the @sentry/react-native package. Other package managers (yarn, pnpm) are available as variations.

```bash
npm install @sentry/react-native --save
```

--------------------------------

### Sentry.init

Source: https://docs.sentry.io/platforms/react-native/configuration/touchevents

Shows how to configure the Sentry SDK to allow sentry-label and text extraction when Session Replay masking is active.

```APIDOC
## [Sentry.init] Configure Touch Events with Session Replay Masking

### Description
Configure the Sentry SDK to enable `sentry-label` and text extraction alongside Session Replay by disabling `maskAllText`.

### Method
`Sentry.init`

### Parameters
#### Configuration Object
- **integrations** (Array) - Required - List of integrations. Must include `Sentry.mobileReplayIntegration`.

### Request Example
```javascript
Sentry.init({
  integrations: [Sentry.mobileReplayIntegration({ maskAllText: false })],
});
```
```

--------------------------------

### Span Starting Options

Source: https://docs.sentry.io/platforms/react-native/guides/expo/tracing/instrumentation/custom-instrumentation

Options that can be used for all span starting functions in the Sentry React Native SDK.

```APIDOC
## Span Starting Options

### Description
Options that can be used for all span starting functions in the Sentry React Native SDK.

### Options

| Option | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | The name of the span. |
| `op` | `string` | No | The operation of the span. |
| `startTime` | `number` | No | The start time of the span. |
| `attributes` | `Record<string, Primitive>` | No | Attributes to attach to the span. |
| `parentSpan` | `Span` | No | If set, makes the span a child of the specified span. Otherwise, the span will be a child of the currently active span. |
| `onlyIfParent` | `boolean` | No | If true, ignores the span if there's no active parent span. |
| `forceTransaction` | `boolean` | No | If true, ensures this span shows up as a transaction in the Sentry UI. |

### Notes
- The only required option is `name`. All other options are optional.
```

--------------------------------

### Manual Setup for Class Components

Source: https://docs.sentry.io/platforms/react-native/guides/expo/tracing/instrumentation/time-to-display

Configure Sentry with reactNavigationIntegration and enableTimeToInitialDisplay. Register the navigation container in onReady using a class component's ref.

```jsx
import * as Sentry from "@sentry/react-native";
import { NavigationContainer } from "@react-navigation/native";

const navigationIntegration = Sentry.reactNavigationIntegration({
  enableTimeToInitialDisplay: true,
});

Sentry.init({
  dsn: "https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
  integrations: [navigationIntegration],
});

class App extends React.Component {
  containerRef = createNavigationContainerRef();

  render() {
    return (
      <NavigationContainer
        ref={this.containerRef}
        onReady={() => {
          navigationIntegration.registerNavigationContainer(
            this.containerRef,
          );
        }}
      ></NavigationContainer>
    );
  }
}
```

--------------------------------

### Install Sentry Fastlane Plugin

Source: https://docs.sentry.io/platforms/react-native/build-distribution

Installs the Sentry Fastlane plugin (version 2.8.0) required for uploading iOS builds to Sentry.

```ruby
bundle exec fastlane add_plugin fastlane-plugin-sentry
```

--------------------------------

### Add span attributes when starting a span

Source: https://docs.sentry.io/platforms/react-native/guides/expo/tracing/instrumentation/custom-instrumentation

Specify attributes when starting a span. Attributes can be of type string, number, boolean, or non-mixed arrays of these types.

```javascript
Sentry.startSpan(
  {
    attributes: {
      attr1: "value1",
      attr2: 42,
      attr3: true,
    },
  },
  () => {
    // Do something
  },
);
```

--------------------------------

### NativeLinkedErrors usage example

Source: https://docs.sentry.io/platforms/react-native/guides/expo/integrations/default

Example of using the NativeLinkedErrors integration: capture an error with a cause property to link the original error. The integration reads linked errors up to the configured limit.

```javascript
async function fetchReviews(movieTitle) {
  try {
    await fetchMovieReviews(movieTitle);
  } catch (e) {
    const fetchError = new Error(
      `Failed to fetch reviews for: ${movieTitle}`,
    );
    fetchError.cause = e;
    Sentry.captureException(fetchError);
  }
}
```
Tokens:
Raw