帮你快速理解、总结文档立即下载
文档中心>腾讯云可观测平台>用户体验监控>接入指南>Electron SDK 接入指引>数据上报验证

数据上报验证

最近更新时间：2026-09-30 17:29:02
本文档已由 AI 辅助审校
我的收藏

本页目录：

本文介绍接入用户体验监控 Electron SDK 后，如何验证各监控能力的数据上报是否成功。

前提条件

已完成 main 与 renderer 两端的集成与初始化，且 main 初始化早于任何 BrowserWindow 创建。
验证期间建议在 renderer 侧开启 debug: true，便于观察初始化摘要与运行日志。
建议在主进程与渲染进程分别打开 DevTools / 日志，便于对照两端行为。

步骤1：检查上报请求

初始化后，main 进程应发出三类请求，HTTP 2xx / 204 均视为成功：
端点
内容
POST {url}/api/v1/config
远程配置，body 含 project_key
POST {url}/api/v1/collect/events
标准事件（错误 / 性能 / 接口测速 / 自定义事件等）
POST {url}/api/v1/collect/replay
会话回放分段
注意：
启动队列有容量与超时限制，失败不会降级为浏览器直传。若 main 未初始化或 preload 未注入，renderer 会直接拒绝初始化，而不是退化为直连上报。

理解上报链路

Electron SDK 的请求不由 renderer 直接发出，而是经 main 代理转发：
renderer → SDK auto preload → typed IPC → main → Electron net → Collector
因此：
窗口 Network 面板中看不到采集请求，需在 main 侧抓包（或看 SDK 诊断日志）。
renderer 发送的 config / events / replay 请求都由 main 解析真实 endpoint 后发出。
同步请求返回 Collector 响应；页面关闭时的 accepted handoff 表示 main 已接管责任，不等于 Collector 成功。

步骤2：验证各监控能力

渲染进程错误

// renderer
tdem.captureException(new Error('tdem verify error'));
tdem.captureMessage('tdem verify message', { level: 'warn' });
也可直接抛错，验证全局捕获：
setTimeout(() => { throw new Error('tdem verify uncaught'); }, 0);

主进程未捕获异常

captureUncaughtException 与 captureUnhandledRejection 默认开启，在 main 侧主动触发即可验证：
// main
Promise.reject(new Error('tdem verify rejection'));

主进程 Warning 事件

Node 运行时警告（如 MaxListenersExceededWarning）由 SDK 自动捕获，无需任何配置，也无法关闭：
// main
process.emitWarning('tdem verify warning');
落库形态：event_type=log、data.log_level=warn、data.event_properties.source=warning，警告文本在 data.event_properties.message。
与 tdem.captureMessage('...', { level: 'warn' }) 的区别：后者是业务主动上报，event_properties 中没有 source=warning，可据此区分二者。

主进程网络与 SSE

main 的 api 默认开启。在 main 中发起一次出站请求即可看到接口测速数据：
// main
import { net } from 'electron';
await net.fetch('https://example.com/api/ping');
覆盖 electron.net.request / net.fetch、Node http / https，以及 undici / 全局 fetch。识别 text/event-stream 后只出 sse_call。

壳层进程健康信号

processSignal 默认开启。事件为 event_type=process_signal，event_name 共 4 种，触发方式与附带字段各不相同：
子窗口渲染进程异常退出 → render_process_gone，带 window_id / web_contents_id / process_role（renderer）/ exit_reason / exit_code。
让主进程短暂阻塞 → 阻塞时 unresponsive、恢复时 responsive；二者均带 window_id / web_contents_id，responsive 额外带 measurements.duration（从阻塞起的毫秒数）。
非窗口子进程（GPU / Utility 等）退出 → child_process_gone，不带 window_id / web_contents_id，改带 process_role（gpu / utility）/ service_name / exit_reason / exit_code / repeat_count。
child_process_gone 的 exit_reason 为 crashed / oom / killed 时，30 秒内的重复退出会合并计数（repeat_count）；所有 process_signal 事件的 event_properties.process_type 恒为 main。
注意：
render_process_gone 与 child_process_gone 在 exit_reason 为 clean-exit 或 exit_code 为 0 时不上报。因此正常关闭子窗口验证不出这类信号，需制造非零退出的异常场景（如让 renderer 进程崩溃、强杀 GPU / Utility 子进程）。unresponsive / responsive 无此限制，仅跳过 devtools:// 窗口。

