This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo Observe
A library that collects app performance metrics and user-defined events and dispatches them to EAS Observe.
EAS Observe includes 100,000 events per month on the Free plan and 500,000 on paid plans, roughly 10,000 and 50,000 monthly active users. Beyond that, pricing is usage-based. See Pricing for details.
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.
Beyond app startup metrics, the library can also:
- Collect per-route navigation metrics with the Expo Router or React Navigation integration.
- Log user-defined events with
Observe.logEvent. - Track EAS Update download times automatically.
expo-observeis not available in Expo Go. To use it, create a development build.
Installation
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:
For step-by-step instructions, including a complete splash screen example and 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
Component methods
Hooks
{
markInteractive: (attributes: MetricAttributes) => void
}Interfaces
ExpoAppMetricsModuleType Methods
Promise<void>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.
voidSets attributes merged into every subsequent metric and log event.
Per-record keys win on collision. Pass null, undefined, or an empty
object to clear.
voidExample
AppMetrics.setGlobalAttributes({ subscription_tier: 'pro', experiment_variant: 'B', });
Extends: NativeModule
Configures how observability events are collected and dispatched at runtime, such as the environment label, dispatching behavior, sampling, and integrations.
voidExample
import { Observe } from 'expo-observe'; Observe.configure({ environment: 'production', dispatchingEnabled: true, });
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.
Promise<void>A promise that resolves when the pending events have been dispatched.
Example
import { Observe } from 'expo-observe'; await Observe.dispatchEvents();
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.
voidMarks the first render of the app. Used to compute the cold_ttr and
warm_ttr metrics.
voidMarks 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-routeror@react-navigation/nativeintegration is active, preferuseObserve().markInteractive(...)— the hook fills inrouteNamefrom the current route, while this raw call does not.
voidPushes 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.
voidTypes
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:
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.
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.
Acceptable values are: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
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.
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.