This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

控制 EAS Observe 如何收集和传送指标，包括环境设置、开发模式和自定义端点。

在运行时配置 EAS Observe，以适应你的应用构建设置、环境和数据路由。本页涵盖 configure() 和 dispatchEvents()，在开发中启用指标、使用自定义端点，以及按环境分离数据。

🌐 Configure EAS Observe at runtime to fit your app's build setup, environment, and data routing. This page covers the configure() and dispatchEvents(), enabling metrics in development, using a custom endpoint, and separating data by environment.

configure()

使用 configure() 方法来控制 EAS Observe 在运行时的行为：

🌐 Use the configure() method to control how EAS Observe behaves at runtime:

import { Observe } from 'expo-observe';

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

dispatchEvents()

当应用进入后台时，事件会自动分发。在 Android 上，一旦网络连接可用，后台工作线程就会分发事件。在 iOS 上，当应用失去活跃状态或即将终止时，会发生这种情况。

🌐 Events are automatically dispatched when the app moves to the background. On Android, a background worker dispatches events once network connectivity is available. On iOS, this happens when the app resigns active state or is about to terminate.

要手动刷新事件（例如，在测试期间或为了确保事件在特定时间点之前发送），请调用 dispatchEvents()：

🌐 To flush events manually (for example, during testing or to ensure events are sent before a specific point), call dispatchEvents():

import { Observe } from 'expo-observe';

await Observe.dispatchEvents();

采样

🌐 Sampling

默认情况下，每个安装都会发送其指标。对于高流量应用，你可以通过将 sampleRate 设置为介于 0 和 1 之间的值来抽样部分安装：

🌐 By default, every installation dispatches its metrics. For high-volume apps, you can sample a fraction of installations by setting sampleRate to a value between 0 and 1:

import { Observe } from 'expo-observe';

// Dispatch metrics from ~25% of installations.
Observe.configure({
  sampleRate: 0.25,
});

采样决策是针对每个安装确定的。每个安装对于给定的比率要么永久处于样本内，要么永久处于样本外，因此该选择在应用启动时是稳定的，并且你获得的是一部分稳定的安装，而不是会话的随机子集。

🌐 The sampling decision is deterministic per installation. Each installation is either permanently in-sample or out-of-sample for a given rate, so the choice is stable across app launches and you get a consistent slice of installations rather than a random subset of sessions.

值得了解的一些细节：

🌐 A few details worth knowing:

• 超出 [0, 1] 范围的值会被限制到最近的边界。0 总是下降；1 总是分发。
• 样本外设备会放弃待处理的指标，而不是累积它们。稍后降低速率不会追溯发送之前的会话。
• 采样取决于dispatchingEnabled。如果dispatchingEnabled是false，无论sampleRate如何，都不会派发任何内容。

在开发中启用指标

🌐 Enable metrics in development

默认情况下，从调试构建中收集的指标不会被发送。要仍然发送这些指标（例如，在测试你的 EAS Observe 集成时），在调用 configure() 时将 dispatchInDebug 设置为 true：

🌐 By default, metrics collected from debug builds are not dispatched. To dispatch them anyway (for example, while testing your EAS Observe integration), set dispatchInDebug to true when calling configure():

import { Observe } from 'expo-observe';

Observe.configure({
  dispatchInDebug: true,
});

如果本地应用是调试版本或 JS 包是开发包（__DEV__ 是 true），构建将被视为调试构建。这种检测独立于 environment 的值（参见 Environments）。

🌐 A build is treated as a debug build if either the native app is a debug build or the JS bundle is a development bundle (__DEV__ is true). This detection is independent of the environment value (see Environments).

dispatchInDebug 对发布版本没有影响，发布版本总是会派发（受 dispatchingEnabled 和 sampleRate 的约束）。如果 dispatchingEnabled 是 false 或者该安装属于样本外，则无论 dispatchInDebug 如何，都不会派发。

警告 仅在测试你的 EAS Observe 集成时启用此功能。开发/调试的性能与生产环境差异显著，因此收集开发/调试指标可能会扭曲仪表板中显示的结果。

自定义端点

🌐 Custom endpoint

EAS Observe 使用 OpenTelemetry 协议（OTLP）通过 HTTP 发送带有 JSON 负载的数据。它将指标发布到 <endpointUrl>/<project-id>/v1/metrics，将日志发布到 <endpointUrl>/<project-id>/v1/logs，其中 <project-id> 是你的 EAS 项目 ID。这意味着你可以将 endpointUrl 设置为 OpenTelemetry 兼容的后端或 OpenTelemetry Collector，以将你的可观测性数据路由到那里。

要更改端点，请在你的 应用配置 中设置 endpointUrl 值：

🌐 To change the endpoint, set the endpointUrl value in your app config:

{
  "expo": {
    "extra": {
      "eas": {
        "observe": {
          "endpointUrl": "https://your-custom-endpoint.com"
        }
      }
    }
  }
}

端点 URL 在应用的原生层中于构建时内置，因此更改它需要重新生成原生代码。更新应用配置后，运行 npx expo prebuild 并创建一个新构建以应用更改。

🌐 The endpoint URL is baked into the native layer of the app at build time, so changing it requires regenerating native code. After updating your app config, run npx expo prebuild and create a new build to apply the change.

该路径在标准的 /v1/metrics 和 /v1/logs OTLP 路径之前包含你的项目 ID。如果你的后端期望没有该前缀的标准 OTLP 路径，请将数据发送到接收它的 OpenTelemetry Collector，然后将其重新导出到你的后端。

🌐 The path includes your project ID before the standard /v1/metrics and /v1/logs OTLP paths. If your backend expects the standard OTLP path without that prefix, send the data to an OpenTelemetry Collector that receives it and re-exports it to your backend.

环境

🌐 Environments

所有指标按环境分组。环境值默认由 process.env.NODE_ENV 导出（如果未设置，则回退到 'production'）。要覆盖它，请使用 configure({ environment })。

🌐 All metrics are grouped by environment. The environment value is derived from process.env.NODE_ENV by default (falling back to 'production' if unset). To override it, use configure({ environment }).

环境是附加到每个指标的元数据标签，与打包包的构建方式无关。要控制是否发送调试构建的指标，请参见 在开发中启用指标。要在全局范围内禁用所有发送，请使用 configure({ dispatchingEnabled: false })。

🌐 The environment is a metadata tag attached to each metric and is independent of how the bundle was built. To control whether debug-build metrics are dispatched, see Enable metrics in development. To disable all dispatching globally, use configure({ dispatchingEnabled: false }).