编程 WebTracing一款SDK实现前端全链路监控

2024-11-19 05:06:20 +0800 CST views 625

WebTracing：如何使用一款SDK实现前端全链路监控

引言

在产品开发和运营过程中，开发者常常面临难以复现的前端故障，如用户无法下单或页面在某些设备上无法打开等。这种难以定位和重现的问题，让开发和运营团队倍感压力。为了解决这些问题，前端监控工具应运而生。

WebTracing 是一款专为前端项目设计的 JavaScript 埋点 SDK，它提供了完善的前端监控解决方案，通过行为追踪、性能监测、异常捕获、请求记录、资源管理、路由监控、曝光分析和录屏等功能，帮助团队在第一时间获取问题的详细信息。

安装

WebTracing 支持多种安装方式，适用于原生 JavaScript 项目以及 Vue2 和 Vue3 项目。

1. 核心实现包安装

pnpm install @web-tracing/core

2. Vue2 版本安装

pnpm install @web-tracing/vue2

3. Vue3 版本安装

pnpm install @web-tracing/vue3

4. HTML 安装方式

<!DOCTYPE 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>WebTracing Demo</title>
</head>
<script src="https://cdn.jsdelivr.net/npm/@web-tracing/core"></script>
<script>
  webtracing.init({
    appName: 'demo-app',
    debug: true,
    pv: true,
    performance: true,
    error: true,
    event: true,
    cacheMaxLength: 10,
    cacheWatingTime: 1000,
    userUuid: 'demo_userUuid',
    scopeError: true,
  });
</script>
<body></body>
</html>

集成与使用

1. Vue2 集成

import WebTracing from '@web-tracing/vue2';

Vue.use(WebTracing, {
  dsn: '/trackweb', // 数据上报地址
  appName: 'demo-app',
});

2. Vue3 集成

import WebTracing from '@web-tracing/vue3';

app.use(WebTracing, {
  dsn: '/trackweb', // 数据上报地址
  appName: 'demo-app',
});

示例项目

作者提供了一个 Vue2 示例项目，帮助开发者快速上手。
项目地址：https://github.com/M-cheng-web/web-tracing-examples-vue2

pnpm install
pnpm run start

node server.js  # 启动 Node 服务

打开示例项目后，将可以直接观察到前端监控功能的工作效果。

配置项说明

WebTracing 提供了丰富的配置项，支持自定义各类监控功能。

名称	类型	必填	默认值	说明
dsn	string	是	-	数据上报地址
appName	string	是	-	应用名称
appCode	string	否	-	应用代码
appVersion	string	否	-	应用版本号
userUuid	string	否	-	用户 UUID
debug	boolean	否	false	是否开启控制台调试输出
recordScreen	boolean	否	false	是否开启录屏功能
pv	object/boolean	否	false	页面访问量监控配置
performance	object/boolean	否	false	性能监控配置
error	object/boolean	否	false	错误监控配置
event	object/boolean	否	false	用户行为事件监控配置
tracesSampleRate	number	否	1	数据抽样比率（0-1）
cacheMaxLength	number	否	5	数据最大缓存数
cacheWatingTime	number	否	5000	数据最大等待时间（毫秒）
ignoreErrors	Array<string/RegExp>	否	[]	忽略的错误类型
ignoreRequest	Array<string/RegExp>	否	[]	忽略的请求类型
scopeError	boolean	否	false	是否开启错误范围限制
beforePushEventList	function	否	-	添加到行为列表前的钩子函数
beforeSendData	function	否	-	数据发送前的钩子函数
afterSendData	function	否	-	数据发送后的钩子函数

事件采集

WebTracing 支持自动与手动两种采集方式：

自动采集：通过劫持或监听浏览器事件，自动捕捉页面错误、性能数据、点击事件等。
手动采集：开发者可以手动调用 SDK 提供的接口，记录自定义事件。

事件对象结构

