配置 EAS Observe

编辑页面

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

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

`configure()`

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

import { Observe } from 'expo-observe';

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

Option	Type	Default	Description
`environment`	`string`	`process.env.NODE_ENV`	可观测性事件的环境标签
`dispatchingEnabled`	`boolean`	`true`	是否将收集的事件发送到服务器
`dispatchInDebug`	`boolean`	`false`	是否发送在调试构建中收集的指标。对发布构建无效。
`sampleRate`	`number`	`undefined`	分发指标的安装实例比例，取值范围为 `[0, 1]`。参见采样。
`integrations`	`object`	`undefined`	EAS Observe 集成的选择性启用设置。参见 Expo Router、React Navigation，或集成你自己的包。

`dispatchEvents()`

当应用切换到后台时，事件会自动分发。在 Android 上，一旦网络连接可用，后台 worker 就会分发事件。在 iOS 上，这发生在应用失去活跃状态或即将终止时。

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

import { Observe } from 'expo-observe';

await Observe.dispatchEvents();

抽样

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

import { Observe } from 'expo-observe';

// 从大约 25% 的安装中分发指标。
Observe.configure({
  sampleRate: 0.25,
});

抽样决策对每次安装是确定性的。对于给定的抽样率，每次安装要么永久处于样本内，要么永久处于样本外，因此该选择在应用启动之间保持稳定，你获得的是一组一致的安装切片，而不是会话的随机子集。

有几点细节值得了解：

超出 [0, 1] 范围的值会被限制到最近的边界。0 始终丢弃；1 始终分发。
样本外设备会丢弃待处理的指标，而不是累积它们。稍后降低抽样率不会追溯发送更早的会话。
抽样依赖于 dispatchingEnabled。如果 dispatchingEnabled 为 false，无论 sampleRate 是多少，都不会分发任何内容。

开发中启用指标

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

import { Observe } from 'expo-observe';

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

如果原生应用是调试构建，或者 JS bundle 是开发包（__DEV__ 为 true），则会将构建视为调试构建。此检测与 environment 值无关（参见环境）。

dispatchInDebug 对发布构建没有影响；发布构建始终会分发（受 dispatchingEnabled 和 sampleRate 约束）。如果 dispatchingEnabled 为 false，或者此安装处于样本外，则无论 dispatchInDebug 如何，都不会分发任何内容。

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

自定义端点

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

要更改端点，请在你的 app config 中设置 endpointUrl 的值：

app.json

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

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

路径中会在标准的 /v1/metrics 和 /v1/logs OTLP 路径之前包含你的项目 ID。如果你的后端期望的是不带该前缀的标准 OTLP 路径，请将数据发送到一个 OpenTelemetry Collector，由它接收数据并重新导出到你的后端。

环境

所有指标都会按环境分组。默认情况下，环境值由 process.env.NODE_ENV 派生（如果未设置，则回退为 'production'）。若要覆盖它，请使用 configure({ environment })。

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