EzMonitor SDK

一站式前端监控解决方案，提供性能监控、错误监控、用户行为分析等全方位的前端监控能力。

🚀 功能特性

🔍 PV监控：页面访问量统计，支持SPA路由监控，实时流量分析
⚡ 性能监控：获取页面加载性能数据，包括FCP、LCP等核心指标
🐛 错误监控：捕获JavaScript错误、资源加载错误、Promise未捕获异常
🎯 用户行为分析：记录用户点击、路由跳转、自定义埋点等交互行为
🎬 错误录屏回放：基于rrweb的用户操作录制，错误现场完美还原
🛠️ 框架支持：支持React、Vue、Next.js等主流前端框架
📊 智能上报：支持批量上报、失败重试、自定义上报策略

📦 安装

注意：项目还在完善中，暂未发布到npm

bash

npm install @EzStars/EzMonitor
# 或
pnpm add @EzStars/EzMonitor
# 或
yarn add @EzStars/EzMonitor

⚡ 快速开始

基础使用

typescript

import EzMonitor from '@EzStars/EzMonitor';

// 初始化监控SDK
const monitor = new EzMonitor({
  url: 'https://your-api.com/monitor',    // 上报地址 (必填)
  projectName: 'your-project',            // 项目名称 (必填)
  appId: 'your-app-id',                   // 项目ID (必填)
  userId: 'user-123',                     // 用户ID (必填)
});

// SDK 初始化后，以下功能将自动启动：
// ✅ PV监控 - 页面访问量统计
// ✅ 错误监控 - JS错误、资源错误捕获
// ✅ 性能监控 - 页面性能指标收集
// ✅ 行为监控 - 用户交互行为记录
// ✅ 屏幕录制 - 用户操作录制（用于错误回放）

高级配置

typescript

const monitor = new EzMonitor({
  // 基础配置
  url: 'https://your-api.com/monitor',
  projectName: 'your-project',
  appId: 'your-app-id',
  userId: 'user-123',
  
  // 上报配置
  batchSize: 10,                          // 批量上报大小，默认10
  isAjax: true,                           // 是否使用Ajax上报，默认true
  
  // 白屏检测配置
  containerElements: ['#app', '#root'],   // 容器元素选择器
  skeletonElements: ['.skeleton'],        // 骨架屏元素选择器
  
  // SourceMap配置（用于错误源码定位）
  enableSourceMap: true,                  // 是否启用SourceMap解析
  sourceMapTimeout: 3000,                 // SourceMap获取超时时间
  sourceMapEndpoint: 'https://your-api.com/sourcemap', // SourceMap服务端点
  
  // 回调函数
  reportBefore: (data) => {
    console.log('上报前:', data);
    // 可以在这里过滤或修改数据
    return data;
  },
  
  reportSuccess: (data) => {
    console.log('上报成功:', data);
  },
  
  reportFail: (error) => {
    console.error('上报失败:', error);
  },
  
  reportAfter: (data) => {
    console.log('上报后:', data);
  }
});

🎯 核心功能使用

1. PV 监控（自动启用）

PV 监控会自动统计页面访问量，支持传统页面和SPA应用：

typescript

// 无需额外配置，SDK初始化后自动启动
// 监控以下场景：
// - 页面首次加载
// - Hash路由变化 (#/home -> #/about)
// - History API路由变化 (/home -> /about)

// 查看PV监控数据（调试用）
console.log('页面信息:', getPageInfo());
console.log('来源信息:', getOriginInfo());

详细文档：PV监控详解

2. 自定义埋点

typescript

// 获取行为监控实例
const behavior = window.$SDK.Behaviour;

// 发送自定义业务埋点
behavior.customHandler({
  eventKey: 'button_click',               // 事件标识
  eventAction: 'click',                   // 事件动作
  eventValue: {                           // 事件数据
    button_name: '购买按钮',
    page: '/product/123',
    price: 99.99,
    user_type: 'premium'
  }
});

3. 获取用户行为轨迹

typescript

