Expo Observe

A library that collects app performance metrics and dispatches them to EAS Observe.

Android

iOS

tvOS

GitHub

npm

Changelog

Recommended version:

~56.0.27

EAS Observe is in Open Beta. The first 10,000 monthly active users are free. For higher usage, contact sales@expo.dev.

expo-observe is a library that collects performance metrics and user-defined events from your app and dispatches them to EAS Observe, a performance monitoring service from Expo, or to your preferred OpenTelemetry (OTEL)-compliant backend. It measures real-world startup performance, such as Time to First Render (TTR) and Time to Interactive (TTI), from apps running in production.

expo-observe is not available in Expo Go. To use it, create a development build.

Installation

Terminal

- npx expo install expo-observe

If you are installing this in an existing React Native app, make sure to install expo in your project.

Configuration

In release builds, installing the expo-observe library is all that is needed to configure the library to start sending startup metrics (though you will need to follow the usage instructions below to call markInteractive to track TTI). The library will not dispatch events in debug builds, but you can change this and other config options such as sample rate, environment name and enabling integrations with the Observe.configure({}) call. For all available options, see the EAS Observe configuration guide.

Usage

Wrap your root layout with ObserveRoot to measure Time to First Render automatically. Then, call markInteractive when your app is ready for user interaction to record Time to Interactive:

src/app/_layout.tsx

import { ObserveRoot, useObserve } from 'expo-observe';
import { Stack } from 'expo-router';
import { useEffect } from 'react';

function RootLayout() {
  const { markInteractive } = useObserve();

  useEffect(() => {
    // Call markInteractive() after any initialization work behind the
    // splash screen completes.
    markInteractive();
  }, [markInteractive]);

  return <Stack />;
}

export default ObserveRoot.wrap(RootLayout);

For step-by-step instructions, including how to handle apps with multiple entry screens, see the EAS Observe Get started guide. To send custom events from your app, see User-defined events.

API

import { Observe, ObserveRoot, useObserve } from 'expo-observe';

Component

`ObserveRoot`

Android

iOS

tvOS

Type: React.Element<{ children: ReactNode } & { children: ReactNode }>

Component methods

`wrap(Component)`

Android

iOS

tvOS

Parameter	Type
Component	`ComponentType<P>`

Returns:

ComponentType<P>

Hooks

`useObserve()`

Android

iOS

tvOS

Returns:

{
  markInteractive: (attributes: MetricAttributes) => void
}

Interfaces

`ExpoAppMetricsModuleType`

Android

iOS

tvOS

ExpoAppMetricsModuleType Methods

`clearStoredEntries()`

Android

iOS

tvOS

Returns:

Promise<void>

`logEvent(name, options)`

Android

iOS

tvOS

Parameter	Type	Description
name	`string`	Event name. Maps to the OpenTelemetry `event.name` attribute.
options(optional)	`LogEventOptions`	Optional body, attributes, and severity overrides.

Records a log event against the current main session. The event is persisted locally and dispatched on the next dispatchEvents() flush as an OpenTelemetry log record sent to the /v1/logs endpoint.

Severity defaults to "info" when not provided.

Returns:

void

`markFirstRender()`

Android

iOS

tvOS

Returns:

void

`markInteractive(attributes)`

Android

iOS

tvOS

Parameter	Type
attributes(optional)	`MetricAttributes`

Returns:

void

`setGlobalAttributes(attributes)`

Android

iOS

tvOS

Parameter	Type
attributes(optional)	`Record<string, LogAttributeValue> \| null`

Sets attributes merged into every subsequent metric and log event. Per-record keys win on collision. Pass null, undefined, or an empty object to clear.

Returns:

void

Example

AppMetrics.setGlobalAttributes({
  subscription_tier: 'pro',
  experiment_variant: 'B',
});

`ObserveModule`

Android

iOS

tvOS

Extends: NativeModule

ObserveModule Methods

`configure(config)`

Android

iOS

tvOS

Parameter	Type	Description
config	`ObserveConfig`	Observability settings to apply.

Configures how observability events are collected and dispatched at runtime, such as the environment label, dispatching behavior, sampling, and integrations.

Returns:

void

Example

import { Observe } from 'expo-observe';

Observe.configure({
  environment: 'production',
  dispatchingEnabled: true,
});

`dispatchEvents()`

Android

iOS

tvOS

Dispatches pending events to the server immediately.

Events are dispatched automatically when the app moves to the background. On Android, a background worker dispatches events once network connectivity is available. On iOS, dispatching happens when the app resigns active state or is about to terminate. Call this method to flush events manually, for example, during testing or to ensure events are sent before a specific point.

Returns:

Promise<void>

A promise that resolves when the pending events have been dispatched.

Example

import { Observe } from 'expo-observe';

await Observe.dispatchEvents();

`logEvent(name, options)`

Android

iOS

tvOS

Parameter	Type	Description
name	`string`	Event name.
options(optional)	`LogEventOptions`	Optional body, attributes, and severity overrides.

Records a log event against the current main session. The event is persisted locally and dispatched on the next dispatchEvents() flush.

Severity defaults to "info" when not provided.

Returns:

void

`markFirstRender()`

Android

iOS

tvOS

Marks the first render of the app. Used to compute the cold_ttr and warm_ttr metrics.

Returns:

void

`markInteractive(attributes)`

Android

iOS

tvOS

Parameter	Type
attributes(optional)	`MetricAttributes`

