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
一个收集应用性能指标和用户定义事件，并将其分发到 EAS Observe 的库
信息 EAS Observe 的 Free 计划每月包含 100,000 个事件，付费计划每月包含 500,000 个事件，大约对应每月 10,000 和 50,000 名活跃用户。超出部分按用量计费。详情请参阅定价。
expo-observe 是一个库，可收集应用中的性能指标和用户定义事件，并将其发送到 EAS Observe（Expo 提供的性能监控服务），或发送到你首选的 OpenTelemetry（OTEL）兼容后端。它会测量生产环境中运行的应用的实际启动性能，例如首次渲染时间（TTR）和可交互时间（TTI）。
除应用启动指标外，该库还可以：
- 使用 Expo Router 或 React Navigation 集成，收集各路由的导航指标。
- 使用
Observe.logEvent记录用户定义事件。 - 自动跟踪 EAS Update 下载时间。
- 使用
ObserveErrorBoundary和Observe.reportError记录 JavaScript 错误，并在 EAS Observe 控制面板中查看带符号解析堆栈跟踪的错误（处于预览阶段）。 - 允许第三方包使用
Observe.registerIntegration注册自己的集成。
警告
expo-observe在 Expo Go 中不可用。要使用它，请创建一个开发构建。
安装
If you are installing this in an existing React Native app, make sure to install expo in your project.
配置
在发布构建中，只需安装 expo-observe 库即可将其配置为开始发送启动指标（不过，你还需要按照下面的使用说明调用 markInteractive 来跟踪 TTI）。该库不会在调试构建中发送事件，但你可以通过调用 Observe.configure({}) 更改此设置以及其他配置选项，例如采样率、环境名称和是否启用集成。有关所有可用选项，请参阅 EAS Observe 配置指南。
使用方法
使用 ObserveRoot 包装根布局，即可自动测量首次渲染时间。然后，在应用准备好供用户交互时调用 markInteractive，以记录可交互时间：
有关分步说明（包括完整的启动屏幕示例，以及如何处理具有多个入口屏幕的应用），请参阅 EAS Observe 入门指南。要从应用发送自定义事件，请参阅用户定义事件。
API
import { Observe, ObserveRoot, useObserve } from 'expo-observe';
Components
Type: React.Component<AppMetricsErrorBoundaryProps, State>
A React error boundary that records render-phase errors as non-fatal js.exception log events (with
the React component stack) and renders a fallback in place of the subtree that threw.
Render-phase errors don't reach global.ErrorUtils, so a boundary is the only way to capture them
with the component stack. Place one around any subtree, or let AppMetricsRoot mount one via its
errorBoundaryFallback prop.
Type: React.Element<ObserveInteractiveMarkerProps>
Declarative wrapper around useObserve().markInteractive(...). Renders nothing
and calls markInteractive once when it first mounts, marking the moment the
screen becomes interactive (used to compute the tti metric). Render it once
the screen is ready for user interaction — for example, after its initial data
has loaded.
Because markInteractive is only sent on mount, the marker is fire-once: changing
params after the first render has no effect and warns in development. If you need
to attach attributes that are only known later, call useObserve().markInteractive(...)
imperatively instead.
Example
import { ObserveInteractiveMarker } from 'expo-observe'; function Feed({ items }) { if (!items) return <Spinner />; return ( <> <FeedList items={items} /> <ObserveInteractiveMarker params={{ cacheHit: true }} /> </> ); }
Type: React.Element<AppMetricsRootProps & {
children: ReactNode
}>
Static methods
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<ObserveModuleEvents>
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 once the events have been dispatched. A call made while another dispatch is running waits for it to finish first.
Example
import { Observe } from 'expo-observe'; await Observe.dispatchEvents();
Returns the integrations config from the most recent configure(...)
call, or an empty object if configure has not run yet.
ObserveIntegrationsConfigRecords 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.
voidInvokes a callback once when the named integration configuration becomes available.
voidExample
Observe.registerIntegration('expo-router', config => { console.log(config); });
Reports an error your code caught and handled, recorded as a non-fatal exception event. Use it
to keep visibility into failures you recover from, which never reach the automatic global handler
or an error boundary.
The thrown value is normalized: an Error's name, message, and stack are captured; any
other value (a string, a plain object) is stringified as the message.
voidExample
try { await syncCart(); } catch (error) { Observe.reportError(error); }
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.
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.