epoint-frontend-monitor

v1.0.0

Published

a year ago

前端监控SDK，支持错误监控、性能监控、设备信息采集等

0High
0Medium
0Low

helun940122

monitor frontend performance error analytics

frontend-monitor-sdk

一个功能全面的前端监控 SDK，用于监控前端异常、性能和用户行为。

功能特点

前端异常监控
- JS 错误信息监控
- Vue 错误信息监控
- Promise 未捕获异常监控
- Ajax(xhr/fetch)异常信息监控
- console.error 错误监控
- 资源加载错误监控
性能监控
- 页面加载性能监控
- 资源加载性能监控
- Web Vitals 指标监控(LCP、FID、CLS)
设备信息采集
- 浏览器信息
- 操作系统信息
- 设备类型
- 屏幕分辨率
- 网络类型
自定义事件上报
- 支持自定义事件名称和参数
- 支持即时上报和批量上报
调试工具集成
- 集成 eruda 调试面板
- 支持 URL 参数唤起
- 支持缓存唤起
- 支持全局配置开关

安装

NPM 方式

npm install frontend-monitor-sdk --save

CDN 方式

<script src="https://cdn.jsdelivr.net/npm/frontend-monitor-sdk/dist/index.umd.min.js"></script>

快速开始

基本用法

// ES Module方式引入
import FrontendMonitor from "frontend-monitor-sdk";

// 初始化SDK
const monitor = new FrontendMonitor({
  appId: "your-app-id", // 应用唯一标识
  reportUrl: "https://your-report-api.com/report", // 数据上报接口地址
  enableErrorMonitor: true, // 是否开启错误监控
  enablePerformanceMonitor: true, // 是否开启性能监控
  enableDeviceInfo: true, // 是否采集设备信息
  samplingRate: 1, // 采样率，1表示100%采样
  logLevel: "info", // 日志级别
});

// 自定义事件上报
monitor.track("page_view", {
  page: location.href,
  title: document.title,
  timestamp: Date.now(),
});

使用 Vue 错误监控

import FrontendMonitor from "frontend-monitor-sdk";
import Vue from "vue";

const monitor = new FrontendMonitor({
  appId: "your-app-id",
  reportUrl: "https://your-report-api.com/report",
  enableVueErrorMonitor: true, // 开启Vue错误监控
  vue: Vue, // 传入Vue实例
});

使用 eruda 调试面板

eruda 调试面板可以通过以下方式开启：

初始化时配置开启

const monitor = new FrontendMonitor({
  appId: "your-app-id",
  reportUrl: "https://your-report-api.com/report",
  enableEruda: true, // 开启eruda调试面板
  erudaCdn: "https://cdn.jsdelivr.net/npm/eruda", // 可选，指定eruda CDN地址
});

URL 参数方式开启

在 URL 中添加debug=true参数即可开启，例如：

https://your-app.com/index.html?debug=true

localStorage 方式开启

在浏览器控制台执行：

localStorage.setItem("monitor_debug", "true");

代码动态开启

// 开启调试面板
monitor.enableDebugger();

// 关闭调试面板
monitor.disableDebugger();

配置选项

| 参数名 | 类型 | 必填 | 默认值 | 说明 | | ------------------------ | ----------------------- | ---- | ------------------------------------ | ------------------------------------------------------------ | | appId | string | 是 | - | 应用唯一标识 | | reportUrl | string | 是 | - | 数据上报接口地址 | | enableErrorMonitor | boolean | 否 | true | 是否开启错误监控 | | enableVueErrorMonitor | boolean | 否 | false | 是否开启 Vue 错误监控 | | vue | Vue 实例 | 否 | - | Vue 实例，启用 Vue 错误监控时必填 | | enablePerformanceMonitor | boolean | 否 | true | 是否开启性能监控 | | enableDeviceInfo | boolean | 否 | true | 是否采集设备信息 | | samplingRate | number | 否 | 1 | 采样率，范围 0-1 | | ignoreErrors | Array<string | RegExp> | 否 | [] | 忽略的错误信息 | | beforeDataReport | function | 否 | - | 数据上报前的处理函数 | | enableEruda | boolean | 否 | false | 是否启用 eruda 调试工具 | | erudaCdn | string | 否 | 'https://cdn.jsdelivr.net/npm/eruda' | eruda CDN 地址 | | logLevel | string | 否 | 'info' | 日志级别：'debug' | 'info' | 'warn' | 'error' | 'silent' | | maxCacheSize | number | 否 | 10 | 最大缓存数量 | | immediateErrorReport | boolean | 否 | true | 是否立即上报错误 |