// 获取用户最近的行为记录（面包屑导航）
const breadcrumbs = window.$SDK.Behaviour.breadcrumbs.getAll();
console.log('用户行为轨迹:', breadcrumbs);

// 获取屏幕录制数据（用于错误回放）
import { getRecordScreenData } from '@EzStars/EzMonitor';
const recordData = getRecordScreenData();
console.log('录屏数据:', recordData);

🛠️ 框架集成示例

Vue.js 项目

typescript

// main.js
import { createApp } from 'vue';
import EzMonitor from '@EzStars/EzMonitor';
import App from './App.vue';

// 初始化监控
const monitor = new EzMonitor({
  url: 'https://api.example.com/monitor',
  projectName: 'vue-app',
  appId: 'vue-app-001',
  userId: localStorage.getItem('userId') || 'anonymous',
});

const app = createApp(App);
app.mount('#app');

React 项目

typescript

// index.js
import React from 'react';
import ReactDOM from 'react-dom/client';
import EzMonitor from '@EzStars/EzMonitor';
import App from './App';

// 初始化监控
const monitor = new EzMonitor({
  url: 'https://api.example.com/monitor',
  projectName: 'react-app',
  appId: 'react-app-001',
  userId: localStorage.getItem('userId') || 'anonymous',
});

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);

Next.js 项目

typescript

// _app.js
import EzMonitor from '@EzStars/EzMonitor';
import { useEffect } from 'react';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    // 客户端初始化监控
    if (typeof window !== 'undefined') {
      const monitor = new EzMonitor({
        url: 'https://api.example.com/monitor',
        projectName: 'nextjs-app',
        appId: 'nextjs-app-001',
        userId: 'user-123',
      });
    }
  }, []);

  return <Component {...pageProps} />;
}

export default MyApp;

🏗️ 项目架构

EzMonitor采用模块化设计，核心模块包括：

采集层 (Collection Layer)

Performance Plugin: 性能数据采集 (FCP、LCP、FMP等)
Error Plugin: 错误数据采集 (JS错误、资源错误、Promise错误)
Behavior Plugin: 行为数据采集 (PV、点击、路由跳转)
Exception Plugin: 异常数据采集 (白屏、卡顿检测)

处理层 (Processing Layer)

数据过滤: 去重、去敏、异常数据过滤
数据采样: 采样策略、流量控制
数据压缩: 录屏数据压缩、批量数据压缩

上报层 (Reporting Layer)

批量上报: 减少网络请求，提高性能
失败重试: 网络异常时的重试机制
优先级队列: 错误数据优先上报

核心层 (Core Layer)

EventBus: 事件总线，模块间通信
ReportQueue: 上报队列管理
SandboxManager: 沙箱管理，插件隔离

🌟 特色功能

智能白屏检测

typescript

const monitor = new EzMonitor({
  // 配置白屏检测
  containerElements: ['#app', '#root', '.main-content'],
  skeletonElements: ['.skeleton', '.loading'],
  // 当检测到白屏时会自动上报
});

SourceMap 源码定位

typescript

const monitor = new EzMonitor({
  enableSourceMap: true,                    // 启用SourceMap
  sourceMapEndpoint: 'https://your-api.com/sourcemap',
  // 错误上报时会自动解析源码位置
});

错误录屏回放

typescript

// 发生错误时，可以获取用户操作录屏
const recordData = getRecordScreenData();
// 录屏数据可以在后台系统中回放，快速定位问题

📊 数据类型说明

所有监控数据都包含以下基础字段：

typescript

interface BaseData {
  type: 'performance' | 'error' | 'behavior' | 'exception';
  subType: string;              // 具体类型
  timestamp: number;            // 时间戳
  // ... 其他具体字段
}

主要数据类型

PV数据 (behavior.pv): 页面访问统计
点击数据 (behavior.click): 用户点击行为
路由数据 (behavior.routerChange): 路由跳转记录
自定义埋点 (behavior.tracker): 业务自定义事件
性能数据 (performance.*): 页面性能指标
错误数据 (error.*): 各类错误信息

🔍 调试和监控

开发环境调试

