引言
在产品的开发和运营过程中我们经常会遇到一些问题，如用户反馈说无法对某某商品下单，而另一位负责运营的同事也提到某某广告在手机上打不开。尽管这些问题被多次报告，但我们却难以复现这些故障，这让团队感到十分棘手。如何有效地记录项目中的错误并能够重现这些问题，正是我们需要通过监控平台来解决的关键痛点之一。
WebTracing是一款专为前端项目量身定制的 JavaScript埋点 SDK，它提供了完善的前端监控手段和解决方案。通过集成行为追踪、性能监测、异常捕获、请求记录、资源管理、路由监控、曝光分析以及录屏功能，让数据驱动决策变得更加直观和高效。
作者的目标是减轻前端开发者在监控方面的工作负担。致力于为各种场景提供全面的解决方案，并希望开发者能从项目中获得一些启发。
安装
// 核心实现包 - js pnpm install -tracing/core // vue2版本 pnpm install -tracing/vue2 // vue3版本 pnpm install -tracing/vue3
html 安装
<html lang="en"> <head> <meta charset="UTF-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Document</title> </head> <script src="https://cdn.jsdelivr.net/npm/@web-tracing/core"></script> <script> webtracing.init({ appName: 'cxh', debug: true, pv: true, performance: true, error: true, event: true, cacheMaxLength: 10, cacheWatingTime: 1000, userUuid: 'init_userUuid', scopeError: true, ... }) </script> <body></body> </html>
Vue2 安装
import WebTracing from '@web-tracing/vue2' Vue.use(WebTracing, { dsn: '/trackweb', appName: 'cxh', ... })
Vue3 安装
import WebTracing from '@web-tracing/vue3' app.use(WebTracing, { dsn: '/trackweb', appName: 'cxh', ... })
介绍
这里以作者提供的 Vue2示例项目来演示：
将示例项目 clone到本地安装
pnpm install pnpm run start
开启 node服务
node server.js
打开示例项目首页
image
该项目是一个前端监控解决方案，它使用 Monorepo + pnpm 的构建方式，支持多包联调和发版，并且提供钩子函数、批量如何错误（去重）、抽样发送、过滤等能力。
配置项
| 名称 | 类型 | 必填 | 默认值 | 说明 |
| dsn | string | 是 | - | 上报地址 |
| appName | string | 是 | - | 应用名称 |
| appCode | string | 否 | - | 应用code |
| appVersion | string | 否 | - | 应用版本 |
| userUuid | string | 否 | - | 用户id |
| debug | boolean | 否 | false | 是否开启触发事件时控制台输出 |
| recordScreen | boolean | 否 | false | 是否开启录屏功能 |
| pv | object/boolean | 否 | false | 见下方 pv 解释 |
| performance | object/boolean | 否 | false | 见下方 performance 解释 |
| error | object/boolean | 否 | false | 见下方 error 解释 |
| event | object/boolean | 否 | false | 见下方 event 解释 |
| ext | object | 否 | undefined | ��定义的全局附加参数 |
| tracesSampleRate | number | 否 | 1 | 抽样发送(0-1) |
| cacheMaxLength | number | 否 | 5 | 上报数据最大缓存数 |
| cacheWatingTime | number | 否 | 5000 | 上报数据最大等待时间(ms) |
| ignoreErrors | Array<string/RegExp> | 否 | [] | 错误类型事件过滤 |
| ignoreRequest | Array<string/RegExp> | 否 | [] | 请求类型事件过滤 |
| scopeError | boolean | 否 | false | 开启范围错误 |
| localization | boolean | 否 | false | 是否本地化 |
| sendTypeByXmlBody | boolean | 否 | false | 是否强制指定发送形式为xml，body请求方式 |
| beforePushEventList | function | 否 | - | 添加到行为列表前的 hook |
| beforeSendData | function | 否 | - | 数据上报前的 hook |
| afterSendData | function | 否 | - | 数据上报后的 hook |
事件采集
项目的基本原理包括自动和手动两种采集方式，自动采集通过劫持或监听浏览器事件来获取错误、性能和页面跳转等信息；手动采集则是通过调用 SDK暴露的方法来触发事件采集。
image
事件对象具体属性如下：
| 属性名称 | 值 | 说明 |
| eventId | 详见下面的采集规则 | 事件ID |
| eventType | click | 事件类型 |
| title | 详见下面的采集规则 | 事件名 |
| triggerPageUrl | 当前页面URL | |
| params | 详见下面的采集规则 | 事件参数 |
| elementPath | 例如: div>div>button | 被点击元素的层级 |
| triggerTime | 事件发生时间 | |
| sendTime | 发送时间 | |
| x | 见下方 | 被点击元素与屏幕左边距离 |
| y | 见下方 | 被点击元素与屏幕上边距离 |
插件会根据 DOM元素上一些属性来获取需要采集该元素的事件,以及采集该元素事件时应该传递哪些参数
| 属性名称 | 说明 |
| data-warden-container | 该元素作为采集容器,内部的需要采集的元素上如果没有这些属性会使用容器上的属性作为填充 |
| data-warden-event-id | 元素上标记事件的eventId,会作为传给后台的eventId |
| data-warden-title | 元素上标记事件的title,也可以使用原生的title属性,都会作为传给后台的title |
| data-warden-* | 其他的属性都会被当作参数,例如 data-warden-name="a" 会被收集为 |
事件示例
<div class="box-div" data-warden-title="xxx" data-warden-bigTitle="bigTitle" width="100%" > 示例div </div>
点击事件示例div产生如下对象
{ eventId: 'div', eventType: 'click', title: 'xxx', triggerPageUrl: 'http://localhost:6656/#/event', x: 280, y: 20, params: { bigtitle: "bigTitle" } elementPath: 'div', triggerTime: 1689726300399, sendTime: 1689726301406 }
错误采集
页面错误自动收集,主要原理是 监听/劫持 error unhandledrejection console.error,采集这三类错误
资源加载错误,代码异常(error) promise调用链异常(reject) console.error异常
image
我们主动触发了代码错误，可以在控制台看到的报错，然后被 webTracing事件采集
触发错误事件时生成的对象
| 属性名称 | 值 | 说明 |
| eventId | code / HTML元素上发生异常则为元素名 | 事件ID |
| eventType | error | 事件类型 |
| triggerPageUrl | 当前页面URL | |
| errMessage | 错误信息 | |
| errStack | 完整的错误信息 | |
| line | 错误信息发生在第几行 | |
| col | 错误信息发生在第几列 | |
| recordscreen | 错误录屏数据 | |
| params | 主动方法触发错误收集可以带参数 | |
| sendTime | 发送时间 | |
| triggerTime | 事件发生时间 |
将配置项中的 scopeError 设置为 true 可对错误事件去重。
此外还包括资源监听、路由采集、请求采集、资源采集、曝光采集，由于篇幅原因这里就不一一展开介绍，大家感兴趣可以去官网自行查阅。
image
其他核心介绍
数据流向方面，监听到的事件会经过预处理并生成描述事件信息的对象，然后放入列表中等待统一发送。发送数据时，会根据最大缓存数和延迟发送事件时长的设置来决定何时发送数据，支持多种发送方式，包括 navigator.sendBeacon、image、XML，以及本地化存储和自定义发送方式。
SDK还提供了丰富的导出项，包括钩子函数和可动态更改的内部 options 对象，以方便开发人员自定义功能，如加密传输、发送事件后的提醒、配置项更改和获取基础数据等。
此外，项目还定义了事件类型和事件ID的枚举，以及用于标识用户和细分业务的特殊标识，如 pageId、sessionId、deviceId、appName 和 appCode。
未来计划
作者提出会写一套服务端(nest) + 后台查看监控数据平台(vue)，有以下几点考量
提供服务端能力（目前只是在采集端发力） 可以在线体验此项目 提供更多示例代码给开发们，再次降低这一套代码在公司的推广难度 作者也想站在业务的角度多思考还能从哪些方面此项目还缺失哪些功能
总结
附上github地址：github.com/M-cheng-web…
我们了解到 WebTracing是一款优秀的埋点项目，并提供了多种监控手段，帮助我们对页面交互和用户操作进行分析。
WebTracing提供了原生、Vue2、Vue3等多种安装方式供我们使用。
它的主要功能包括事件采集、错误采集、路由采集、请求采集、资源采集、曝光采集等。
