Learn how to collect telemetry from your React Native application and send it to Honeycomb using the Honeycomb OpenTelemetry React Native SDK.
Instrumenting your application lets you measure how it behaves on actual devices, detect performance issues, and better understand how users experience your application.
Before you run the code, you’ll need to do a few things.
If you don’t already have a Honeycomb account, you can sign up for one. Signup is free.
Honeycomb stores your data in either a US-based or EU-based location, depending on your account region:
For this guide, you’ll need a Honeycomb Ingest API Key with the Can create services/datasets permission. This lets your application send telemetry to Honeycomb and create a dataset for your service.
Make note of your API key; for security reasons, you will not be able to see the key again, and you will need it later.
Before you can use Honeycomb’s OpenTelemetry React Native SDK, you need to install it and configure platform-specific dependencies.
Configure Metro to recognize package.json
exports. To do this, create a new file, metro.config.js
, in your application’s root directory.
Enable package.json
exports in your Metro configuration.
config.resolver.unstable_enablePackageExports = true;
Here’s an example Metro configuration:
const path = require('path');
const { getDefaultConfig } = require('@react-native/metro-config');
const { getConfig } = require('react-native-builder-bob/metro-config');
const pkg = require('../package.json');
const root = path.resolve(__dirname, '..');
const config = getConfig(getDefaultConfig(__dirname), {
root,
pkg,
project: __dirname,
});
// Required to use @opentelemetry package.json "exports" field
config.resolver.unstable_enablePackageExports = true;
module.exports = config;
Install Honeycomb’s OpenTelemetry React Native SDK in your application’s root directory using your preferred package manager.
Install with yarn
:
yarn add @honeycombio/opentelemetry-react-native
Install with npm
:
npm install @honeycombio/opentelemetry-react-native
Install the necessary dependencies for each mobile platform your application supports.
Android dependencies:
Add the following dependencies to your application’s build.gradle
.
dependencies {
//...
implementation "io.honeycomb.android:honeycomb-opentelemetry-android:0.0.16"
implementation "io.opentelemetry.android:android-agent:0.11.0-alpha"
}
If your application’s minSDK
version is lower than 26, add core library desugaring to your android/app/build.gradle
.
android {
compileOptions {
// Enable support for the new language APIs
coreLibraryDesugaringEnabled true
}
dependencies {
coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.1.5"
}
}
iOS dependencies:
Add the use_frameworks!
option to your application’s Podfile
.
platform :ios, min_ios_version_supported
prepare_react_native_project!
use_frameworks!
From the ios
directory, run pod install
to install the required dependencies.
Initialize the SDK at the start of your React Native application. This ensures that events such as startup time and early view loads are captured.
import { HoneycombReactNativeSDK } from '@honeycombio/opentelemetry-react-native';
import { DiagLogLevel } from '@opentelemetry/api';
const sdk = new HoneycombReactNativeSDK({
// Uncomment the line below to send to EU instance. Defaults to US.
// endpoint: "https://api.eu1.honeycomb.io:443",
apiKey: "YOUR-API-KEY",
serviceName: "YOUR-SERVICE-NAME",
logLevel: DiagLogLevel.DEBUG,
});
sdk.start();
In the above example, key configuration options include:
https://api.honeycomb.io:443
(the Honeycomb US instance URL).https://api.eu1.honeycomb.io:443
.Can be set to either .NONE
, .ERROR
, .WARN
, .INFO
, .DEBUG
, or .ALL
. For more information, visit Enumeration DiagLogLevel.
For Android, initialize the SDK at the start of the onCreate()
method in your main Application
class.
// MainApplication.kt
override fun onCreate() {
val options = HoneycombOpentelemetryReactNativeModule.optionsBuilder(this)
// Uncomment the line below to send to EU instance. Defaults to US.
// .setApiEndpoint("https://api.eu1.honeycomb.io:443")
.setApiKey("YOUR-API-KEY")
.setServiceName("YOUR-SERVICE-NAME")
HoneycombOpentelemetryReactNativeModule.configure(this, options)
super.onCreate()
}
For iOS, initialize the SDK at the start of the application()
method in your AppDelegate
class.
// AppDelegate.swift
override func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
let options = HoneycombReactNative.optionsBuilder()
// Uncomment the line below to send to EU instance. Defaults to US.
// .setAPIEndpoint("https://api.eu1.honeycomb.io:443")
.setAPIKey("YOUR-API-KEY")
.setServiceName("YOUR-SERVICE-NAME")
HoneycombReactNative.configure(options)
}
The Honeycomb OpenTelemetry React Native SDK includes auto-instrumentation libraries for:
Automatic instrumentation is enabled by default. You can enable or disable individual auto-instrumentation libraries in your configuration.
import { HoneycombReactNativeSDK } from '@honeycombio/opentelemetry-react-native';
import { DiagLogLevel } from '@opentelemetry/api';
const sdk = new HoneycombReactNativeSDK({
// Uncomment the line below to send to EU instance. Defaults to US.
// endpoint: "https://api.eu1.honeycomb.io:443",
apiKey: "YOUR-API-KEY",
serviceName: "YOUR-SERVICE-NAME",
logLevel: DiagLogLevel.DEBUG,
// auto-instrumentation options
reactNativeStartupInstrumentationConfig: {
enabled: true,
},
uncaughtExceptionInstrumentationConfig: {
enabled: true,
},
fetchInstrumentationConfig: {
enabled: true,
},
slowEventLoopInstrumentationConfig: {
enabled: true,
},
});
sdk.start();
Once your application is instrumented, check that telemetry data is reaching Honeycomb:
Confirm that debug logging is enabled by setting logLevel: DiagLogLevel.DEBUG
in your SDK configuration.
Build and run your application.
Open your debugger and check for logs with output like this:
🐝 Honeycomb SDK Debug Mode Enabled 🐝
Honeycomb options: HoneycombOptions(...)
Not sampling, emitting all spans
Log in to Honeycomb, and open your environment.
You should see a new dataset named after your serviceName
value.
If you don’t see any data, visit Troubleshooting.
Take a look at the data that you have generated using automatic instrumentation through the React Native Launchpad or a custom Board.
If you’re using Honeycomb for Frontend Observability, the React Native Launchpad provides a starting point for monitoring and analyzing telemetry from your React Native application. The Launchpad helps you:
It’s a great place to start exploring how your application behaves in real-world conditions.
You can also explore your data by creating a Board from a pre-configured Board template. Our specialized template for React Native telemetry includes a curated set of ready-made queries and visualizations based on the fields collected by the Honeycomb OpenTelemetry React Native SDK.
This template gives you an immediate, actionable view into common mobile metrics like application start times, crashes, and session flows, without needing to build anything from scratch. You can use it as-is or customize it to fit your needs.
To learn more, visit Use Board Templates.
Running into issues? Here are some common problems and ways to fix them.
Make sure that you:
"YOUR-API-KEY"
with a valid Ingest API Key.The Honeycomb OpenTelemetry React Native SDK uses the value passed to apiKey
configuration option to send your telemetry data.
This must be set correctly for data to reach Honeycomb.
Check the value passed to serviceName
during initialization.
This value determines the name of your dataset in Honeycomb.
If you leave it blank, the default will be inferred from your bundle, which might not be descriptive or consistent across builds.
If you see an error like this when running your application on iOS:
'HoneycombOpentelemetryReactNative/HoneycombOpentelemetryReactNative-Swift.h' file not found when trying to run for iOS
It usually means your application’s Podfile
is missing the use_frameworks!
line.
To resolve this error:
Add use_frameworks!
immediately below prepare_react_native_project!
in your Podfile
:
prepare_react_native_project!
use_frameworks!
Install the iOS dependencies by navigating to your ios
directory and running pod install
:
cd ios
pod install
Unlike JavaScript code, native code does not hot reload on changes. So if you updated your AppDelegate.swift
or MainApplication.kt
files and are still not getting native telemetry, you’ll need to rebuild your application.
Stop metro, the simulator, and restart the build. If this still doesn’t work, try uninstalling the application and reinstalling it.