typescript

const monitor = new EzMonitor({
  // ... 其他配置
  reportBefore: (data) => {
    console.group(`📊 ${data.type}.${data.subType}`);
    console.log('数据:', data);
    console.log('时间:', new Date(data.timestamp).toLocaleString());
    console.groupEnd();
    return data;
  }
});

生产环境监控

typescript

const monitor = new EzMonitor({
  // ... 其他配置
  reportFail: (error) => {
    // 上报失败时的降级处理
    console.error('监控数据上报失败:', error);
    // 可以考虑降级到其他上报方式
  }
});

📚 详细文档

PV监控详解 - 页面访问量监控详细指南
用户行为收集 - 用户行为数据收集
错误录屏回放 - 屏幕录制和错误回放
性能监控 - 页面性能监控指南
错误监控 - 各类错误监控详解
智能上报方案 - 数据上报策略优化

🛠️ 开发测试

bash

# 克隆项目
git clone https://github.com/EzStars/EzMonitor.git

# 安装依赖
pnpm install

# 构建SDK
pnpm run build

# 运行测试
pnpm run test

💡 最佳实践

合理配置批量上报: 根据业务量级调整 batchSize
过滤敏感信息: 在 reportBefore 中过滤用户敏感数据
监控性能影响: 定期检查监控代码对页面性能的影响
错误分级处理: 区分致命错误和普通错误的上报策略
数据隐私合规: 确保收集的数据符合隐私政策要求

❓ 常见问题

Q: SDK 会影响页面性能吗？
A: SDK 采用异步上报和批量处理，对页面性能影响极小（<1ms）

Q: 如何在SPA应用中使用？
A: SDK 自动支持 Hash 和 History 模式的路由监控，无需额外配置

Q: 数据上报失败怎么办？
A: SDK 内置重试机制，并提供 reportFail 回调进行自定义处理

Q: 如何自定义数据过滤？
A: 使用 reportBefore 回调函数，可以在上报前修改或过滤数据

🤝 技术支持

如有问题，请联系：

GitHub Issues: https://github.com/EzStars/EzMonitor/issues
文档网站: [项目文档地址]
技术交流: [技术交流群]

EzMonitor - 让前端监控更简单！ 🚀

EzMonitor SDK ​

🚀 功能特性 ​

📦 安装 ​

⚡ 快速开始 ​

基础使用 ​

高级配置 ​

🎯 核心功能使用 ​

1. PV 监控（自动启用） ​

2. 自定义埋点 ​

3. 获取用户行为轨迹 ​

🛠️ 框架集成示例 ​

Vue.js 项目 ​

React 项目 ​

Next.js 项目 ​

🏗️ 项目架构 ​

采集层 (Collection Layer) ​

处理层 (Processing Layer) ​

上报层 (Reporting Layer) ​

核心层 (Core Layer) ​

🌟 特色功能 ​

智能白屏检测 ​

SourceMap 源码定位 ​

错误录屏回放 ​

📊 数据类型说明 ​

主要数据类型 ​

🔍 调试和监控 ​

开发环境调试 ​

生产环境监控 ​

📚 详细文档 ​

🛠️ 开发测试 ​

💡 最佳实践 ​

❓ 常见问题 ​

🤝 技术支持 ​

EzMonitor SDK

🚀 功能特性

📦 安装

⚡ 快速开始

基础使用

高级配置

🎯 核心功能使用

1. PV 监控（自动启用）

2. 自定义埋点

3. 获取用户行为轨迹

🛠️ 框架集成示例

Vue.js 项目

React 项目

Next.js 项目

🏗️ 项目架构

采集层 (Collection Layer)

处理层 (Processing Layer)

上报层 (Reporting Layer)

核心层 (Core Layer)

🌟 特色功能

智能白屏检测

SourceMap 源码定位

错误录屏回放

📊 数据类型说明

主要数据类型

🔍 调试和监控

开发环境调试

生产环境监控

📚 详细文档

🛠️ 开发测试

💡 最佳实践

❓ 常见问题

🤝 技术支持