Configure the Splunk RUM React Native agent

Configure Splunk RUM instrumentation for your React Native applications.

AgentConfiguration

You can configure the Splunk RUM React Native agent to add custom attributes, adapt the instrumentation to your environment and application, customize sampling, and more.

To configure the React Native RUM agent, pass the settings to the agent in an AgentConfiguration object. The following example shows how to configure this object with your Splunk RUM token, Splunk realm, application name, and deployment environment:

TYPESCRIPT 
await SplunkRum.install({
  endpoint: {
    realm: 'your-splunk-realm',
    rumAccessToken: 'your-splunk-rum-access-token',
  },
  appName: 'your-application-name',
  deploymentEnvironment: 'your-environment-name',
});

General settings

Use the following settings to configure the AgentConfiguration object:

Option Description
appName (required) Sets the application name.
appVersion Sets the application version.
deferredUntilForeground

Defer telemetry until the app is brought to the foreground. Default: false

Android only.
deploymentEnvironment (required) Environment for all the spans produced by the application. For example, dev, test, or prod.
enableDebugLogging Activates debug logging. Default: false
endpoint Sets the configuration needed to export data to an endpoint. There are two required inputs:
globalAttributes Attributes to append to every span collected. For an example, see Manage global attributes.
instrumentedProcessName

Compares application ID and process name. If they are the same, the application is visible to user. If not, it is the background process.

Android only.
session

Configured by SessionConfiguration for configuring sessions. It has following properties:

  • samplingRate Activates session ID based sampling and sets a sampling ratio. The sampling ratio is the probability of a session being included. Valid values: 0.0 (all dropped) to 1.0 (all included).
user

Configured by UserConfiguration for end user tracking. It has following properties:

  • trackingMode with a default of NO TRACKING.

Instrumentation module settings

You can configure the following modules in the Splunk RUM React Native agent:

Note: A module's settings only take effect if you activate that module (set its isEnabled attribute to true). All modules except navigation detection are activated by default.

HTTP instrumentation module (Android only)

The Splunk RUM React Native agent supports automatic instrumentation for the OkHttp and HttpURLConnection HTTP clients for Android.

Tip: See what attributes are included when this module is activated.
Okhttp3 (Android only)

This instrumentation automatically modifies the code at build time and adds the necessary hooks for tracing network requests made through the OkHttp3 APIs. To activate this, add the following plugin to android/build.gradle and android/app/build.gradle:

GROOVY 
// android/build.gradle
buildscript {
  repositories {
    google()
    mavenCentral()
  }
  dependencies {
    classpath("com.splunk:rum-okhttp3-auto-plugin:splunk-rum-version")
  }
}

Add these lines to android/app/build.gradle:

GROOVY 
// android/app/build.gradle
apply plugin: "com.splunk.rum-okhttp3-auto-plugin"

Enable the module in TypeScript and capture request and response headers:

You can opt-in to capture certain request and response headers using the HTTP instrumentation modules. If those headers are available, the resulting span will contain http.request.header.key and http.response.header.key attributes with the header value(s).

TYPESCRIPT 
import {
  HttpURLModuleConfiguration,
  OkHttp3AutoModuleConfiguration,
} from '@splunk/otel-react-native';

const modules = [
  new HttpURLModuleConfiguration(
    true,
    ['content-type', 'user-agent'],
    ['content-type', 'cache-control']
  ),
  new OkHttp3AutoModuleConfiguration(
    true,
    ['content-type', 'accept'],
    ['content-type', 'content-length']
  ),
];

await SplunkRum.install(agentConfiguration, modules);
Note: If you don't add the plugin to the application at build time, the runtime OkHttp3AutoModuleConfiguration will have no effect
HttpUrlConnection (Android only)

This instrumentation automatically modifies the code at build time and adds the necessary hooks for tracing network requests made via the URLConnection , HttpURLConnection, or HttpsURLConnection APIs. To enable this, add the following plugin to android/build.gradle and android/app/build.gradle.

GROOVY 
// android/build.gradle
buildscript {
  repositories {
    google()
    mavenCentral()
}
  dependencies {
    classpath("com.splunk:rum-httpurlconnection-auto-plugin:splunk-rum-version")
  }
}
GROOVY 
// android/app/build.gradle
apply plugin: "com.splunk.rum-httpurlconnection-auto-plugin"
Note: If you don't add the plugin to the application at build time, the runtime HttpUrlModuleConfiguration will have no effect.
Note: There is currently an open issue with Google that may result in a build failure when an application is built with these plugins. It's related to the Jetifier. The issue is tracked in the Google Issue Tracker and can be resolved by setting the enableJetifier flag to false in your gradle.properties file. For example, android.enableJetifier=false

If you see ByteBuddy resolution errors, enforce the ByteBuddy version:

