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 在免费计划中每月包含 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 下载时间。
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';
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.