Sobey Monitor SDK

前端全方位监控 SDK，支持错误监控、性能监控、用户行为回溯。适合单页面应用及多端环境。

特性

• 错误监控：JS 运行时错误、Promise 异常、资源加载失败、HTTP 请求错误、白屏检测。
• 性能监控：核心 Web Vitals 指标 (FP, FCP, LCP, FID, CLS, TTFB) 及页面加载流程。
• 行为回溯：通过面包屑 (Breadcrumbs) 自动记录用户点击、路由变化、控制台日志等行为轨迹。
• 多应用隔离：支持多 appId 隔离上报，配合管理后台实现多项目监控。

安装

npm install sobey-monitor-sdk --save

快速开始

方式一：使用远程配置（推荐）

通过 configUrl 从服务端获取配置，无需手动维护 appId 和 dsn：

import { monitor } from 'sobey-monitor-sdk';

// 只需提供 configUrl，其他配置从远程获取
monitor.init({
  configUrl: '/monitor/api/config/your-app-id'
});

// 也可以覆盖部分远程配置
monitor.init({
  configUrl: '/monitor/api/config/your-app-id',
  debug: true  // 本地配置优先级高于远程配置
});

方式二：传统配置

import { monitor } from 'sobey-monitor-sdk';

monitor.init({
  appId: 'your-app-id', // 在管理后台申请
  dsn: 'http://localhost:3000/api/report', // 后端接收地址
  debug: true, // 开启调试模式
});

API

monitor.init(config)

初始化 SDK。

monitor.setUser(userInfo)

设置当前用户信息，方便追踪。

monitor.updateConfig(partialConfig)

动态更新 SDK 配置。可以在运行时修改采样率、调试模式等配置。

// 示例：动态开启调试模式
monitor.updateConfig({ debug: true });

// 示例：动态调整采样率
monitor.updateConfig({
  sampling: { error: 0.5, performance: 0.1 }
});

monitor.getConfig()

获取当前 SDK 配置。

monitor.captureError(error, extra)

手动上报异常或错误。

monitor.addBreadcrumb(breadcrumb)

手动添加一条用户行为轨迹。

monitor.flush()

立即上报缓冲区中的数据。

框架集成

Vue 3

使用 VueMonitorPlugin 插件，可以捕获 Vue 组件内的渲染错误：

import { createApp } from 'vue';
import App from './App.vue';
import { VueMonitorPlugin } from 'sobey-monitor-sdk';

const app = createApp(App);

app.use(VueMonitorPlugin, {
  appId: 'your-app-id',
  dsn: 'http://localhost:3000/api/report',
  debug: true,
});

app.mount('#app');

React

使用 createReactErrorBoundary 创建错误边界组件，包裹根组件以捕获渲染错误：

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import { createReactErrorBoundary } from 'sobey-monitor-sdk';

// 创建错误边界组件
const ErrorBoundary = createReactErrorBoundary(React, {
  appId: 'your-app-id',
  dsn: 'http://localhost:3000/api/report',
  debug: true,
});

ReactDOM.render(
  <ErrorBoundary fallback={<h1>页面出错了</h1>}>
    <App />
  </ErrorBoundary>,
  document.getElementById('root')
);

注意：框架集成会自动初始化 SDK，无需再手动调用 monitor.init()。

配置项

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | configUrl | string | - | 远程配置接口地址，填写后可从远程获取 appId、dsn 等配置（仅初始化时获取一次） | | appId | string | 必填* | 应用唯一标识（使用 configUrl 时可不填） | | dsn | string | 必填* | 数据上报地址（使用 configUrl 时可不填） | | enabled | boolean | true | 全局开关，设为 false 则完全禁用所有监控上报 | | debug | boolean | false | 调试模式，开启后会在控制台输出日志 | | sampling.error | number | 1 | 错误采样率 (0-1) | | sampling.performance | number | 1 | 性能采样率 (0-1) | | sampling.behavior | number | 1 | 行为采样率 (0-1) | | report.maxBufferSize | number | 10 | 缓冲区最大数量，达到后立即上报 | | report.flushInterval | number | 5000 | 上报间隔 (ms) | | report.timeout | number | 10000 | 请求超时 (ms) | | error.enabled | boolean | true | 是否启用错误监控 | | error.jsError | boolean | true | 是否捕获 JS 运行时错误 | | error.promiseError | boolean | true | 是否捕获 Promise 异常 | | error.resourceError | boolean | true | 是否捕获资源加载错误 | | error.httpError | boolean | true | 是否捕获 HTTP 请求错误 | | performance.enabled | boolean | true | 是否启用性能监控 | | performance.webVitals | boolean | true | 是否采集 Web Vitals 指标 | | performance.resource | boolean | true | 是否采集资源加载性能 | | performance.api | boolean | true | 是否采集接口性能 | | behavior.enabled | boolean | true | 是否启用行为监控 | | behavior.pv | boolean | true | 是否采集页面访问 (PV) | | behavior.click | boolean | true | 是否采集点击事件 | | behavior.route | boolean | true | 是否采集路由变化 | | behavior.maxBreadcrumbs | number | 20 | 行为回溯最大记录数 | | behavior.recordRequestBreadcrumb | 'all' | 'error' | 'none' | 'error' | 网络请求记录模式：'all' 记录所有、'error' 记录失败请求、'none' 不记录 |

产物清单

构建产物生成在 dist 目录中：

• index.cjs.js: CommonJS 格式
• index.esm.js: ES Module 格式
• index.umd.js: UMD 格式 (支持 CDN 引入)
• index.d.ts: TypeScript 类型定义