> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Started with Honeycomb for React Native
> Instrument your React Native application with the Honeycomb OpenTelemetry React Native SDK, send telemetry to Honeycomb, and measure real device performance in production.
Learn how to collect telemetry from your React Native application and send it to Honeycomb using the [Honeycomb OpenTelemetry React Native SDK](https://github.com/honeycombio/honeycomb-opentelemetry-react-native).
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:
* [Create a US account](https://ui.honeycomb.io/signup)
* [Create an EU account](https://ui.eu1.honeycomb.io/signup)
### Get an API key
For this guide, you'll need a [Honeycomb Ingest API Key](/configure/environments/manage-api-keys/#create-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.
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](https://reactnative.dev/blog/2023/06/21/package-exports-support) in your Metro configuration.
```js theme={}
config.resolver.unstable_enablePackageExports = true;
```
Here's an [example Metro configuration](https://github.com/honeycombio/honeycomb-opentelemetry-react-native/blob/main/example/metro.config.js):
```js theme={}
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](https://metrobundler.dev/docs/configuration/).
2. Install Honeycomb’s OpenTelemetry React Native SDK in your application’s root directory using your preferred package manager.
**Install with `yarn`:**
```bash theme={}
yarn add @honeycombio/opentelemetry-react-native
```
**Install with `npm`:**
```bash theme={}
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`.
```gradle theme={}
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](https://developer.android.com/studio/write/java8-support#library-desugaring) to your `android/app/build.gradle`.
```gradle theme={}
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`.
```podfile theme={}
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.
```ts theme={}
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](/configure/environments/manage-api-keys/#create-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](https://open-telemetry.github.io/opentelemetry-js/enums/_opentelemetry_api._opentelemetry_api.DiagLogLevel.html).
For Android, initialize the SDK at the start of the `onCreate()` method in your main `Application` class.
```kotlin theme={}
// 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.
```swift theme={}
// 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](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) instrumentation, using the [opentelemetry-instrumentation-fetch](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/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.
```ts theme={}
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:
```text theme={}
🐝 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](#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](https://www.honeycomb.io/frontend-observability/), the [React Native Launchpad](/observe/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](/observe/boards/) from a [pre-configured Board template](/observe/boards/templates/).
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](/observe/boards/templates/).
## Troubleshooting
Running into issues? Here are some common problems and ways to fix them.
Still stuck?
Check out our [Support Knowledge Base](/troubleshoot/customer-support/) or post a question in our [Pollinators Community](/troubleshoot/community/).
### Dataset isn't showing up in Honeycomb
Make sure that you:
* Replaced `"YOUR-API-KEY"` with a valid [Ingest API Key](/configure/environments/manage-api-keys/#create-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:
```text theme={}
'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`:
```swift theme={}
prepare_react_native_project!
use_frameworks!
```
2. Install the iOS dependencies by navigating to your `ios` directory and running `pod install`:
```bash theme={}
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.