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() API 参考。

🌐 Configure EAS Observe at runtime to fit your app's build setup, environment, and data routing. This page covers enabling metrics in development, sampling, using a custom endpoint, separating data by environment, and turning off data ingestion from the dashboard. For the runtime methods themselves, see the configure() and dispatchEvents() API references.

采样

🌐 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 }).

网络跟踪

🌐 Network traces

信息 网络追踪需要 SDK 58 或更高版本。

完成的网络请求可以记录为跟踪跨度。默认情况下，记录是关闭的，因为每个跨度都会计入你的事件配额。可以通过以下方式开启：

🌐 Completed network requests can be recorded as trace spans. Recording is off by default, because each span counts toward your event quota. Turn it on with:

import { Observe } from 'expo-observe';

Observe.configure({ networkTraces: true });

传入一个对象来记录你关心的请求。主机名完全匹配且不区分大小写，所以不会包含子域名。省略的字段会匹配所有请求，而空数组则不匹配任何请求：

🌐 Pass an object to record only the requests you care about. Hosts match exactly and case-insensitively, so subdomains are not implied. An omitted field matches every request, and an empty array matches none:

Observe.configure({
  networkTraces: { filter: { hosts: ['api.myapp.com'], methods: ['GET', 'POST'] } },
});

对象形式会记录，除非你另有说明，所以设置 enabled: false 来在不记录任何内容的同时保留一个配置的过滤器。

🌐 The object form records unless you say otherwise, so set enabled: false to keep a filter configured while recording nothing.

被关闭或过滤掉的请求永远不会到达本地数据库，所以不会存储也不会导出。该设置适用于将来的请求，因此启动时之前记录的跨度仍然会被发送。它在多次启动之间也会保留，所以在下次启动运行configure之前观察到的请求会遵循你上次设置的值。

🌐 A request that is turned off or filtered out never reaches the local database, so nothing is stored and nothing is exported. The setting applies to future requests, so spans recorded earlier in the launch are still sent. It also persists across launches, so requests observed before configure runs on the next launch follow the last value you set.

因为这个值会一直存在，移除选项会在下次 configure 运行时生效，而不会立即生效。对于一个狭窄的 hosts 列表也是一样：它会持续阻止早期启动的请求，直到 configure 将其扩大。

🌐 Because the value persists, removing the option takes effect the next time configure runs, not immediately. The same applies to a narrow hosts list: it keeps suppressing early-startup requests until a configure widens it.

在存储之前，URL 会被编辑掉。URL 中的用户名和密码会被替换成 REDACTED，查询参数 AWSAccessKeyId、Signature、sig、X-Amz-Signature、X-Amz-Credential、X-Amz-Security-Token 和 X-Goog-Signature 也会被同样替换。其他查询参数中的秘密会原样存储。

🌐 URLs are redacted before they are stored. A username and password in the URL are replaced with REDACTED, as are the query parameters AWSAccessKeyId, Signature, sig, X-Amz-Signature, X-Amz-Credential, X-Amz-Security-Token, and X-Goog-Signature. A secret in any other query parameter is stored as-is.

关闭数据摄取

🌐 Turn off data ingestion

上面的选项控制你的应用发送什么内容。你也可以在不发布应用更新的情况下，通过 EAS 仪表板中的 Observe 数据摄取 开关，停止 EAS Observe 在服务器端接收数据：

🌐 The options above control what your app sends. You can also stop EAS Observe from accepting data on the server side, without shipping an app update, using the Observe data ingestion toggle in the EAS dashboard:

• 账户级别：打开 账户设置 并关闭 观察数据摄取。这会暂停账户中所有项目的数据摄取。
• 项目级别：打开项目设置并关闭观察数据摄取。这只会暂停该项目的数据摄取。

在暂停数据接收时，EAS Observe 不会接受你应用发送的事件、指标或日志。已经接收的数据仍然可以在仪表板和命令行中查看。将开关重新打开即可恢复数据接收。

🌐 While ingestion is paused, EAS Observe does not accept events, metrics, or logs sent by your apps. Data that was already ingested stays available in the dashboard and the CLI. Turn the toggle back on to resume ingestion.