---
title: Performance Monitoring
description: >-
  Performance Monitoring: getPerformance/initializePerformance, trace() custom
  traces, httpMetric() HTTP metrics, newScreenTrace/startScreenTrace, collection
  toggles, SDK_VERSION, and the perf_auto_collection_enabled and
  perf_collection_deactivated firebase.json flags.
next: /perf/axios-integration
previous: /remote-config/usage
---
> ## Documentation Index
> Fetch the complete documentation index at: https://rnfirebase.io/llms.txt
> Use this file to discover all available pages before exploring further.

## Prerequisites

- `@react-native-firebase/app` installed and native config completed per [Getting Started](/) (Android `google-services.json`, iOS `GoogleService-Info.plist`, Expo config plugin, or React Native CLI setup). From v26, New Architecture is required for packages with a native bridge.
- Install Performance Monitoring: `npm install --save @react-native-firebase/perf` or `yarn add @react-native-firebase/perf`, then rebuild native apps (`cd ios && pod install` on iOS).
- On React Native CLI Android builds, apply the Google Performance Monitoring Gradle plugin (see [Add the Performance Monitoring Plugin](/perf/usage#add-the-performance-monitoring-plugin)). The Expo config plugin covers those steps.
- Enable Performance Monitoring for your Firebase project in the [Firebase Console](https://console.firebase.google.com/). Performance Monitoring supports only the default Firebase app.

Example Expo Router screen: https://github.com/invertase/react-native-firebase/blob/main/test-expo/app/perf.tsx

# Installation

This module requires that the `@react-native-firebase/app` module is already setup and installed. To install the "app" module, view the
[Getting Started](/) documentation.

```bash
# Install & setup the app module
yarn add @react-native-firebase/app

# Install the performance monitoring module
yarn add @react-native-firebase/perf

# If you're developing your app using iOS, run this command
cd ios/ && pod install
```

## Add the Performance Monitoring Plugin

> If you're using Expo, make sure to add the `@react-native-firebase/perf` config plugin to your `app.json` or `app.config.js`. It handles the below installation steps for you. For instructions on how to do that, view the [Expo](/#installation-for-expo-projects) installation section.

On Android, you need to install the Google Performance Monitoring Plugin which enables automatic
HTTPS network request monitoring.

Add the plugin to your `/android/build.gradle` file as a dependency, inside the existing `buildscript.dependencies` block:

```groovy
// File: android/build.gradle (inside the existing buildscript.dependencies block)
buildscript {
    dependencies {
        classpath 'com.google.firebase:perf-plugin:2.0.2'
    }
}
```

Apply the plugin via the `/android/app/build.gradle` file (at the top):

```groovy
// File: android/app/build.gradle (top of file)
apply plugin: 'com.android.application'
apply plugin: 'com.google.firebase.firebase-perf'
```

# Platform support and New Architecture

{/* prettier-ignore */}
| | |
| --- | --- |
| **Platforms** | Android, iOS (native Firebase SDK) |
| **New Architecture** | **Required** from v26. See [Migrating to v26](/migrating-to-v26#new-architecture-requirement). |

**Platform notes:** `initializePerformance` returns synchronously on React Native Firebase. Trace, HTTP metric, and screen trace `start`/`stop` are synchronous through TurboModules, matching firebase-js-sdk web `PerformanceTrace` start/stop. Performance Monitoring supports only the default Firebase app. React Native Firebase exports `SDK_VERSION`, `getPerformance`, `initializePerformance`, `trace`, `httpMetric`, `newScreenTrace`, `startScreenTrace`, the `HttpMethod` string union, and the `FirebasePerformance`, `PerformanceTrace`, `HttpMetric`, and `ScreenTrace` types. Each is explained in the section that uses it.

This page does not cover browser User Timing (`performance.mark` / `measure`): that API is web-only and is not bridged here. Automatic First Input Delay and other Core Web Vitals collection is likewise only available in the firebase-js-sdk for browsers. Firebase console dashboard guides (metrics boards, filters, troubleshooting UI) live in the [Firebase Performance Monitoring documentation](https://firebase.google.com/docs/perf-mon/console?utm_source=invertase&utm_medium=react-native-firebase&utm_campaign=perf); this page covers the React Native API only.

# What does it do

Performance Monitoring allows you to gain insight into key performance characteristics within your React Native application.
It provides a simple API to track custom trace and HTTP request metrics.

<YouTube id="0EHSPFvH7vk" />

Review and analyze that data in the Firebase console. Performance Monitoring helps you to understand where and when the
performance of your app can be improved so that you can use that information to fix performance issues.

Performance Monitoring package automatically traces events and metrics which are sent to Firebase. For more information
on the automatic traces, please see the Firebase Performance Monitoring [documentation](https://firebase.google.com/docs/perf-mon/auto_duration-traces-metrics_ios-android).
The package also allows you to performance monitor custom aspects to your application like network requests and task specific
app code. All performance metrics are available on your Firebase [console](https://console.firebase.google.com/u/0/) performance tab.

To learn more, view the [Firebase Performance Monitoring documentation](https://firebase.google.com/docs/perf-mon?utm_source=invertase&utm_medium=react-native-firebase&utm_campaign=perf).

# Usage

## Get a Performance instance

`getPerformance` returns the `FirebasePerformance` module instance for the default Firebase app. Passing `getApp()` still resolves that same default-app instance. Performance Monitoring does not support secondary Firebase apps.

```js
import { getApp } from '@react-native-firebase/app';
import { getPerformance } from '@react-native-firebase/perf';

function readPerformanceInstance() {
  const perf = getPerformance();
  const sameDefaultApp = getPerformance(getApp());
  console.log('Default app name:', perf.app.name);
  console.log('Collection enabled:', perf.isPerformanceCollectionEnabled);
  console.log('dataCollectionEnabled:', perf.dataCollectionEnabled);
  console.log('instrumentationEnabled:', perf.instrumentationEnabled);
  console.log('Same instance for default app:', sameDefaultApp === perf);
}
```

`FirebasePerformance` is the TypeScript type of that instance. On React Native it also exposes `isPerformanceCollectionEnabled` (native collection state) alongside the web-aligned `dataCollectionEnabled` and `instrumentationEnabled` properties.

## Initialize with settings

`initializePerformance(app, settings?)` returns a `FirebasePerformance` instance and optionally applies `PerformanceSettings` (`dataCollectionEnabled`, `instrumentationEnabled`). On React Native Firebase it returns **synchronously** (same instance as `getPerformance(app)`), then assigns any provided settings.

```js
import { getApp } from '@react-native-firebase/app';
import { initializePerformance } from '@react-native-firebase/perf';

function preparePerformance() {
  const perf = initializePerformance(getApp(), {
    dataCollectionEnabled: true,
    instrumentationEnabled: true,
  });
  console.log('Collection enabled:', perf.isPerformanceCollectionEnabled);
  return perf;
}
```

Setting `instrumentationEnabled` from JavaScript takes effect on **iOS** (applied for the next app run). On Android, automatic instrumentation is controlled at Gradle build time by the Performance Monitoring plugin, and assigning `instrumentationEnabled` in JS is a no-op.

## Custom tracing

`trace(performance, name)` returns a `PerformanceTrace` for measuring how long a specific task takes. Call `start` before the work and `stop` after. You can attach custom attributes and custom metrics to the trace.

`PerformanceTrace` on React Native Firebase uses synchronous `start`/`stop` (TurboModule calls), matching firebase-js-sdk web. React Native also exposes `getMetrics` and `removeMetric` for native-backed custom metrics. The web SDK additionally exposes `record()` for recording a trace from already-known timestamps; React Native Firebase does not.

How the JavaScript layer treats a trace:

- `trace` throws if `name` is not a string or is longer than 100 characters.
- Attributes and metrics are kept in JavaScript and sent to native when you call `stop`. Set them before `stop`; changes made after `stop` are not reported.
- Calling `start` or `stop` a second time does nothing.
- `putAttribute` throws if the attribute name is longer than 40 characters, the value is longer than 100 characters, or the trace already has 5 attributes. Both arguments must be strings.
- `putMetric` and `incrementMetric` need a number for the value, and `getMetric` returns `0` for a metric that was never set. The native SDKs store metric values as integers, so decimals are not kept.
- The Firebase backend applies its own rules to names, for example no leading underscore and no leading or trailing spaces, and attribute names limited to letters and underscores. See [Add custom monitoring for specific app code](https://firebase.google.com/docs/perf-mon/custom-code-traces) in the Firebase documentation. Do not put information that identifies a person in attributes.

```js
import { getPerformance, trace } from '@react-native-firebase/perf';

function customTrace() {
  const perf = getPerformance();
  const t = trace(perf, 'custom_trace');

  t.start();
  t.putAttribute('user', 'abcd');
  t.putMetric('credits', 30);
  t.incrementMetric('items', 1);
  console.log('credits metric:', t.getMetric('credits'));
  console.log('all metrics:', t.getMetrics());
  console.log('user attribute:', t.getAttribute('user'));
  t.removeMetric('items');
  t.stop();
}
```

## Custom screen traces

`ScreenTrace` records slow and frozen frame counts for a named screen. `newScreenTrace(performance, screenName)` constructs a JavaScript `ScreenTrace` without starting it; that constructor does not throw for platform support. `startScreenTrace(performance, screenName)` constructs one and starts it immediately. Neither helper exists on the firebase-js-sdk modular Performance API.

Throw timing matches `start`, not JS construction:

- On **iOS**, `ScreenTrace.start()` (and therefore `startScreenTrace`) always throws an error whose message says that custom screen traces are not supported on iOS.
- On **Android**, the throw (if any) happens when native `startScreenTrace` builds the Java `ScreenTrace`: Android API 26 or 27, a missing `FrameMetricsAggregator` class, or hardware acceleration turned off for the Activity. Catching only around `newScreenTrace()` misses that throw.
- Also on **Android**, if there is no current Activity when start runs, native start returns without constructing a trace (silent no-op).
- `newScreenTrace` and `startScreenTrace` throw if `screenName` is not a string or is longer than 100 characters. Calling `stop` before `start` does nothing.

```js
import { getPerformance, newScreenTrace, startScreenTrace } from '@react-native-firebase/perf';

function screenTraceWithNew() {
  // WARNING: ScreenTrace.start throws on iOS. On Android, unsupported devices
  // (API 26/27 or hardware acceleration off) throw during native start; a null
  // current Activity is a silent no-op. newScreenTrace itself does not throw.
  const screenTrace = newScreenTrace(getPerformance(), 'FooScreen');
  screenTrace.start();
  screenTrace.stop();
}

function screenTraceStarted() {
  // WARNING: startScreenTrace throws on iOS. On Android, unsupported devices
  // (API 26/27 or hardware acceleration off) throw during native start; a null
  // current Activity is a silent no-op.
  const screenTrace = startScreenTrace(getPerformance(), 'FooScreen');
  screenTrace.stop();
}
```

## HTTP Request Tracing

`httpMetric(performance, url, httpMethod)` constructs an `HttpMetric` for measuring HTTP request latency. `HttpMethod` is the string union of allowed verbs (`GET`, `HEAD`, `PUT`, `POST`, `PATCH`, `TRACE`, `DELETE`, `CONNECT`, `OPTIONS`). The firebase-js-sdk modular Performance API does not expose HTTP metrics on its public modular surface; React Native Firebase does via native instrumentation.

Performance Monitoring already collects network request traces automatically for requests made through the native networking libraries that Firebase supports (see [HTTP/S network request performance data](https://firebase.google.com/docs/perf-mon/network-traces)). Use `httpMetric` for requests that those traces miss, or to attach your own attributes and payload sizes.

- `httpMetric` throws if `url` is not a string or `httpMethod` is not one of the `HttpMethod` values.
- Call `start` before the request. Before `stop`, set at least `setHttpResponseCode`. Without a response code the metric is still stopped locally, but the package logs a warning and the metric will not be visible in the Firebase console.
- `setHttpResponseCode`, `setRequestPayloadSize` and `setResponsePayloadSize` accept a number or `null`, and `setResponseContentType` accepts a string or `null`. They throw for `undefined` and any other type, so pass `null` when a value is missing, for example a response without a `Content-Type` header.
- The response code, payload sizes, content type and attributes are kept in JavaScript and sent to native when you call `stop`. `putAttribute` follows the same limits as for traces.
- Calling `start` or `stop` a second time does nothing.

```js
import { getPerformance, httpMetric } from '@react-native-firebase/perf';

async function getRequest(url) {
  const metric = httpMetric(getPerformance(), url, 'GET');

  metric.putAttribute('user', 'abcd');
  metric.setRequestPayloadSize(0);

  metric.start();

  const response = await fetch(url);
  const contentLengthHeader = response.headers.get('Content-Length');
  metric.setHttpResponseCode(response.status);
  metric.setResponseContentType(response.headers.get('Content-Type'));
  metric.setResponsePayloadSize(contentLengthHeader ? Number(contentLengthHeader) : null);

  metric.stop();

  return response.json();
}

getRequest('https://api.com').then(json => {
  console.log(json);
});
```

For Axios and KY interceptors that wrap `httpMetric`, see [Axios integration](/perf/axios-integration) and [KY integration](/perf/ky-integration).

## Collection toggles

`dataCollectionEnabled` and `isPerformanceCollectionEnabled` read the same value: the Performance Monitoring data collection flag. Assigning `dataCollectionEnabled` updates that value and calls the native SDK without waiting for it to finish. Assigning `instrumentationEnabled` controls automatic (out-of-the-box) monitoring on iOS and does nothing on Android. Both setters throw if the value is not a boolean.

`dataCollectionEnabled` starts with the value the native SDK reports at startup, which reflects the `perf_auto_collection_enabled` and `perf_collection_deactivated` options from `firebase.json`. On Android `instrumentationEnabled` always starts as `true` and is not affected by assignments.

Prefer assigning the properties on the modular instance:

```js
import { getPerformance } from '@react-native-firebase/perf';

function enableCollection() {
  const perf = getPerformance();
  perf.dataCollectionEnabled = true;
  // instrumentationEnabled assignment applies on iOS only; Android automatic
  // instrumentation is controlled by the Gradle Performance Monitoring plugin.
  perf.instrumentationEnabled = true;
  console.log('Collection enabled:', perf.isPerformanceCollectionEnabled);
}

function disableCollection() {
  const perf = getPerformance();
  perf.dataCollectionEnabled = false;
  perf.instrumentationEnabled = false;
}
```

# firebase.json

## Disable Auto-Initialization

The Performance Monitoring module will automatically start collecting data once it is installed. To disable this behavior,
set the `perf_auto_collection_enabled` flag to `false`:

```json
// <project-root>/firebase.json
{
  "react-native": {
    "perf_auto_collection_enabled": false
  }
}
```

To re-enable collection at runtime after the user consents, assign `dataCollectionEnabled` (and on iOS, `instrumentationEnabled` if you also want automatic monitoring) as shown in [Collection toggles](/perf/usage#collection-toggles).

## Deactivate collection permanently

Set `perf_collection_deactivated` to `true` to switch Performance Monitoring off for a build in a way that your app cannot undo at runtime. It takes precedence over `perf_auto_collection_enabled`. Remove it to turn collection back on.

```json
// <project-root>/firebase.json
{
  "react-native": {
    "perf_collection_deactivated": true
  }
}
```

Both options are read when the app is built, so rebuild the app after you change them. On Android they set the `firebase_performance_collection_enabled` and `firebase_performance_collection_deactivated` manifest values described in [Disable Firebase Performance Monitoring](https://firebase.google.com/docs/perf-mon/disable-sdk). On iOS they set the matching keys in the app's `Info.plist`.

# Package version

`SDK_VERSION` is the React Native Firebase Performance Monitoring package version string exported from `@react-native-firebase/perf`. The firebase-js-sdk does not export `SDK_VERSION` from `@firebase/performance`.

```js
import { SDK_VERSION } from '@react-native-firebase/perf';

console.log('Performance package version:', SDK_VERSION);
```
