Get Started with Honeycomb for React Native

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 begin

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:

Get an API key

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.

When deploying to production, replace this key with a separate key that does not allow dataset creation. This helps protect your data structure in live environments.

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.

Install the SDK

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;

To learn more about Metro configuration, visit Configuring Metro.

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

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: endpoint : URL where your telemetry is sent. Defaults to https://api.honeycomb.io:443 (the Honeycomb US instance URL). For EU instances, set this to https://api.eu1.honeycomb.io:443. If you’re using an OpenTelemetry Collector, use your collector’s URL instead. apiKey : Your Ingest API Key, which authorizes your application to send telemetry directly to Honeycomb. serviceName : Name of your application, which Honeycomb will use as your dataset name. Choose something meaningful and consistent.

If you don’t provide a service name, the dataset name will be inferred from your bundle.

logLevel : Verbosity of logs printed to the console. Enabling debug logs is helpful during development. 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)
}

Enable automatic instrumentation

The Honeycomb OpenTelemetry React Native SDK includes auto-instrumentation libraries for:

Application startup time, measured from when the native SDKs start to when the JavaScript SDK finishes initializing.
Errors or uncaught exceptions.
Fetch instrumentation, using the opentelemetry-instrumentation-fetch package.
Slow event loop detection.

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();

Verify data is being sent

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

If you don’t see any data, visit Troubleshooting.

Explore your data

Take a look at the data that you have generated using automatic instrumentation through the React Native Launchpad or a custom Board.

Explore with the React Native Launchpad

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:

Find slow event loops
Detect performance slow downs and crashes
Monitor how users interact with your application

It’s a great place to start exploring how your application behaves in real-world conditions.

Explore using Boards

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.

Troubleshooting

Running into issues? Here are some common problems and ways to fix them.

Still stuck? Check out our Support Knowledge Base or post a question in our Pollinators Community.

Dataset isn’t showing up in Honeycomb

Make sure that you:

Replaced "YOUR-API-KEY" with a valid Ingest API Key.
Gave the key Can create datasets permission.

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.

Dataset name looks wrong

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.

File not found error on iOS

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

Not receiving native telemetry data

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.

Start Building

Observability Fundamentals

Honeycomb Basics

Plan + Design

Get Started with Honeycomb for React Native

Before you begin

Get an API key

Install the SDK

Initialize

Enable automatic instrumentation

Verify data is being sent

Explore your data

Explore with the React Native Launchpad

Explore using Boards

Troubleshooting

Dataset isn’t showing up in Honeycomb

Dataset name looks wrong

File not found error on iOS

Not receiving native telemetry data

​Before you begin

​Sign up for Honeycomb

​Get an API key

​Install the SDK

​Initialize

​Enable automatic instrumentation

​Verify data is being sent

​Explore your data

​Explore with the React Native Launchpad

​Explore using Boards

​Troubleshooting

​Dataset isn’t showing up in Honeycomb

​Dataset name looks wrong

​File not found error on iOS

​Not receiving native telemetry data

Before you begin

Sign up for Honeycomb

Get an API key

Install the SDK

Initialize

Enable automatic instrumentation

Verify data is being sent

Explore your data

Explore with the React Native Launchpad

Explore using Boards

Troubleshooting

Dataset isn’t showing up in Honeycomb

Dataset name looks wrong

File not found error on iOS

Not receiving native telemetry data