应用内存 / CPU 指标

需显式开启 appMetrics：
init({
  id: 'project-id',
  url: 'https://dem.rumt-zh.com',
  appMetrics: { enabled: true, intervalMs: 60000 },
});
开启后按周期上报 event_type=app_metrics。
注意：
Electron renderer 会强制关闭 Web SDK 的 memoryMonitor，页面级 JS 堆不再上报，内存数据请以 appMetrics 为准。

文件系统 IO

需显式开启 filesystemIo，之后在 main 中做一次文件读写即可：
import fs from 'node:fs';
fs.writeFileSync('/tmp/tdem-verify.txt', 'hello');
上报为 event_type=file_io。SDK 自身产物目录（preload、tdem-memory-dumps、native crash 产物）不会上报。

手动内存 Dump

const result = await tdem.dumpMemory();
console.log(result.ok, result.filePath);
文件只留本地、不上报附件；禁用态 client 返回 { ok: false }，不写文件、不抛异常。

会话回放

1. 冷启动 → 打开页 A → 点击 → 跳到页 B → 切后台几秒再回。
2. 进入 用户体验监控控制台，在左侧菜单栏中选择用户行为 > 会话分析，按平台筛到该会话，页面跳转应在同一会话内。
3. 在会话详情或会话列表中单击回放，打开会话回放，事件时间轴应与画面对齐。
注意：
远程配置关闭采集，或从未拉到配置且无缓存时，SDK 不会上报回放。这是默认保守策略，不是接入失败。

Node 子进程注入

需显式开启 nodeInjection: true（且必须在创建窗口与缓存 spawn 之前），并保证 tdem-node-sdk 的 preload / inject 入口在运行时可解析（即打包时留在 asar 外）。之后在 main 中拉起一个 Node 子进程：
import { spawn } from 'node:child_process';
spawn('node', ['-e', 'setTimeout(()=>{}, 100)']);
被注入的子孙进程会用 Node http / https 直报 {url}/api/v1/collect/events，不走 Electron IPC。若打包时未把 tdem-node-sdk 留在 asar 外，注入会失败降级（原进程仍正常启动，但不产生数据）。
子进程侧的网络与文件 IO 采集继承 main 的开关：api 关闭则子进程无接口测速，filesystemIo 关闭则子进程无 file_io。因此只开 nodeInjection 只解决「把子进程纳入同一会话」，采集范围仍由这两个开关决定。
原生崩溃（nativeCrash）默认开启，验证方式与配置说明见 SDK 初始化 的 nativeCrash；产物上报为 event_type=crash / crash_type=native_crash，附件处理的降级行为见 API 说明 的静默降级清单。

步骤3：主动上报(可选)

除自动采集外，SDK 提供下列主动上报接口，main 与 renderer 两侧均可调用。
// main 或 renderer 均可
tdem.track('checkout_completed', { tags: { step: 'pay' } });
tdem.measure('bootstrap', 320, { tags: { stage: 'cold' } });
track(name, { tags, properties })：上报业务自定义事件，name 须为非空字符串；tags / properties 分别落到 data.tags 与 data.event_properties，值会被转为字符串，单个值最长1024字符。
measure(name, duration, { tags, properties })：直接上报耗时（毫秒）；也可用 startMeasure(name) / endMeasure(name) 成对计时。
验证方式：调用后在 main 侧抓包，确认请求体中出现 event_type = custom，且 data.event_name 为传入的事件名。

步骤4：检查数据上报

Electron 的采集请求由 main 进程发出，窗口 Network 面板中看不到，需在 main 侧抓包观察，或在 renderer 侧开启 debug: true 后查看 SDK 诊断日志。也可在控制台查看对应监控能力的数据，上报端点清单参见 检查上报请求。

中国站