> ## 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` 需 Electron 37 及以上 | `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。

<Note>
  Electron 自带的 `net` 模块只在 **Electron 37 及以上**被追踪。在 Electron 30 到 36 上，`net.request` / `net.fetch` 发出的请求不会产生 resource 事件；`http`、`https` 和全局 `fetch` 不受影响，各支持版本均正常采集。
</Note>

主要字段包括：

* 请求 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.