> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Electron SDK 数据收集

> 了解 Electron RUM SDK 在主进程和渲染进程中采集的数据、关联方式与上报行为

Electron SDK 将主进程和渲染进程的数据关联到同一条会话，帮助你同时分析桌面应用运行状态和页面体验。

## 采集概览

| 数据            | 主进程                                | 渲染进程                    |
| ------------- | ---------------------------------- | ----------------------- |
| 会话            | 负责创建、续期和结束                         | 使用主进程会话 ID              |
| view          | 每个主进程实例维护一个固定 view                 | 记录页面加载和路由切换             |
| 用户操作          | 不采集                                | 点击、输入和自定义 action        |
| 网络请求          | `http`、`https`、`fetch`、`net.fetch` | `fetch`、XHR 和静态资源       |
| JavaScript 错误 | 未捕获异常、Promise 拒绝、手动错误              | 页面错误和手动错误               |
| 原生崩溃          | 主进程崩溃和进程终止                         | 由主进程监听渲染进程终止            |
| 性能指标          | 不产生 Web Vitals                     | LCP、INP、CLS、long task 等 |
| 会话回放          | 不录制                                | 在渲染进程录制并直接上传            |

渲染进程的页面数据由 `@flashcatcloud/browser-rum` 采集，支持范围与 [Web SDK 数据收集](/zh/rum/sdk/web/data-collection)一致。

## 区分主进程和渲染进程

两类事件使用不同的来源字段：

| 事件来源 | `source`   | `container.source` | `view.url`                |
| ---- | ---------- | ------------------ | ------------------------- |
| 主进程  | `electron` | 无                  | `electron://main-process` |
| 渲染进程 | `browser`  | `electron`         | 当前页面 URL                  |

要筛选一个 Electron 应用产生的全部事件，请使用：

```text theme={null}
source:electron OR container.source:electron
```

只使用 `source:electron` 会遗漏渲染进程数据。