TYPESCRIPT 
configurations.matching { it.name.toLowerCase().contains("bytebuddyclasspath") }.all {
  resolutionStrategy {
    force("net.bytebuddy:byte-buddy:1.14.12")
  }
}
Manual OkHttp instrumentation (Android only)

Not available in the alpha release.

Capture request and response headers (Android only)

You can opt-in to capture certain request and response headers using the HTTP instrumentation module. If those headers are available, the resulting span will contain http.request.header.key and http.response.header.key attributes with the header value(s).

Automatic URLSession instrumentation (iOS only)

Configure automatic instrumentation for URLSession clients to make HTTP network requests.

Specify patterns for NSRegularExpression to exclude requests from instrumentation as in the example below.

Tip: See what attributes are included when this module is activated.
SWIFT 
import { NetworkInstrumentationModuleConfiguration } from '@splunk/otel-react-native';

const modules = [
  new NetworkInstrumentationModuleConfiguration(true, [
    'https://example.com/health',
    '.*\\.png$',
  ]),
];

await SplunkRum.install(agentConfiguration, modules);

Automatic Navigation Instrumentation

Splunk Real User Monitoring can automatically detect route changes in supported React Native applications. The agent reports an app.ui.navigation event when the active route changes and adds screen.name to subsequent telemetry. This behavior helps you analyze application activity by framework route instead of the native host container.

The framework integration detects the active route and sends its name to the existing native navigation module. The native module creates the navigation signal and maintains the current screen name. You can use automatic tracking with manual navigation calls for custom flows.

Supported Frameworks and Libraries

React Native automatic navigation instrumentation supports:

  • React Navigation 6 and 7.
  • Expo Router through its React Navigation integration.

Other React Native navigation libraries are not supported.

The integration provides these behaviors:

  • They report the initial route by default.
  • They suppress repeated events when the active route has not changed.
  • They let you rename screens, exclude routes, and add custom attributes.
  • They update screen.name so subsequent spans, logs, crashes, and session-replay frames include the current screen.
  • They remove reserved navigation keys from custom attributes before sending data to the native agent.
Important: Keep native automatic navigation tracking disabled when you use framework route detection. Native tracking sees framework host containers and can produce duplicate events or replace the route name with a native implementation name.

Limitations

React Native automatic detection does not support Wix react-native-navigation.

Use manual navigation tracking for unsupported or custom flows.

Tip: See what attributes are included when this module is activated.

The agent provides two automatic navigation tracking methods:

  • Native-layer tracking detects Android Activity and Fragment transitions and iOS UIViewController transitions.

  • Framework-layer tracking detects routes managed by React Navigation. Add reactNavigationIntegration to enable this tracking.

Both methods report navigation events and update screen.name.

Note: Do not enable native automatic tracking when you use framework-layer tracking. Enabling both methods can produce duplicate events or report native container names instead of framework route names.

Automatic Navigation Tracking

Track native navigation automatically

Automatic detection of screen names is deactivated by default. You can activate it through the isAutomatedTrackingEnabled setting as shown in the examples below.

TYPESCRIPT 
import { NavigationModuleConfiguration } from '@splunk/otel-react-native';

const modules = [new NavigationModuleConfiguration(true, true)];

await SplunkRum.install(agentConfiguration, modules);
Note:
  • The isAutomatedTrackingEnabled setting controls native-layer navigation detection only. It monitors Android Activity and Fragment transitions and iOS UIViewController transitions. It does not detect routes managed by React Navigation. To track React Navigation routes, configure reactNavigationIntegration and keep native automatic navigation tracking disabled.
    Tracking method Native automatic tracking Framework integration
    Native-layer tracking Enabled Not configured
    React Native route tracking Disabled reactNavigationIntegration configured
  • To track navigation events manually, see Manually track navigation events

Track React Navigation Routes Automatically

Before you start, confirm these conditions:

  • Your application uses React Navigation 6 or 7, or Expo Router.
  • Your installed Splunk RUM React Native agent supports reactNavigationIntegration.
  • Native automatic navigation tracking is disabled.

To track React Navigation routes:

  1. Import reactNavigationIntegration from the agent's React Navigation subpath.
  2. Create the integration once, outside the application component.
  3. Create a navigation-container reference.
  4. Register the reference when the navigation container is ready.
TYPESCRIPT 
import {
  NavigationContainer,
  useNavigationContainerRef,
} from '@react-navigation/native';
import { reactNavigationIntegration } from
  '@splunk/otel-react-native/react-navigation';

const splunkNavigation = reactNavigationIntegration();

export default function App() {
  const navigationRef = useNavigationContainerRef();

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() =>
        splunkNavigation.registerNavigationContainer(navigationRef)
      }
    >
      <RootNavigator />
    </NavigationContainer>
  );
}