属性名称	值	说明
eventId	string	事件 ID
eventType	string	事件类型（如 click）
title	string	事件名称
triggerPageUrl	string	当前页面 URL
params	object	事件参数
elementPath	string	被点击元素的层级路径
triggerTime	number	事件发生时间戳
sendTime	number	事件发送时间戳
x	number	元素与屏幕左侧距离
y	number	元素与屏幕顶部距离

示例：采集点击事件

<div
  class="example-div"
  data-warden-title="示例点击事件"
  data-warden-bigTitle="大标题"
>
  点击我
</div>

点击元素时，生成的事件对象如下：

{
  "eventId": "div",
  "eventType": "click",
  "title": "示例点击事件",
  "triggerPageUrl": "http://localhost",
  "x": 280,
  "y": 20,
  "params": { "bigTitle": "大标题" },
  "elementPath": "div",
  "triggerTime": 1689726300399,
  "sendTime": 1689726301406
}

错误采集

WebTracing 自动监听页面中的错误事件，并通过捕获 error、unhandledrejection 和 console.error 事件，记录页面资源加载错误、JavaScript 执行错误、Promise 调用链错误等。

错误事件对象

属性名称	值	说明
eventId	string	事件 ID（代码错误则为 `code`，HTML 元素错误为元素名）
eventType	string	事件类型（如 `error`）
triggerPageUrl	string	当前页面 URL
errMessage	string	错误信息
errStack	string	完整错误堆栈
line	number	错误发生行号
col	number	错误发生列号
recordscreen	object	错误录屏数据
params	object	错误发生时的参数
sendTime	number	发送时间戳
triggerTime	number	事件发生时间戳

总结

WebTracing 是一款强大的前端埋点 SDK，能够有效地帮助开发者捕捉页面交互、性能数据、错误信息等。通过集成 WebTracing，开发者可以在开发和运维中实时监控用户的操作轨迹和异常情况，快速定位和解决问题。

该 SDK 提供了丰富的功能，如自动和手动事件采集、错误监控、性能监测、路由采集、资源采集等，同时支持 Vue2 和 Vue3 项目的集成。

项目地址：https://github.com/M-cheng-web/web-tracing

如果你正在寻找一款高效的前端监控工具，WebTracing 将是一个非常不错的选择。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>WebTracing Demo</title>
</head>
<body>
    <h1>WebTracing 前端监控 Demo</h1>

    <p id="content">点击以下按钮以触发事件，或引发 JavaScript 错误。</p>

    <button id="click-event-btn" data-warden-title="点击事件">点击触发事件采集</button>
    <button id="trigger-error-btn">点击触发错误</button>

    <!-- 引入 WebTracing SDK -->
    <script src="https://cdn.jsdelivr.net/npm/@web-tracing/core"></script>

    <script>
        // 初始化 WebTracing SDK
        WebTracing.init({
            appName: 'demo-app',
            dsn: '/trackweb',  // 示例的 DSN 地址
            debug: true,
            pv: true,           // 开启页面访问量监控
            performance: true,   // 开启性能监控
            error: true,         // 开启错误捕获
            event: true,         // 开启事件采集
            cacheMaxLength: 10,  // 最大缓存数
            cacheWatingTime: 1000, // 数据上报间隔
            userUuid: 'demo_userUuid',
            scopeError: true,    // 开启错误去重
        });

        // 点击按钮触发 JavaScript 错误
        document.getElementById('trigger-error-btn').addEventListener('click', function() {
            console.log("即将触发 JavaScript 错误");
            // 触发一个未定义变量错误
            nonExistentFunction();  // 这将会抛出一个 ReferenceError
        });

        // 自动采集点击事件
        document.getElementById('click-event-btn').addEventListener('click', function() {
            console.log("点击事件已触发");
            // WebTracing SDK 自动捕获该点击事件，无需手动调用
        });

    </script>
</body>
</html>

复制全文生成海报前端开发监控工具 JavaScript 性能优化错误处理