<Note>
  如果渲染进程事件没有 `container.source: electron`，说明事件没有经过主进程桥接。请参阅[为什么只有主进程数据](/zh/rum/sdk/electron/faq#为什么只有主进程数据)。
</Note>

在控制台中，错误详情和会话事件详情的属性面板会在「Other」属性组中额外展示一个虚拟的 `process` 属性，取值为「主进程」或「渲染进程」，用于直接区分事件来自哪个进程；会话事件列表中，主进程事件还会带有「主进程」标记。

## 会话

主进程负责 Electron 应用的会话生命周期：

| 规则    | 行为                         |
| ----- | -------------------------- |
| 无操作超时 | 连续 15 分钟没有有效界面输入后结束会话      |
| 最大时长  | 单个会话最长 4 小时                |
| 活跃信号  | 鼠标按下、滚轮、按键等 Electron 输入事件  |
| 应用重启  | 未过期的会话可以继续使用               |
| 会话续期  | 会话结束后，下一次有效输入会创建新会话和新 view |

纯主进程后台任务不会延长会话，也不会自动创建新会话。

## 用户身份

主进程 SDK 会为应用生成稳定的匿名设备标识。调用 `setUser()` 后，主进程事件和通过桥接上报的渲染进程事件都会带上登录用户信息。

| 状态                                | 后续事件中的用户信息        |
| --------------------------------- | ----------------- |
| 未调用 `setUser()`                   | 只包含匿名设备标识         |
| 调用 `setUser({ id, name, email })` | 同时包含匿名设备标识和登录用户信息 |
| 调用 `clearUser()`                  | 移除登录用户信息，保留匿名设备标识 |

会话回放由渲染进程直接上传。开启回放时，请在渲染进程同步调用 `flashcatRum.setUser()` 和 `flashcatRum.clearUser()`。

API 用法见[关联登录用户](/zh/rum/sdk/electron/advanced-config#关联登录用户)。

## 主进程 view

主进程没有页面路由。SDK 为每个主进程实例维护一个固定 view，并将主进程的错误和网络请求关联到该 view。

该 view 的主要标识为：

| 字段                | 值或含义                      |
| ----------------- | ------------------------- |
| `view.url`        | `electron://main-process` |
| `view.name`       | `main process`            |
| `view.time_spent` | 主进程 view 已持续的时间           |
| `view.is_active`  | 当前会话是否仍然活跃                |

渲染进程仍按 Web SDK 规则创建自己的页面 view。主进程 view 不包含渲染进程页面的 Web Vitals 和用户操作计数。

## 错误与崩溃

### JavaScript 错误

| 来源                 | 采集方式                      |
| ------------------ | ------------------------- |
| 主进程未捕获异常           | 自动采集 `uncaughtException`  |
| 主进程未处理 Promise 拒绝  | 自动采集 `unhandledRejection` |
| 主进程已捕获异常           | 调用 `addError()` 手动上报      |
| 渲染进程 JavaScript 错误 | 由 Browser SDK 自动采集        |

主进程和渲染进程的错误栈都会归一化为稳定路径，可以使用 sourcemap 还原。操作方法见 [Electron 错误还原](/zh/rum/sdk/electron/error-symbolication#还原-javascript-错误)。

### 原生崩溃

Electron 发生原生崩溃时，会在本地生成 minidump。进程已经终止，无法立即上报，因此 SDK 会在应用下一次启动时读取并上报崩溃事件。

崩溃事件包含：

* 崩溃类型和进程信息
* 崩溃线程及其他线程的调用栈
* 加载的原生模块
* 操作系统和 CPU 架构

未上传符号文件时，原生调用栈会显示模块名和地址。上传匹配的 Breakpad 符号后，Flashduty 可以还原函数名、文件名和行号。

### 进程终止

SDK 还会监听渲染进程和 Electron 子进程终止，包括被系统结束、启动失败或沙箱终止等不会产生 minidump 的情况。

这类事件会记录进程类型、退出原因、退出码和页面 URL，但没有调用栈。

## 主进程网络请求

SDK 自动采集主进程发起的 `http`、`https`、`fetch` 和 `net.fetch` 请求，并将它们记录为 RUM resource。

主要字段包括：

* 请求 URL 和方法
* HTTP 状态码
* 请求耗时
* Trace ID 和 Span ID

主进程 resource 的 `resource.type` 为 `native`，可以与渲染进程的 `fetch` 和 `xhr` 区分。

当前不提供完整 APM。只有 HTTP span 会转换为 RUM resource；IPC 和子进程命令 span 不会上报。

## 上报与重试

普通 RUM 事件和会话回放使用不同的上报方式：

| 数据            | 上报进程      | 缓冲与重试                         |
| ------------- | --------- | ----------------------------- |
| 主进程事件         | 主进程       | 写入磁盘，上传成功后删除；应用重启后可以继续发送      |
| 渲染进程普通 RUM 事件 | 通过桥接交给主进程 | 与主进程事件使用相同的磁盘缓冲               |
| 会话回放分段        | 渲染进程直接上传  | 使用 Browser SDK 的内存重试，不写入主进程磁盘 |

因此，主进程的 `site`、`proxy`、`batchSize` 和 `uploadFrequency` 不会改变会话回放的上传行为。私有化回放地址需要在渲染进程单独配置。

## 相关页面

<CardGroup cols={2}>
  <Card title="SDK 接入指南" icon="plug" href="/zh/rum/sdk/electron/sdk-integration">
    完成主进程与渲染进程接入。
  </Card>

  <Card title="高级配置" icon="sliders" href="/zh/rum/sdk/electron/advanced-config">
    配置上报地址、用户身份和公开 API。
  </Card>

  <Card title="错误还原" icon="bug" href="/zh/rum/sdk/electron/error-symbolication">
    还原 JavaScript 和原生崩溃调用栈。
  </Card>

  <Card title="问题排查" icon="circle-question" href="/zh/rum/sdk/electron/faq">
    排查数据缺失、桥接和回放问题。
  </Card>
</CardGroup>