Marks the moment the app becomes interactive. Used to compute the tti metric. Custom routeName and params can be attached via attributes.

Note: When the expo-router or @react-navigation/native integration is active, prefer useObserve().markInteractive(...) — the hook fills in routeName from the current route, while this raw call does not.

Returns:

void

`setBundleDefaults(defaults)`

Android

iOS

tvOS

Parameter	Type
defaults	`{ environment: string, isJsDev: boolean }`

Pushes JS-bundle-derived facts (process.env.NODE_ENV, __DEV__) into native storage. Called automatically once when the package is first imported; should not be called by host apps directly.

Returns:

void

`setGlobalAttributes(attributes)`

Android

iOS

tvOS

Parameter	Type
attributes(optional)	`ObserveAttributes \| null`

Sets attributes merged into every subsequent metric and log event. Per-record keys win on collision. Pass null, undefined, or an empty object to clear.

Returns:

void

Example

Observe.setGlobalAttributes({
  subscription_tier: 'pro',
  experiment_variant: 'B',
});

Types

`LogAttributeValue`

Android

iOS

tvOS

Value types accepted in a log event's attributes map. Strings, numbers, and booleans are stored as typed primitives; arrays and nested maps preserve their structure. Other JS values (functions, Date, undefined, etc.) are not supported and may be dropped by downstream consumers.

Type: string or number or boolean or object shaped as below:

Property	Type	Description
key(index signature)	`LogAttributeValue`	-

`LogEventOptions`

Android

iOS

tvOS

Optional configuration accepted by logEvent. The event name is passed as the first positional argument since it's required and the only field most callers set.

Property	Type	Description
attributes(optional)	`Record<string, LogAttributeValue> \| null`	Custom attributes attached to the event. Each entry is preserved with its original value type — see `LogAttributeValue` for the supported shapes.
body(optional)	`string \| null`	Optional free-form message describing the event.
severity(optional)	`LogSeverity \| null`	Severity of the event. Default:`"info"`

`LogSeverity`

Android

iOS

tvOS

Literal type: string

Severity of a log event, ordered from least to most severe:

"trace" — Fine-grained tracing, typically only useful while reproducing a specific issue.
"debug" — Diagnostic detail useful during development; usually filtered out in production.
"info" — Routine, expected events that record normal app behavior.
"warn" — Unexpected but recoverable conditions worth investigating.
"error" — An operation failed; the app continues running but is in a degraded state.
"fatal" — A severe failure, often immediately followed by app termination.

`MetricAttributes`

Android

iOS

tvOS

Property	Type	Description
params(optional)	`Record<string, unknown>`	Custom parameters to attach to the metric.
routeName(optional)	`string \| null`	Name of the route associated with the metric. Some metrics populate this with a sensible default when omitted — for example, the TTI metric falls back to the initial route name detected from the router.

`ObserveAttribute`

Android

iOS

tvOS

Type: LogAttributeValue

Value types accepted as attribute values in setGlobalAttributes and the other Observe APIs. Strings, numbers, and booleans are stored as typed primitives; arrays and nested maps preserve their structure.

`ObserveAttributes`

Android

iOS

tvOS

Type: Record<string, ObserveAttribute>

A map of attribute key to value, as accepted by setGlobalAttributes and other Observe APIs that take a free-form attributes payload.

`ObserveConfig`

Android

iOS

tvOS

Property	Type	Description
dispatchInDebug(optional)	`boolean`	Whether to dispatch metrics that were collected in a debug build of the host app. When `false`, metrics produced by debug builds are marked as sent without being dispatched. When `true`, debug-build metrics are dispatched alongside release-build metrics. Has no effect on release builds. If `dispatchingEnabled` is `false` or this device is out-of-sample for `sampleRate`, nothing is dispatched regardless of `dispatchInDebug`. Default:`false`
dispatchingEnabled(optional)	`boolean`	Whether to dispatch observability events to the server. When `false`, any pending metrics are marked as sent without being dispatched and no further metrics are dispatched until this is set back to `true`. Default:`true`
environment(optional)	`string`	The environment for observability events Default:`process.env.NODE_ENV`
integrations(optional)	`ObserveIntegrationsConfig`	Opt in to per-integration behavior. See the Expo Router and React Navigation integrations, or integrate your own package.
sampleRate(optional)	`number`	Fraction of installations that should dispatch metrics, in `[0, 1]`. Values outside that range are clamped. The decision is deterministic per installation — a device is either permanently in-sample or out-of-sample for a given rate, so the choice is stable across app launches. Interaction with `dispatchingEnabled`: If `dispatchingEnabled` is `false`, metrics are never dispatched If `dispatchingEnabled` is `true` (or unset), metrics are dispatched only when this device is in-sample. Note: Devices that end up out-of-sample drop pending metrics rather than accumulating them. Default:`undefined - metrics from all devices are sent`

`ObserveIntegrationsConfig`

Android

iOS

tvOS

Property	Type	Description
expo-router(optional)	`boolean`	Enables the `expo-router` integration, which records navigation metrics (`cold_ttr`, `warm_ttr`, `tti`) from router state changes. Requires `expo-router` to be installed. Default:`false`
react-navigation(optional)	`boolean`	Enables the `@react-navigation/native` integration, which records navigation metrics (`cold_ttr`, `warm_ttr`, `tti`). Requires `@react-navigation/native` to be installed and the app tree to be wrapped in `<ObserveNavigationContainer>` instead of the stock `<NavigationContainer>`. Default:`false`