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

用户自定义事件允许你从应用记录任意名称的事件。使用它们来跟踪内置性能指标未涵盖的应用特定信号。

🌐 User-defined events let you record arbitrary, named events from your app. Use them to track any signal specific to your app that the built-in performance metrics do not cover.

事件会在设备上持久化、批处理，并在下一次刷新时作为 OpenTelemetry 日志记录发送。它们会出现在 EAS Observe 仪表板的 事件 标签中，并且可以通过 EAS CLI 查询。

🌐 Events are persisted on-device, batched, and dispatched on the next flush as OpenTelemetry log records. They appear in the Events tab of the EAS Observe dashboard and are queryable from the EAS CLI.

记录一个事件

🌐 Log an event

在应用中的任何地方调用 Observe.logEvent：

🌐 Call Observe.logEvent from anywhere in your app:

import { Observe } from 'expo-observe';

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

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

🌐 The first argument is the event name. Use a stable, dot-separated identifier. The dashboard groups events by exact name.

附加属性

🌐 Attach attributes

传递一个 attributes 映射以使用事件记录上下文：

🌐 Pass an attributes map to record context with the event:

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

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

🌐 Supported attribute value types: string, number, boolean, arrays, and nested objects. Other JS values (Date, undefined, functions) are dropped.

严重性

🌐 Severity

事件默认具有 "info" 严重性。通过 severity 选项覆盖，用于在仪表板中单独显示你想要的警告或错误：

🌐 Events default to "info" severity. Override with the severity option for warnings or errors you want to surface separately in the dashboard:

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

支持的严重性级别，从最低到最高："trace"、"debug"、"info"、"warn"、"error"、"fatal"。

🌐 Supported severities, from lowest to highest: "trace", "debug", "info", "warn", "error", "fatal".

主体

🌐 Body

使用 body 来发送补充结构化属性的自由格式消息：

🌐 Use body for a free-form message that complements the structured attributes:

Observe.logEvent('cache.evicted', {
  body: 'Cache evicted because disk pressure exceeded the configured threshold.',
  severity: 'warn',
  attributes: { evictedItemCount: 42, freedBytes: 1048576 },
});

命名规范

🌐 Naming conventions

• 使用小写、点分隔的名称：task.completed、onboarding.skipped、report.exported。
• 选择一个词汇并坚持使用。仪表板按确切事件名称分组，因此 report_exported 和 report.exported 将显示为单独的行。
• 在事件名称、属性键和属性值中避免使用个人可识别信息（PII）。你传送的所有内容都可以在仪表板上看到，并且会从设备发送出去。

查看事件

🌐 View events

在仪表板中：打开你的项目并导航到 Observe > Events。默认视图列出了选定时间范围内不同事件名称及其次数。点击事件名称可以查看带有时间戳、属性及所属会话的单个事件。

🌐 In the dashboard: open your project and navigate to Observe > Events. The default view lists distinct event names with their counts in the selected time range. Click an event name to see individual events with their timestamps, attributes, and the session they belong to.

从命令行接口（CLI）:

🌐 From the CLI:

运行 eas observe:events --help 以获取完整的标志列表（时间范围、平台、会话 ID 等）。

🌐 Run eas observe:events --help for the full list of flags (time range, platform, session ID, and more).