跳转到主要内容
本文介绍主进程 @flashcatcloud/electron-sdk 的可选配置和公开 API。渲染进程使用 Browser SDK,其通用配置见 Web SDK 高级配置。

初始化参数

main.ts
init() 返回 false 表示配置校验失败。SDK 会在主进程控制台输出具体原因,并且不会开始采集,但不会阻止应用继续启动。

会话采样

Electron SDK 0.4.0 起支持会话采样。sessionSampleRate 决定采集多少比例的会话,默认 100(全部采集):
main.ts
  • 每个会话只在主进程抽样一次,结果同时决定渲染进程:渲染进程事件经桥接由主进程上报,主进程会丢弃未抽中会话的事件。
  • 渲染进程 flashcatRum.init() 中的 sessionSampleRate 对经桥接上报的事件不生效,请只在主进程设置。
  • 应用重启后恢复的会话沿用创建时的抽样结果。
  • 每条 RUM 事件都会带上会话抽样时使用的采样率(_dd.configuration.session_sample_rate),平台据此换算总量。

异常会话补采

开启 sessionOnError 后,采样未抽中的会话不会直接丢弃,而是先在内存中暂存,只有该会话报错时才上报:
main.ts
  • 暂存范围覆盖主进程和渲染进程的事件,最多保留报错前 60 秒的内容(同时受 64 KiB 明细、200 条事件和 50 个 view 的上限约束)。暂存内容只在内存中,不写入磁盘。
  • 会话首次报错后,暂存内容与错误一起在数秒内上报,之后该会话像普通采集的会话一样持续上报。
  • 应用可能即将退出时(主进程未捕获异常、before-quit、will-quit 与进程 exit 事件),已经触发补采的内容会先写入磁盘,下次启动再上传。主进程未捕获异常要被计入,应用自己的 uncaughtException 监听器需在 await init(...) 完成之后注册。
  • 没有报错就结束的会话整体丢弃,退出应用时也不会上传。
  • 只有应用自身的错误会触发补采:被渲染进程 beforeSend 丢弃的错误、SDK 自身上报的错误不计入。原生崩溃同样计入,会在下次启动时随崩溃所在的 view 一起上报。
被补采的会话上报的会话采样率为 0,并在 view 上带 session.sampled_for_error: true 标记,按自身计数、不会按采样率放大。筛选方式见数据查询语法指南中的 session_sampled_for_error。
会话回放不受异常补采控制。 回放由渲染进程直接上传,不经过主进程。开启 sessionReplayDirectUpload 时,被异常补采暂存的会话无论最终是否报错,其回放都会上传。请不要同时使用 sessionOnError 与会话回放。

远程配置

Electron SDK 0.4.0 起,会话采样率、错误会话补充采集与自定义配置项可以在控制台 应用管理 → 远程配置 页签在线调整,无需改代码、重新发版。该功能默认关闭,需要在主进程初始化时开启:
main.ts
控制台 Electron 接入向导中的 允许远程配置 开关打开时,生成的主进程初始化代码会自动带上这一行。 开启后的行为:
  • 配置由主进程在 init() 时与每次新建会话时请求,init() 不会等待请求完成。拿到的配置对下一个新会话生效,进行中的会话不受影响。例外:SDK 0.5.3 起,采样率调到 0 时进行中的会话立即停止采集,从 0 调高时立即恢复采集。
  • 控制台下发的值优先于初始化值;控制台未设置的项、或控制台停用远程配置时,沿用初始化值。
  • 最近一次接收的配置保存在应用的 userData 目录,冷启动后的新会话在网络返回前、甚至离线时也会按它抽样。缓存只对相同的上报地址、应用、env 与 version 生效。
  • 请求失败、超时或响应无法识别时,沿用已生效的配置;SDK 会短暂重试两次。
  • Electron SDK 只读取会话采样率、错误会话补充采集与自定义配置项三项。会话回放由渲染进程的 Browser SDK 自行录制与采样,远程配置不会下发到渲染进程,回放与 Trace 相关的配置项不会在 Electron 应用里出现。
  • 渲染进程无需开启远程配置,主进程会统一处理会话与采样。
