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 仪表板中可见的自定义信号。

用户定义事件可让你从应用中记录任意命名事件。可用它们跟踪任何你的应用特有、而内置性能指标未覆盖的信号。

事件会持久保存在设备上，经过批处理后，在下一次刷新时以 OpenTelemetry 日志记录的形式发送。它们会显示在 EAS Observe 仪表板的 事件 页面中，并可通过 EAS CLI 查询。

记录事件

在应用中的任意位置调用 Observe.logEvent：

import { Observe } from 'expo-observe';

function handleOnboardingComplete() {
  Observe.logEvent('onboarding.completed');
}

第一个参数是事件名称。请使用稳定的、以点分隔的标识符。仪表板会按精确名称对事件分组。

附加属性

传入 attributes 映射以记录事件上下文：

Observe.logEvent('report.exported', {
  attributes: {
    format: 'csv',
    rowCount: 1248,
    durationMs: 532,
    filters: ['status:active', 'region:us-west'],
  },
});

支持的属性值类型：string、number、boolean、数组以及嵌套对象。其他 JS 值（Date、undefined、函数）会被丢弃。

严重性

事件默认使用 "info" 严重性。对于希望在仪表板中单独展示的警告或错误，可使用 severity 选项覆盖：

Observe.logEvent('sync.failed', {
  severity: 'error',
  attributes: { reason: 'network_timeout' },
});

支持的严重性从低到高依次为："trace"、"debug"、"info"、"warn"、"error"、"fatal"。

正文

使用 body 传入自由格式消息，以补充结构化属性：

Observe.logEvent('cache.evicted', {
  body: '由于磁盘压力超过了配置的阈值，缓存已被驱逐。',
  severity: 'warn',
  attributes: { evictedItemCount: 42, freedBytes: 1048576 },
});

命名规范

• 使用小写、以点分隔的名称：task.completed、onboarding.skipped、report.exported。
• 选择一套词汇并坚持使用。仪表板会按精确事件名称分组，因此 report_exported 和 report.exported 会显示为两行不同的记录。
• 避免在事件名称、属性键和属性值中使用个人身份信息（PII）。你传入的所有内容都可以在仪表板中看到，并且会被发送到设备外。

显示名称

使用 displayName 为仪表板中的事件提供易于理解的标签：

Observe.logEvent('onboarding.completed', {
  displayName: 'Onboarding completed',
});

注意： 你设置的显示名称仅会用于会话时间线视图。

SDK 和集成发出的事件

除了你自己的事件之外，你还可能会看到 EAS Observe 及其集成发出的事件：

• 以 expo. 开头的事件名称是 EAS Observe 自身发出的保留事件。例如，当 iOS 向应用发送低内存警告时，会记录 expo.memory.warning。请参阅内存警告。logEvent 会丢弃使用保留前缀的事件，并丢弃 expo. 命名空间中的属性键；在开发环境中会记录警告。
• 已启用的集成会记录各自的事件。例如，expo-image 集成会在图像解码尺寸远大于屏幕可显示尺寸时记录 expo-image.oversized。

查看事件

在仪表板中：打开你的项目，然后导航到 观察 > 事件。默认视图会列出所选时间范围内不同的事件名称及其计数。点击事件名称即可查看单个事件，包括其时间戳、属性以及所属的会话。

从 CLI：

运行 eas observe:events --help 可查看完整的标志列表（时间范围、平台、会话 ID 等）。请参阅使用 EAS CLI 查询，了解其他 eas observe 命令。