API 参考

FrontendMonitor 实例方法

track(eventName, params)

上报自定义事件。

参数：
- eventName: string - 事件名称
- params: object - 事件参数
返回：Promise - 上报是否成功

monitor.track("button_click", {
  buttonId: "submit-btn",
  page: location.pathname,
});

enableDebugger()

启用 eruda 调试面板。

返回：Promise

monitor.enableDebugger();

disableDebugger()

禁用 eruda 调试面板。

返回：void

monitor.disableDebugger();

getDeviceInfo()

获取当前设备信息。

返回：DeviceInfo | null - 设备信息对象

const deviceInfo = monitor.getDeviceInfo();
console.log(deviceInfo);

destroy()

销毁监控实例，清理相关资源。

返回：void

monitor.destroy();

数据上报格式

数据上报采用 POST 请求，Content-Type 为 application/json，请求体为 JSON 数组，包含多条数据。

单条数据格式如下：

{
  "type": "error", // 数据类型：error|performance|device|custom
  "data": {}, // 具体数据内容，根据type不同而不同
  "timestamp": 1611232323232, // 时间戳
  "appId": "your-app-id", // 应用标识
  "sessionId": "xxxxxx", // 会话ID
  "deviceInfo": {} // 设备信息
}

错误数据格式 (type=error)

{
  "type": "error",
  "data": {
    "type": "js", // 错误类型：js|vue|promise|ajax|console|resource
    "name": "Error", // 错误名称
    "message": "Cannot read property 'x' of undefined", // 错误信息
    "stack": "...", // 错误堆栈
    "pageUrl": "https://example.com/index.html", // 发生错误的页面URL
    "filename": "app.js", // 发生错误的文件名
    "lineNo": 42, // 行号
    "columnNo": 13, // 列号
    "selector": "button#submit", // 元素选择器(资源错误)
    "componentName": "LoginForm" // 组件名称(Vue错误)
  },
  "timestamp": 1611232323232,
  "appId": "your-app-id",
  "sessionId": "xxxxxx",
  "deviceInfo": {...}
}

性能数据格式 (type=performance)

{
  "type": "performance",
  "data": {
    "redirect": 0, // 重定向时间
    "dns": 23, // DNS查询时间
    "tcp": 35, // TCP连接时间
    "request": 128, // 请求时间
    "response": 45, // 响应时间
    "domParse": 67, // DOM解析时间
    "domContentLoaded": 563, // DOM内容加载完成时间
    "firstPaint": 532, // 首次绘制时间
    "firstContentfulPaint": 543, // 首次内容绘制时间
    "largestContentfulPaint": 1023, // 最大内容绘制时间
    "firstInputDelay": 24, // 首次输入延迟
    "cumulativeLayoutShift": 0.02, // 累计布局偏移
    "load": 1245, // 页面加载总时间
    "resources": [
      {
        "name": "https://example.com/app.js",
        "initiatorType": "script",
        "duration": 78,
        "transferSize": 25600
      }
    ]
  },
  "timestamp": 1611232323232,
  "appId": "your-app-id",
  "sessionId": "xxxxxx",
  "deviceInfo": {...}
}

设备信息格式 (type=device)

{
  "type": "device",
  "data": {
    "browser": "Chrome",
    "browserVersion": "88.0.4324.96",
    "os": "Windows",
    "osVersion": "10",
    "deviceType": "desktop",
    "screenResolution": "1920x1080",
    "networkType": "4g",
    "language": "zh-CN",
    "userAgent": "Mozilla/5.0...",
    "devicePixelRatio": 1.5
  },
  "timestamp": 1611232323232,
  "appId": "your-app-id",
  "sessionId": "xxxxxx"
}

自定义事件格式 (type=custom)

{
  "type": "custom",
  "data": {
    "name": "button_click",
    "params": {
      "buttonId": "submit-btn",
      "page": "/login"
    }
  },
  "timestamp": 1611232323232,
  "appId": "your-app-id",
  "sessionId": "xxxxxx",
  "deviceInfo": {...}
}

浏览器兼容性

Chrome >= 49
Firefox >= 52
Safari >= 10
Edge >= 15
IE >= 11 (基础功能支持，部分高级功能可能不可用)

许可证

MIT