Skip to content

快速开始.md

Latest commit

 

History

History
373 lines (291 loc) · 10.1 KB

快速开始.md

File metadata and controls

373 lines (291 loc) · 10.1 KB

EzMonitor SDK

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

🚀 功能特性

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

📦 安装

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

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

⚡ 快速开始

基础使用

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错误、资源错误捕获
// ✅ 性能监控 - 页面性能指标收集
// ✅ 行为监控 - 用户交互行为记录
// ✅ 屏幕录制 - 用户操作录制（用于错误回放）

高级配置

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应用：

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

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

详细文档：PV监控详解

2. 自定义埋点

// 获取行为监控实例
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. 获取用户行为轨迹

// 获取用户最近的行为记录（面包屑导航）
// 获取屏幕录制数据（用于错误回放）
import { getRecordScreenData } from '@EzStars/EzMonitor'

const breadcrumbs = window.$SDK.Behaviour.breadcrumbs.getAll()
console.log('用户行为轨迹:', breadcrumbs)
const recordData = getRecordScreenData()
console.log('录屏数据:', recordData)

🛠️ 框架集成示例

Vue.js 项目

import EzMonitor from '@EzStars/EzMonitor'
// main.js
import { createApp } from 'vue'
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 项目

// 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 项目

// _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: 沙箱管理，插件隔离

🌟 特色功能

智能白屏检测

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

SourceMap 源码定位

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

错误录屏回放

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

📊 数据类型说明

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

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

主要数据类型

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

🔍 调试和监控

开发环境调试

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
  }
})

生产环境监控

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

📚 详细文档

🛠️ 开发测试

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

# 安装依赖
pnpm install

# 构建SDK
pnpm run build

# 运行测试
pnpm run test

💡 最佳实践

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

❓ 常见问题

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

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

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

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

🤝 技术支持

如有问题，请联系：

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