可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载本篇指南基于 highlight.io开源全栈监控平台官方文档中的 Electron 快速入门页讲解如何在 Electron 桌面应用中接入 highlight.run SDK完成会话回放Session Replay、错误监控、日志与链路追踪四大产品线的接入并重点剖析 Electron 特有的configureElectronHighlight窗口事件机制——即如何利用主进程的focus/blur/close事件控制录制启停从而降低对 Electron 用户性能与电量的影响。读完后你可以按步骤把一个 Electron 应用完整接入 highlight.io并理解其底层 IPC 通信原理。文档入口与快速入门内容的渲染机制官方 Electron 快速入门文档位于 7_electron.md其正文仅有一个组件调用QuickStart content{quickStartContent[client][js][electron]}/也就是说文档页的实际内容由仓库内的前端组件驱动。在 QuickstartContent.tsx 中quickStartContent是一个按产品线分层的步骤内容注册表其中client.js分支通过QuickStartType.Electron枚举键指向 electron.tsx 中定义的ElectronContext。该上下文声明了 Electron 接入所覆盖的产品能力export const ElectronContext: QuickStartContent { title: Electron, subtitle: Learn how to set up highlight.io with your Electron application., logoKey: electron, products: [Sessions, Errors, Logs, Traces], entries: [ packageInstallSnippet, // 1. 安装 SDK initializeSnippet, // 2. 初始化 { /* 3. 接入 Electron 窗口事件 */ }, identifySnippet, // 4. 用户标识 verifySnippet, // 5. 验证安装 configureSourcemapsCI(), // 6. CI 上传 sourcemap可选 setupBackendSnippet, // 7. 后端接入 ], }从源码结构看ElectronContext共 7 个步骤定义于 electron.tsx其中大部分复用 shared-snippets.tsx 中与 Web 前端通用的步骤片段仅第 3 步是 Electron 专属内容。下文按该骨架逐步展开。第一步安装 highlight.run SDK在 Electron 项目的渲染进程所在目录中安装 npm 包highlight.run。官方文档提供了三种包管理器的安装方式# with yarn yarn add highlight.run # with pnpm pnpm add highlight.run # with npm npm install highlight.run对于需要窗口事件追踪能力的 Electron 项目集成文档 electron-integration.md 明确要求请使用highlight.run4.3.4 及以上版本否则configureElectronHighlight的窗口事件转发行为不被保证。第二步在渲染进程中初始化 SDK从 Highlight 控制台的项目设置页获取你的 Project ID作为H.init()的第一个参数传入。官方快速入门推荐的初始化代码如下来自 shared-snippets.tsx 的initializeSnippet... import { H } from highlight.run; H.init(YOUR_PROJECT_ID, { serviceName: frontend-app, tracingOrigins: true, networkRecording: { enabled: true, recordHeadersAndBody: true, urlBlocklist: [ // insert full or partial urls that you dont want to record here // Out of the box, Highlight will not record these URLs (they can be safely removed): https://www.googleapis.com/identitytoolkit, https://securetoken.googleapis.com, ], }, }); ... // rendering code.各配置项的含义与官方建议参数说明serviceName前端服务名用于前后端映射时将前端会话与后端日志/错误关联到同一应用。tracingOrigins官方建议开启使 SDK 向网络请求注入追踪头从而把前端错误与后端错误配对Fullstack Mapping。networkRecording.enabled开启网络请求录制回放时可看到 XHR/fetch 的请求与响应。networkRecording.recordHeadersAndBody是否录制请求/响应头与 body涉及隐私时需谨慎评估。networkRecording.urlBlocklist全量或部分 URL 匹配黑名单。SDK 默认已屏蔽两条 Google 身份认证相关 URLhttps://www.googleapis.com/identitytoolkit与https://securetoken.googleapis.com文档注释标明这两项“可以安全删除”。值得注意的是electron.tsx 中还保留了一份 Electron 专属的初始化片段electronInitCodeSnippet它在通用配置之外额外演示了environment如production与version如commit:abcdefg12345两个选项。从源码结构看当前快速入门页面实际渲染的是通用initializeSnippet而该专属片段更多是展示在桌面端发布场景下为会话标注环境与应用版本的用法。第三步接入 Electron 窗口事件Electron 专属这是 Electron 快速入门中区别于普通 Web 前端的核心步骤。官方步骤说明为该函数会把主进程的focus和blur事件转发到渲染进程使 highlight 的录制逻辑能够感知它们。当应用不可见时暂停 Highlight 录制当应用重新获得可见性时恢复会话以尽量降低 Highlight 对 Electron 用户的性能与电量影响。在主进程中创建BrowserWindow后调用configureElectronHighlight即可const mainWindow new BrowserWindow(...) configureElectronHighlight(mainWindow)configureElectronHighlight是 SDK 的公开导出。在 index.tsx 的导出列表中可以看到该函数第 645 行附近其实现位于 electron.ts/* Given a BrowserWindow, sets up event listeners for Highlight. */ export default function configureElectronHighlight(window: any) { if (window.on window.webContents?.send) { window.on(focus, () { window.webContents.send(highlight.run, { visible: true }) }) window.on(blur, () { window.webContents.send(highlight.run, { visible: false }) }) window.on(close, () { window.webContents.send(highlight.run, { visible: false }) }) } }从源码实现看该函数做了三件事防御性校验只有传入对象同时具备on方法与webContents.send能力即确实是 Electron 的BrowserWindow时才注册监听器避免误传普通 DOM 对象时抛错焦点事件转发监听focus与blur通过webContents.send(highlight.run, { visible: ... })向渲染进程推送可见性状态关闭事件处理比文档描述更进一步源码还监听了close事件并在窗口关闭时发送visible: false确保会话在应用关闭时正常收尾。渲染进程一侧的接收逻辑位于 client/index.tsx// only do this once, since we want to keep the visibility listener attached even when recoding is stopped if (!this._hasPreviouslyInitialized) { // setup electron main thread window visiblity events listener if (window.electron?.ipcRenderer) { window.electron.ipcRenderer.on( highlight.run, ({ visible }: { visible: boolean }) { this._visibilityHandler(!visible) }, ) this.logger.log(Set up Electron highlight.run events.) } else { // Send the payload every time the page is no longer visible - this includes when the tab is closed, as well // as when switching tabs or apps on mobile. Non-blocking. PageVisibilityListener((isTabHidden) this._visibilityHandler(isTabHidden), ) this.logger.log(Set up document visibility listener.) } this._hasPreviouslyInitialized true }这段代码揭示了 SDK 的环境自适应设计初始化时 SDK 会检测window.electron?.ipcRenderer由 Electron preload 暴露。若检测到 Electron IPC 通道则以主进程转发来的highlight.run消息作为可见性来源调用统一的_visibilityHandler参数取反visible: true表示“未隐藏”否则回退到浏览器的PageVisibilityListener监听页面隐藏切标签页、移动端切应用、关页等场景。两条路径最终汇聚到同一个可见性处理函数且该监听器只注册一次_hasPreviouslyInitialized标记保证即使在录制停止状态下可见性监听依然保持挂载。也就是说完整的数据流是主进程BrowserWindow事件 →webContents.send(highlight.run, { visible })→ 渲染进程ipcRenderer.on(highlight.run)→_visibilityHandler→ 暂停/恢复会话录制。这正是 Electron 集成文档 electron-integration.md 中“under the hood”一节描述的原理。第四步标识用户Identify在用户认证流程完成后调用H.identify将用户身份与后续会话关联使其可在控制台按用户维度检索。官方示例shared-snippets.tsximport { H } from highlight.run; function Login(username: string, password: string) { // login logic here... // pass the user details from your auth provider to the H.identify call H.identify(jayhighlight.io, { id: very-secure-id, phone: 867-5309, bestFriend: jenny }); }官方建议在任何异步、客户端上下文中、于认证完成后调用。第一个参数会通过identifier属性可检索第二个对象的每个键值对都可按键名检索例如可按phone搜索用户的会话。第五步验证安装打开 Highlight 控制台的会话Sessions页面查看是否有新会话出现。官方提示记得移除Status is Completed过滤器以查看进行中的会话若始终看不到数据可联系 Highlight 社区协助调试。第六步在 CI 中配置 Sourcemap可选为了让生产环境的 JavaScript 错误拥有还原后的、可读的堆栈enhanced stacktraces官方建议在 CI 流水线中上传 sourcemap。如果你的构建产物已随包公开了 sourcemappublic sourcemaps可以跳过此步。官方示例命令shared-snippets.tsx 的configureSourcemapsCI# Upload sourcemaps to Highlight ... npx --yes highlight-run/sourcemap-uploader upload --apiKey ${YOUR_ORG_API_KEY} --path ./build ...其中--apiKey传入组织级 API Key建议经 CI 密钥变量注入如${YOUR_ORG_API_KEY}--path指向构建产物目录。上传工具本身也在本仓库中维护见 sourcemap-uploader/ 目录含构建配置 tsup.config.ts 等。第七步接入后端完成全栈映射前端接入完成后的下一步是接入后端 SDK将日志与错误关联到前端会话。快速入门页的最后一步setupBackendSnippet指向后端的接入文档与 Fullstack Mapping 说明仓库内对应的说明文档为 frontend-backend-mapping.md其中解释了tracingOrigins注入的追踪头如何把一次用户操作串联为“前端会话 后端日志/错误”的完整视图。后端各语言/框架的具体接入方式可在 getting-started 后端章节 中选择对应的 SDK。小结与相关路径索引Electron 场景下接入 highlight.io 的完整链路是安装highlight.run→H.init初始化并开启networkRecording与tracingOrigins→ 主进程调用configureElectronHighlight(mainWindow)转发窗口可见性事件 →H.identify标识用户 → 控制台验证会话 → 可选CI 上传 sourcemap → 接入后端完成全栈映射。与本主题相关的仓库路径资源路径快速入门文档本页主题docs-content/getting-started/3_browser/7_electron.mdElectron 集成说明文档docs-content/general/7_integrations/electron-integration.md快速入门内容定义7 步骨架highlight.io/components/QuickstartContent/frontend/electron.tsx通用步骤片段安装/初始化/identify/验证/sourcemap/后端highlight.io/components/QuickstartContent/frontend/shared-snippets.tsx主进程事件转发实现sdk/highlight-run/src/environments/electron.ts渲染进程 IPC 可见性监听sdk/highlight-run/src/client/index.tsxSDK 公开导出含 configureElectronHighlightsdk/highlight-run/src/index.tsxsourcemap 上传工具sourcemap-uploader/适用前提SDK 版本需为highlight.run4.3.4 及以上configureElectronHighlight需要项目使用 Electron 的 preload 机制将ipcRenderer暴露为window.electron渲染进程侧的 IPC 监听才会生效否则 SDK 自动回退到标准浏览器可见性监听。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐highlight.io 前端接入实战React.js 应用的会话回放、错误监控与完整配置指南highlight.io 前端接入实战React.js 应用的会话回放、错误监控与完整配置指南 本篇指南基于 highlight.io 官方文档中的 Reac可观测性后端highlight.io 在 Gatsby.js 中的完整接入指南会话回放、错误监控与全栈日志highlight.io 在 Gatsby.js 中的完整接入指南会话回放、错误监控与全栈日志 本文基于 highlight.io 官方文档 Gatsby.j可观测性后端用 Highlight 接入 Next.jshighlight-run/next 的会话回放、错误监控与分布式追踪完整实践用 Highlight 接入 Next.jshighlight run/next 的会话回放、错误监控与分布式追踪完整实践 本文基于 Highlight 仓可观测性后端上一篇终极指南如何用开源工具Cap打造专业级屏幕录制体验下一篇CefSharp自定义协议实现cefsharp://方案详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考