The integration tracks the active route in nested React Navigation stacks and tab navigators. Registering another navigation container replaces the current container.

Track Expo Router Routes Automatically

Register the Expo Router navigation-container reference in the root layout:

TYPESCRIPT 
import { useEffect } from 'react';
import { Stack, useNavigationContainerRef } from 'expo-router';
import { reactNavigationIntegration } from
  '@splunk/otel-react-native/react-navigation';

const splunkNavigation = reactNavigationIntegration();

export default function RootLayout() {
  const navigationRef = useNavigationContainerRef();

  useEffect(() => {
    splunkNavigation.registerNavigationContainer(navigationRef);

    return () => {
      splunkNavigation.unregisterNavigationContainer();
    };
  }, [navigationRef]);

  return <Stack />;
}

Customize React Native Screen Tracking

Configure the integration to rename screens, exclude routes, or derive event attributes:

TYPESCRIPT 
const splunkNavigation = reactNavigationIntegration({
  viewNamePredicate: route =>
    route.name === 'ProductDetails' ? 'Product' : route.name,
  shouldTrackView: route =>
    route.name !== 'DeveloperMenu',
  attributesFromRoute: route => {
    const productId = route.params?.productId;

    return productId == null
      ? undefined
      : { 'product.id': String(productId) };
  },
});

This table describes the React Native options:

Option Description Default
viewNamePredicate Changes the reported screen name. Return null, undefined, or an empty string to skip the screen. Route name
shouldTrackView Returns whether to track the route. true
attributesFromRoute Adds custom route attributes to the navigation event. No attributes
trackInitialRoute Reports the first route displayed by the application. true

Track Navigation Manually

If automatic tracking does not cover a navigation event, report the event manually. See Manually track navigation events.

Disable Automatic Framework Navigation Tracking

To disable React Native route tracking, call unregisterNavigationContainer() or remove the registration call. You can continue to report navigation manually.

Crash reporting module

Automatically captures crashes on the native platform. The crash reporting module is activated by default. To deactivate it, see the codeblock below.

Tip: See what attributes are included when this module is activated: Android, iOS.
TYPESCRIPT 
import { CrashReportsModuleConfiguration } from '@splunk/otel-react-native';

const modules = [new CrashReportsModuleConfiguration(false)];

await SplunkRum.install(agentConfiguration, modules);

Application not responding module (Android only)

Application not responding (ANR) occurs when an Android application's main thread is blocked for more than five seconds, preventing it from processing user input. The detection of ANRs is activated by default. To deactivate it, see the codeblock below.

Tip: See what attributes are included when this module is activated.
TYPESCRIPT 
import { AnrModuleConfiguration } from '@splunk/otel-react-native';

const modules = [new AnrModuleConfiguration(false)];

await SplunkRum.install(agentConfiguration, modules);

Slow rendering module

Monitors rendering performance at the native platform level. Activated by default. Configure as follows.

Tip: See what attributes are included when this module is activated: Android, iOS.
Android
TYPESCRIPT 
import { SlowRenderingModuleConfiguration } from '@splunk/otel-react-native';

const modules = [new SlowRenderingModuleConfiguration(true, 1000)];

await SplunkRum.install(agentConfiguration, modules);
iOS
TYPESCRIPT 
import { SlowRenderingModuleConfiguration } from '@splunk/otel-react-native';

const modules = [new SlowRenderingModuleConfiguration(true)];

await SplunkRum.install(agentConfiguration, modules);

Interaction detection module

Captures user interaction coordinates and timing at the native platform level. Interaction detection is enabled by default. To deactivate it, see the codeblock below.

Tip: See what attributes are included when this module is activated: Android, iOS.
TYPESCRIPT 
import { InteractionsModuleConfiguration } from '@splunk/otel-react-native';

const modules = [new InteractionsModuleConfiguration(false)];

await SplunkRum.install(agentConfiguration, modules);

Network monitoring module

The network monitoring module is included in the Splunk RUM React Native agent and is activated by default. This module monitors network connectivity and quality at the native platform level. To deactivate it, see the codeblock below.

TYPESCRIPT 
import { NetworkMonitorModuleConfiguration } from '@splunk/otel-react-native';

const modules = [new NetworkMonitorModuleConfiguration(false)];

await SplunkRum.install(agentConfiguration, modules);

Application lifecycle monitoring module

The application lifecycle monitoring module is included in the Splunk RUM React Native agent and is activated by default. This module monitors application lifecycle events (foreground, background, termination) at the native platform level. To deactivate it, see the codeblock below.

Tip: See what attributes are included when this module is activated: Android, iOS.
TYPESCRIPT 
import { ApplicationLifecycleModuleConfiguration } from '@splunk/otel-react-native';

const modules = [new ApplicationLifecycleModuleConfiguration(false)];

await SplunkRum.install(agentConfiguration, modules);