怎么做一款轻量级前端监控sdk

producer 即生产者，负责接收客户端上报的日志，并推入消息队列。

作为一个SEO运营专家，我的职责之一是处理来自消息队列的消息，以及从数据库中检索相应信息并进行处理。这包括消费者从消息队列中读取消息，并将其拼接成日志信息，最后写入数据库。另外，我还需要处理监控后台发来的请求，在数据库中寻找相应的信息，进行处理后再返回给监控后台。

Core

作为SDK的核心抽象类，Core 主要完成一些基础的初始化工作，并提供与平台无关的代码，同时规范了各个客户端的属性和方法。

Core 主要做了以下事情

1. 完成 SDK 配置项的初始化与绑定
2. 实现引用插件的功能
3. 使用发布订阅模式完成日志的捕获与上报
4. 统一控制台的输出方法
5. 提供面包屑功能，给各个插件使用（暂不支持手动增加面包屑，可以使用 @heimdallr-sdk/customer 上报）
6. 规范初始化应用方法，各客户端所需的应用信息不一致，因此这里只提供抽象方法，需要各个客户端自己实现
7. 规范数据转换方法，与上一条一样，这里也只提供抽象方法，需要客户端自行实现
8. 规范数据上报方法，因为不同客户端支持的网络请求方式不一致，如：浏览器端有多种网络请求 API 可用，而 wx 只能使用 wx.request 方法发起请求，因此这里也只提供抽象方法，得客户端自己实现

Client

Client 即客户端，也就是在不同平台使用的 sdk 基座

Browser

Browser 即浏览器端的监控基座，以浏览器为载体的应用都可以使用该基座

继承自 Core 抽象类，实现了 Core 中的抽象方法：

• 初始化应用
• 数据转换
• 数据上报：支持 sendBeacon、图片上报、get 三种上报方式，默认使用 sendBeacon

Browser 基座同时内置了错误监控 sdk，以内置插件的方式集成在基座中，可以监听到以下三种类型的错误：

• 代码错误（支持 sourcemap，需上传 sourcemap 文件）
• 资源加载错误
• 代码中未捕获的错误

此外还监听了页面的加载与卸载，作为一次访问会话上报，以页面加载作为会话开始、页面卸载视为会话结束

Browser 基座支持 CDN 与 NPM 两种引入方式，这也就意味着绝大多数技术栈的前端应用都可以使用该基座

CDN 方式引入如下

<script>
    window.__HEIMDALLR_OPTIONS__ = {
        dsn: {
            host: 'localhost:8888',
            init: '/project/init',
            upload: '/log/upload'
        },
        app: {
            name: 'playgroundAPP',
            leader: 'test',
            desc: 'test proj'
        },
        userIdentify: {
            name: '__state__.a.0.user.id', // window.__state__ = { a: [{ user: { id:'123' } }] }
            position: 'global'
        }
    };
</script>
<script async src="/browser-dist/browser.iife.js"></script>

NPM 引入

import heimdallr from "@heimdallr-sdk/browser";
heimdallr({
    dsn: {
        host: 'localhost:8888',
        init: '/project/init',
        upload: '/log/upload'
    },
    app: {
        name: 'playgroundAPP',
        leader: 'test',
        desc: 'test proj'
    },
    userIdentify: {
        name: '__state__.a.0.user.id', // window.__state__ = { a: [{ user: { id:'123' } }] }
        position: 'global'
    }
});

Node

Node 即 nodejs 服务端的监控基座

同样继承自 Core 抽象类，实现了应用初始化、上报数据最后的转换、数据上报三个方法

这里的上报方式使用了第三方库来实现，node-fetch

Node 基座同样默认集成了错误监听的能力，监听了 uncaughtException 的错误并上报

Node 服务端一般不以“会话”为监控维度，更关注接口与服务器性能，因此没有 Browser 中的“会话”的概念

该基座可以通过 NPM 方式引入，与 Browser 引入方式类似

Wx

Wx 即微信小程序的监控基座

老规矩，继承自 Core 抽象类，实现初始化、转换、上报三个方法

同样的，Wx 基座也集成了基础的错误监控，本质上就是重写了 APP.onError，捕获到错误并上报

与 Browser （浏览器）最大的不同之处在于如何监听完整的会话。我们人为规定，以 onShow（显示）作为会话的开始，以 onHide（隐藏）作为会话的结束。同时，我们提供了两种方式来监听会话。

1. 提供 trace 函数，在每个页面的 onShow 与 onHide 方法内手动添加埋点
2. 重写小程序的 Page 方法，返回 heimdallrPage 方法，在页面中直接使用 heimdallrPage 替代 Page 方法

通过 NPM 方式引入，引入方式参考微信官方文档啦

Plugins

