前端监控 SDK

前端监控 SDK，用于错误监控、性能监控和用户行为追踪。

功能特点

• 错误监控：捕获 JS 异常、Promise 错误、资源加载错误、HTTP 请求错误等
• 性能监控：记录页面加载性能、资源加载时间、Web Vitals 核心指标等
• 用户行为追踪：PV/UV 统计、点击事件追踪、路由变化记录等
• 调试能力：支持通过 CDN 引入 eruda 调试面板，可通过特定触发方式打开
• 控制台管理：封装原生 console，支持开启/关闭日志输出
• 丰富的扩展能力：支持自定义插件开发

安装

npm install epoint-frontend-monitor-sdk --save
# 或者
yarn add epoint-frontend-monitor-sdk

基本使用

import { createMonitor } from "epoint-frontend-monitor-sdk";

// 创建监控实例
const monitor = createMonitor({
  appId: "your-app-id", // 应用ID，必填
  userId: "user-123", // 用户ID，可选
  reportUrl: "https://your-report-api.com/report", // 上报地址

  // 错误监控配置
  error: {
    enabled: true,
    jsError: true,
    resourceError: true,
    promiseError: true,
    httpError: true,
  },

  // 性能监控配置
  performance: {
    enabled: true,
    webVitals: true,
    firstPaint: true,
  },

  // 用户行为监控配置
  behavior: {
    enabled: true,
    pv: true,
    click: true,
    route: true,
  },
});

// 手动上报错误
monitor.reportError(new Error("自定义错误"));

// 手动上报性能指标
monitor.reportPerformance("customMetric", 123);

// 手动上报事件
monitor.reportEvent("buttonClick", { buttonId: "submit-btn" });

调试面板功能

SDK 集成了 eruda 调试面板，可通过 CDN 动态加载，减小 SDK 体积。调试面板有以下激活方式：

1. 连续点击指定元素 N 次激活
2. 通过 URL 参数打开

配置调试面板

import { createMonitor } from "epoint-frontend-monitor-sdk";

const monitor = createMonitor({
  appId: "your-app-id",
  // ...其他配置项

  // 调试面板配置
  debugPanel: {
    enabled: false, // 默认不启用，需要通过触发方式开启
    cdn: "https://cdn.jsdelivr.net/npm/eruda", // CDN地址
    triggerCount: 5, // 需要连续点击5次才能激活
    triggerEl: "body", // 点击触发的元素，默认是body
    triggerKey: "__debug_mode__", // localStorage中存储的键名
    urlParamKey: "debug", // URL参数名，如 ?debug=1
  },
});

激活方式

1. 连续快速点击激活：在页面上连续快速点击配置的元素 (默认是 body) 指定次数 (默认 5 次)
2. URL 参数激活：在 URL 后添加参数，例如 ?debug=1 或 ?debug=true
3. URL 参数关闭：在 URL 后添加参数，例如 ?debug=0 或 ?debug=false

Console 控制功能

SDK 封装了原生 console 对象，可以通过配置控制日志输出：

import { createMonitor } from "epoint-frontend-monitor-sdk";

const monitor = createMonitor({
  appId: "your-app-id",
  // ...其他配置项

  // 控制台配置
  console: {
    enabled: true, // 是否开启console输出
    prefix: "[MyApp]", // 输出前缀
    enabledMethods: ["log", "warn", "error"], // 允许的方法，空数组表示全部
    saveToMemory: true, // 是否保存日志到内存
    maxMemoryLogs: 100, // 内存中最大保存的日志条数
    overrideNative: true, // 是否覆盖原生console
    logLevel: "info", // 日志级别: debug, info, warn, error, all
  },
});

控制 console 输出

通过 SDK 实例可以动态控制 console 输出：

import { ConsolePlugin } from "epoint-frontend-monitor-sdk";

// 获取monitor实例
const monitor = window.$monitor;

// 获取console插件
const consolePlugin = monitor.getPlugin(ConsolePlugin);

if (consolePlugin) {
  // 禁用所有console输出
  consolePlugin.disable();

  // 启用console输出
  consolePlugin.enable();

  // 设置日志级别
  consolePlugin.setLogLevel("warn"); // 只输出warn和error级别

  // 获取内存中的日志
  const logs = consolePlugin.getLogs();

  // 清空内存中的日志
  consolePlugin.clearLogs();

  // 恢复原始console行为
  consolePlugin.restore();
}

配置项说明

| 配置项 | 类型 | 必填 | 默认值 | 说明 | | --------------- | ------- | ---- | ------ | -------------------- | | appId | string | 是 | - | 应用唯一标识 | | userId | string | 否 | - | 用户 ID | | reportUrl | string | 是 | - | 数据上报地址 | | debug | boolean | 否 | false | 是否开启调试模式 | | sampling | number | 否 | 1 | 采样率(0-1) | | maxBreadcrumbs | number | 否 | 20 | 最大面包屑数量 | | withCredentials | boolean | 否 | false | 跨域请求是否携带凭证 |

更多配置项详见代码类型定义。