Splunk Distribution of OpenTelemetry for React Native

Overview

The Splunk Distribution of OpenTelemetry for React Native provides automatic instrumentation for React Native applications running on Android and iOS devices. This library captures telemetry data including:

• Application lifecycle events
• Network requests (fetch, XMLHttpRequest)
• User interactions
• App startup and performance metrics
• Crash reporting
• Slow rendering detection
• Navigation tracking

[!IMPORTANT] This library instruments React Native applications for Android and iOS devices. For React web instrumentation, see the splunk-otel-js-web project.

Requirements

• React Native >= 0.75.0
• React >= 18.2.0
• iOS >= 15.0 (with USE_FRAMEWORKS=dynamic in Podfile - required for SPM)
• Android minSdkVersion >= 24

Installation

For Expo Projects (with Development Builds)

This SDK supports Expo projects that use development builds (custom native code). It includes an Expo Config Plugin that automatically configures the native projects.

Note: This SDK does not work with Expo Go since it requires custom native code. You must use a development build.

1. Install the SDK:

npx expo install @splunk/otel-react-native

2. Add the plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": ["@splunk/otel-react-native"]
  }
}

3. (iOS only) Add USE_FRAMEWORKS=dynamic to your ios/Podfile:

# Required for SPM dependencies
ENV['USE_FRAMEWORKS'] = 'dynamic'

4. Run prebuild and build your development client:

npx expo prebuild
npx expo run:ios  # or npx expo run:android

Note: For iOS, USE_FRAMEWORKS=dynamic is required due to SPM dependencies. If you run expo prebuild without this, add it to the generated ios/Podfile and run cd ios && pod install && cd ..

For Bare React Native Projects

1. Install the SDK:

npm install @splunk/otel-react-native
# or
yarn add @splunk/otel-react-native

2. iOS Setup (REQUIRED):

Due to Swift Package Manager (SPM) dependencies, you must use dynamic frameworks. Add this to your ios/Podfile before pod install:

# Required for SPM dependencies
ENV['USE_FRAMEWORKS'] = 'dynamic'

Then install pods:

cd ios && pod install && cd ..

Note: USE_FRAMEWORKS=dynamic is required because this SDK uses SPM dependencies for the native iOS SDK, which is a limitation of SPM support in React Native. See React Native PR #44627 for more details.

3. Android Setup:

Enable core library desugaring in your android/app/build.gradle:

android {
  compileOptions {
    // Flag to enable support for the new language APIs
    // For AGP 4.1+
    isCoreLibraryDesugaringEnabled = true
    // For AGP 4.0
    // coreLibraryDesugaringEnabled = true
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
  kotlinOptions {
    // If this setting is present, jvmTarget must be "1.8"
    jvmTarget = "1.8"
  }
}
dependencies {
  // For AGP 8+
  coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.1.5"
  // For AGP 7.4+
  // coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.3")
  // For AGP 7.3
  // coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.2.3")
  // For AGP 4.0 to 7.2
  // coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.1.9")
}

Ensure minSdkVersion is 24 or higher.

The Maven repository is automatically configured. No additional setup required.

Quick Start

1. Wrap Your App with SplunkRumProvider

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

export default function App() {
  return (
    <SplunkRumProvider
      agentConfiguration={{
        appName: 'MyApp',
        deploymentEnvironment: 'production',
        endpoint: {
          rumAccessToken: 'YOUR_RUM_TOKEN',
          realm: 'us0',
        },
      }}
    >
      <YourAppContent />
    </SplunkRumProvider>
  );
}

2. (Optional) Use the Imperative API

You can also initialize the SDK imperatively:

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

await SplunkRum.install({
  appName: 'MyApp',
  deploymentEnvironment: 'production',
  endpoint: {
    rumAccessToken: 'YOUR_RUM_TOKEN',
    realm: 'us0',
  },
});

Configuration

Module Configuration

Control which features are enabled by passing module configurations:

import {
  CrashReportsModuleConfiguration,
  NetworkMonitorModuleConfiguration,
  InteractionsModuleConfiguration,
  SlowRenderingModuleConfiguration,
} from '@splunk/otel-react-native';

<SplunkRumProvider
  agentConfiguration={{
    appName: 'MyApp',
    deploymentEnvironment: 'production',
    endpoint: {
      rumAccessToken: 'YOUR_RUM_TOKEN',
      realm: 'us0',
    },
  }}
  modules={[
    new CrashReportsModuleConfiguration(true),  // Enable crash reporting
    new NetworkMonitorModuleConfiguration(false),  // Disable network monitoring
    new InteractionsModuleConfiguration(true),  // Enable user interactions
    new SlowRenderingModuleConfiguration(true, 1000),  // Enabled, check every 1s (Android)
  ]}
>
  <YourAppContent />
</SplunkRumProvider>;

Global Attributes

Add custom attributes to all telemetry:

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

// Set a single attribute
await SplunkRum.instance.globalAttributes.set('user.id', '12345');

// Set multiple attributes
await SplunkRum.instance.globalAttributes.set({
  'app.version': '1.2.3',
  'user.tier': 'premium',
});

User Tracking

Control user session tracking:

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

// Set tracking mode
await SplunkRum.instance.user.setTrackingMode('ANONYMOUS_TRACKING');

Custom Events

Track custom events:

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

// Track a simple event
await SplunkRum.instance.customTracking.trackCustomEvent('purchase_completed', {
  'product.id': 'abc123',
  'product.price': 99.99,
});

// Track a workflow with duration
const workflow = await SplunkRum.instance.customTracking.startWorkflow('checkout');
// ... perform checkout steps ...
await workflow.end();

WebView Integration

Instrument WebViews to capture web-based telemetry:

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

<SplunkWebView
  source={{ uri: 'https://example.com' }}
  style={{ flex: 1 }}
/>;

Testing

For unit tests, use the provided Jest mock:

// jest.config.js
module.exports = {
  moduleNameMapper: {
    '@splunk/otel-react-native':
      '<rootDir>/node_modules/@splunk/otel-react-native/jest/mock.js',
  },
};

Or import it directly:

jest.mock('@splunk/otel-react-native', () =>
  require('@splunk/otel-react-native/jest')
);

Troubleshooting

Common Issues

1. "Native module SplunkOtelReactNative is not linked"

   • Make sure you've run pod install (iOS) or rebuilt the app (Android)
   • For Expo, ensure you've run expo prebuild

2. iOS build errors: "Module 'SplunkOtel' not found" or SPM-related errors

   • Solution: Add ENV['USE_FRAMEWORKS'] = 'dynamic' to your ios/Podfile before running pod install
   • This is required for SPM dependencies to work with React Native
   • After adding, run: cd ios && pod install --repo-update && cd ..
   • Clean build if needed: cd ios && rm -rf build Pods && pod install && cd ..

3. Expo Go not supported

   • This SDK requires custom native code and doesn't work with Expo Go
   • Use a development build instead

4. Build errors on iOS

   • Ensure you're using iOS 15.0+ as minimum deployment target
   • Verify USE_FRAMEWORKS=dynamic is set in Podfile
   • Clean build folder: cd ios && rm -rf build && cd ..

Contributing

Contributions are welcome! See the Contributing Guide.

Support

• GitHub Issues
• Splunk Observability Documentation
• Community Forums

License

Copyright 2025 Splunk Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

ℹ️  SignalFx was acquired by Splunk in October 2019. See Splunk SignalFx for more information.