当前仅有 Browser 基座与 Wx 基座的插件

篇幅有限，只能罗列一下了，没法一个个单独讲

For Browser

Browser 基座的所有插件均提供 CDN 与 NPM 两种引入方式

• @heimdallr-sdk/console
• 监听浏览器控制台的输出并上报，debug 为 false 时，控制台所有信息都不会打印

• @heimdallr-sdk/customer
• 自动读取存储在 cookie、localStorage、sessionStorage、window 上的数据并上报，同时也可以通过调用 window.HEIMDALLR_REPORT(type: string, data: any) 手动上报
• @heimdallr-sdk/dom
• 监听页面的点击事件并上报

• @heimdallr-sdk/fetch
• 监听页面发起的 fetch 请求，reportResponds 为 true 时，将连同接口返回值一同上报
• @heimdallr-sdk/xhr
• 监听页面发起的 XMLHttpRequest 请求，reportResponds 为 true 时，将连同接口返回值一同上报

• @heimdallr-sdk/hash
• 监听页面路由的 hash 变化，记录来源与跳转地址并上报
• @heimdallr-sdk/history
• 监听页面路由的变化，包括手动点击浏览器按钮的跳转，自动记录来源与跳转地址并上报

• @heimdallr-sdk/performance
• 页面性能监控，可以得到下列性能指标
• dnsSearch: DNS 解析耗时
• tcpConnect: TCP 连接耗时
• sslConnect: SSL 安全连接耗时
• request: TTFB 网络请求耗时
• response: 数据传输耗时
• parseDomTree: DOM 解析耗时
• resource: 资源加载耗时
• domReady: DOM Ready
• httpHead: http 头部大小
• interactive: 首次可交互时间
• complete: 页面完全加载
• redirect: 重定向次数
• redirectTime: 重定向耗时
• duration
• fp: 渲染出第一个像素点，白屏时间
• fcp: 渲染出第一个内容，首屏结束时间
• fmp: 有意义内容渲染时间
• fps: 刷新率
• lcp: 最大内容渲染时间，2.5s 内
• fid: 交互性能，应小于 100ms
• cls: 视觉稳定性，应小于 0.1
• resource: 页面资源加载耗时
• @heimdallr-sdk/record
• 录制当前会话所有操作并上报

• @heimdallr-sdk/page_crash
• 监听页面崩溃，需配合 @heimdallr-sdk/page-crash-worker 使用，不走基座的上报与数据转换，在 page-crash-worker 文件中使用 get 方法上报崩溃数据。从命名就能看出来，核心原理就是使用 Worker (狗头)
• @heimdallr-sdk/vue
• 捕获 vue 抛出的错误并上报，支持 sourcemap（需上传 sourcemap 文件）

For Wx

虽然小程序基座的插件数量有限，但实际上也没有太大的需要。毕竟小程序本身已经具备了一套完整的性能和错误监控机制。因此，我只选择了一些常用但小程序没有提供的监控插件来使用。

• @heimdallr-sdk/wx-dom
• 监听小程序的点击事件，记录触发的函数名以及附带信息并上报

• @heimdallr-sdk/wx-request
• 监听小程序发起的请求，包括 request、downloadFile、uploadFile，同样可通过 reportResponds 配置决定是否上报接口返回结果
• @heimdallr-sdk/wx-route
• 捕获小程序的路由跳转，记录来源、跳转地址与跳转状态（成功与否）并上报

自定义插件

插件本质上就是一个个 Plugin 类型对象

基础的 Plugin 类型如下：

export interface BasePluginType {
  name: string;
  monitor: (notify: (collectedData: any) => void) => void;
  transform?: (collectedData: any) => ReportDataType<any>;
}

• name: 当前插件名称（不能写中文）
• monitor: 插件逻辑的具体实现放在这个函数体中
• notify 函数负责将数据上报，collectedData 还不是最终上报到服务器的数据，会在基座的 transform 内包装一下再上报

• transform: 可选配置，即接收 notify 中上报的数据，在这里转换一下；最终也是会到基座的 transform 方法内做最后的“包装”

所以，只需创建并返回一个符合 BasePluginType 的对象，就能将其作为插件接入 heimdallr-sdk 的基座中。

Server

服务端作为私有子包，不发布，可通过 @heimdallr-sdk/cli 脚手架快速部署

服务端使用 express 作为 Node 服务端框架，ORM 库使用 Prisma，数据库则使用的是 MySQL

正如前面说的，这里我提供了两种服务端，我把它称为“单服务”与“多服务”

“单服务”

"单服务"使用传统的 MVC 架构，但默认的 View 不直接调用 API，而是作为接口文档，方便浏览。同时也可以通过修改路由将其指向不同的页面。

