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.

Sign up for Honeycomb 

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.

Tip
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.

  1. 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;
    
    Tip
    To learn more about Metro configuration, visit Configuring Metro.
  2. 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
    
  3. 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.
Tip
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:

  1. Confirm that debug logging is enabled by setting logLevel: DiagLogLevel.DEBUG in your SDK configuration.

  2. Build and run your application.

  3. Open your debugger and check for logs with output like this:

    🐝 Honeycomb SDK Debug Mode Enabled 🐝
    Honeycomb options: HoneycombOptions(...)
    Not sampling, emitting all spans
    
  4. 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.

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.

Tip
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:

  1. Add use_frameworks! immediately below prepare_react_native_project! in your Podfile:

    prepare_react_native_project!
    use_frameworks!
    
  2. 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.