配置接口位于上报地址旁的 /api/v2/rum/config 路径:配置 site 时为 https://<site>/api/v2/rum/config;配置 proxy 时,请求同样发往 proxy,目标路径 /api/v2/rum/config 放在 ddforward 参数中。私有化部署请确认转发服务放行了该路径。
自定义配置项通过 getRemoteConfig() 读取,返回一份副本;未开启远程配置、尚未拿到配置或控制台未设置该项时返回 undefined。在服务端返回前,它从本地缓存读取,因此 init() 完成后即可调用:
main.ts
自定义配置项会下发到客户端,任何持有 Client Token 的人都能读到。请勿在其中存放密钥、访问令牌或个人敏感信息。
控制台侧的配置项、发布与生效方式见 应用管理 · 远程配置。

自定义上报地址

默认情况下,普通 RUM 事件由主进程上报到 Flashduty SaaS,无需配置 site 或 proxy。

使用私有化接收域名

如果数据接收端支持 HTTPS,并且接收路径为 /api/v2/rum,请将域名填入 site。不要包含 https:// 或路径:
main.ts
SDK 会向 https://rum.example.internal/api/v2/rum 上报普通 RUM 事件。

使用自定义转发地址

以下场景请使用 proxy:
  • 数据接收端只提供 HTTP
  • 上报路径不是 /api/v2/rum
  • 客户端需要通过统一网关访问数据接收端
main.ts
这里的 proxy 是由您提供的 RUM 转发地址,不是操作系统或 Electron 的网络代理设置。主进程会在请求中附加目标路径信息;转发服务需要保留请求体和 DD-API-KEY 请求头,并将请求发送到 Flashduty 数据接收端。 设置 proxy 后,主进程不再使用 site 生成上报地址。

为会话回放配置私有化地址

普通 RUM 事件通过主进程上报,但会话回放由渲染进程直接上传。因此,主进程的 site 或 proxy 不会自动应用到回放。 私有化部署开启回放时,请在渲染进程配置 Browser SDK 的 proxy:
renderer.ts
同时将该地址加入页面 CSP 的 connect-src。

上报批次与频率

普通 RUM 事件会先写入应用的 userData 目录,再按批次上传。上传成功后,SDK 才会删除对应的批次文件。 接入调试时,可以使用 batchSize: 'SMALL' 和 uploadFrequency: 'FREQUENT' 更快看到数据。正常运行时建议保留默认值。
这套落盘与重试机制只覆盖普通 RUM 事件。会话回放由渲染进程直接上传,不使用主进程的磁盘缓冲。

采集第三方页面

当前窗口加载的页面始终可以使用桥接,无需配置 allowedWebViewHosts。只有当您需要采集 <webview> 或 BrowserView 中加载的第三方页面时,才添加额外 host:
main.ts
匹配规则包含子域名。例如配置 example.com 后,app.example.com 也可以使用桥接。

关联登录用户

用户登录后,在主进程调用 setUser()。主进程事件和通过桥接上报的渲染进程事件都会带上相同的用户身份。
main.ts
开启会话回放时,请在同一套登录和退出流程中同步调用渲染进程的 flashcatRum.setUser() 与 flashcatRum.clearUser(),因为回放分段不会经过主进程。

手动上报错误

主进程中被 try/catch 捕获的异常不会作为未处理异常自动上报。您可以调用 addError() 记录它:
main.ts
手动上报的错误会标记为已处理错误。context 中的属性可用于筛选和定位业务场景。

结束当前会话

用户退出登录或需要重新开始会话时,可以调用 stopSession():
main.ts
当前会话会立即结束。下一次有效的界面输入会创建新会话。

预创建窗口的性能指标

Electron 应用可能先创建隐藏的 BrowserWindow,完成页面加载后再显示。SDK 默认会将这类窗口的 FCP 和 LCP 校正到窗口首次可见的时间,避免把预热等待时间计入页面性能。 如果您希望保留页面原始的 Paint Timing 数值,可以关闭校正:
main.ts
该能力只覆盖 BrowserWindow。WebContentsView 和 <webview> 的指标不会校正。

自定义错误栈路径

SDK 默认把应用目录中的错误栈路径改写为 app:///<相对路径>,让同一份 sourcemap 可以匹配不同机器上的安装路径。大多数项目无需修改。 如果构建产物的目录结构与应用目录不一致,可以通过 normalizeStackPath 自定义映射:
main.ts
返回 undefined 时,SDK 会继续使用默认归一化逻辑。上传方法见 Electron 错误还原。

相关页面

SDK 接入指南

完成主进程与渲染进程接入。

错误还原

上传 JavaScript sourcemap 和原生崩溃符号。

数据收集

查看 SDK 采集的数据类型与上报行为。

问题排查

排查桥接、回放和数据上报问题。