实现的主要功能如下：

• 项目的初始化（其实就是应用信息入库）
• 会话的创建与写入
• 日志信息的接收与写入（同时支持 post 与 get）
• 应用列表
• 会话列表
• 日志列表
• 接收 sourcemap 文件
• 解析 sourcemap

“单服务”既负责接收，也负责提供接口给监控后台（Manager）使用，能直接读写数据库

“多服务”

“多服务”将服务端一分为二，分为“消费服务”与“生产服务”

使用 RabbitMQ 完成对流量的削峰填谷

Producer

“生产服务” 也就是图中的 producer，即生产者，面向监控 SDK，从 SDK 接收上报数据

主要功能如下：

• 接收应用信息，并推入应用队列
• 接收日志信息（会话就是两条一前一后的日志），并推入日志队列
• 接收 sourcemap 文件

Consumer

“消费服务” 也就是上图的 consumer，也即消费者，面向监控后台，提供读取接口给监控后台调用。

主要功能如下：

• 从应用队列中提取应用消息，写入数据库
• 从日志队列中提取日志消息，完成日志消息的“组装”，再写入数据库
• 解析 sourcemap 文件
• 提供统计数据接口
• 提供应用/项目列表接口
• 提供会话列表接口
• 提供日志列表接口

Manager

Manager 即监控服务的管理后台，私有包，不发布，同样可以通过 @heimdallr-sdk/cli 脚手架工具快速部署

使用了自己写的 Vue3 脚手架 vva-cli 快速开发的，技术栈是 Vue3 + Typescript + Element-Plus，使用 Vite 打包编译

有以下四个模块：

1. 总览
   

1. 应用列表
   

1. 会话
   

详情不单开页面，在列表页右侧增加抽屉式弹层展示

（回放功能需引入 @heimdallr-sdk/record 插件）

1. 日志
   

同样的，日志详情也不单开页面，在列表页右侧增加抽屉式弹层展示

Tools

@heimdallr-sdk/cli

heimdallr-sdk 的脚手架工具

主要作用就是为了能够快速部署“监控服务端”与“监控管理后台”

全局安装脚手架

npm i @heimdallr-sdk/cli

安装完成后输入 heimdallr-create 命令，即可开始选择相应的模板

提供监控后台管理台和监控服务以及带消息队列的监控服务 三类模板

依次完成配置（作答）后，在当前目录下将自动创建项目文件夹

三个模板前文已经介绍了，这里就不再赘述了

@heimdallr-sdk/webpack-plugin-sourcemap-upload

这个插件名为"doge"，主要功能是自动上传在使用webpack构建工具的项目中生成的sourcemap文件。

它将在 webpack 构建完成后，将产出的 sourcemap 文件自动上传到指定服务器

用法也很简单，指定一下初始化 sdk 时使用的应用名称，以及文件上传的接口地址即可

import UploadSourceMapPlugin from "@heimdallr-sdk/webpack-plugin-sourcemap-upload";
const config = {
  plugins: [
    new UploadSourceMapPlugin({
      appname: "playground",
      url: `http://localhost:8001/sourcemap/upload`,
    }),
  ],
  // TODO--
};

@heimdallr-sdk/vite-plugin-sourcemap-upload

该插件的功能与前一个插件相同，但不同的是：前一个插件适用于使用 webpack 作为构建工具的项目，而该插件适用于使用 vite 作为构建工具的项目。

同样是在 vite 构建工作完成后，将产出的 sourcemap 文件自动上传到指定服务器

因为 vite 底层其实是使用 rollup 构建，因此，该插件监听的是 writeBundle 和 closeBundle 两个阶段的 hook

用法如下

import sourceMapUpload from "@heimdallr-sdk/vite-plugin-sourcemap-upload";

export default defineConfig({
  plugins: [
    vue(),
    sourceMapUpload({
      appname: "playground",
      url: `http://localhost:8001/sourcemap/upload`,
    }),
  ],
  build: {
    sourcemap: true,
  },
  // TODO--
});

使用时需要注意的是，@heimdallr-sdk/webpack-plugin-sourcemap-upload 对外暴露的是一个类，而 @heimdallr-sdk/vite-plugin-sourcemap-upload 对外暴露的则是一个函数

后记

后续考虑出个系列，再详细写一下实现。刚开源不久，可能还有 bug ，欢迎多多提 issue

前端监控对于任何能赚钱的业务都是必不可少的。当项目出现bug时，使用自己开发的前端监控系统能够更早地发现和排查问题。基于插件化架构的监控系统具有更高的安全性和定制化的能力。对于大项目而言，贵重着重于安全性和定制化。自己开发前端监控系统能够更主动地解决问题。

参考链接：https://zhuanlan.zhihu.com/p/614352204