前端性能监控SDK

简介

这是一个轻量级的前端性能监控SDK，用于采集和上报网页性能数据、错误信息和用户行为数据，帮助开发者监控和优化前端应用。

功能特性

1. 性能监控

核心Web指标：LCP (最大内容绘制)、FID (首次输入延迟)、CLS (累积布局偏移)
加载时序指标：FP (首次绘制)、FCP (首次内容绘制)、TTFB (首字节时间) 等
请求性能：XHR 和 Fetch 请求监控
长任务监控：识别可能导致卡顿的长任务

2. 错误监控

JS运行时错误：捕获全局错误
Promise错误：监控未捕获的Promise拒绝
资源加载错误：监控图片、脚本等资源加载失败
白屏检测：自动检测页面白屏情况

3. 用户行为监控

页面浏览：PV/UV统计
用户交互：点击、表单提交、键盘输入等
会话管理：用户会话跟踪
滚动行为：页面滚动深度监控

4. 高级上报策略

采样率控制：可配置数据采集采样率
批量上报：减少HTTP请求次数
定时上报：按时间间隔上报数据
离线存储：支持离线数据缓存
降级策略：多种数据发送方式备用

快速开始

1. 安装方式

从NPM安装

bash

npm install frontend-monitor-sdk-px

从源码构建

bash

# 克隆仓库
# 安装依赖
npm install

# 构建SDK
npm run build

构建完成后，SDK文件将生成在 dist 目录下：

dist/umd/monitor.js - UMD格式未压缩版本
dist/umd/monitor.min.js - UMD格式压缩版本
dist/esm/monitor.esm.js - ESM格式未压缩版本
dist/esm/monitor.esm.min.js - ESM格式压缩版本

3. 使用方式

3.1 通过CDN引入

html

<script src="path/to/monitor.js"></script>
<script>
  // 配置SDK
  PerfMonitor('config', {
    appId: 'your-app-id',
    serverUrl: 'https://your-report-server.com/api/report'
  });
  
  // 初始化SDK
  PerfMonitor('init');
</script>

3.2 通过模块化引入

javascript

// ES模块引入
import PerfMonitor from 'frontend-monitor-sdk-px';

// 或者CommonJS引入
const PerfMonitor = require('frontend-monitor-sdk-px');

// 配置SDK
PerfMonitor('config', {
  appId: 'your-app-id',
  serverUrl: 'https://your-report-server.com/api/report'
});

// 初始化SDK
PerfMonitor('init');

配置选项

javascript

PerfMonitor('config', {
  // 应用标识
  appId: 'your-app-id',
  
  // 上报服务器地址
  serverUrl: 'https://your-report-server.com/api/report',
  
  // 采样率 (0-1)
  sampleRate: 1,
  
  // 是否启用性能监控
  enablePerformance: true,
  
  // 是否启用错误监控
  enableError: true,
  
  // 是否启用用户行为监控
  enableUserBehavior: true,
  
  // 批量上报的数量阈值
  batchSize: 5,
  
  // 定时上报的时间间隔 (ms)
  interval: 3000,
  
  // 自定义采样函数
  sample: function() {
    return Math.random() < 0.5; // 50%采样率
  },
  
  // 数据过滤函数
  filter: function(data) {
    // 返回true则上报，false则不上报
    return data.value < 1000; // 只上报值小于1000的数据
  }
});

包导出格式

该SDK同时支持多种模块格式，适配不同的使用场景：

UMD格式：适用于浏览器直接引入
ESM格式：适用于现代打包工具和ES模块环境
CommonJS格式：通过exports字段支持require引入

API参考

1. 配置与初始化

javascript

// 配置SDK - 这是SDK的核心配置方式
PerfMonitor('config', options);

// 初始化SDK
PerfMonitor('init');

// 销毁SDK实例
PerfMonitor('destroy');

2. 自定义事件上报

javascript

// 上报自定义事件
PerfMonitor('trackEvent', eventName, eventData);

// 上报自定义错误
PerfMonitor('trackError', error, context);

// 上报自定义性能指标
PerfMonitor('trackPerformance', metricName, metricValue, context);

3. 面包屑记录

javascript

// 添加自定义面包屑
PerfMonitor('addBreadcrumb', {
  type: 'custom',
  message: '自定义面包屑信息',
  data: { key: 'value' }
});

数据格式

1. 性能数据

json

{
  "type": "performance",
  "subType": "lcp", // 指标类型
  "value": 2500,    // 指标值 (ms)
  "timestamp": 1652345678901,
  "pageUrl": "https://example.com/page",
  "appId": "your-app-id"
}

2. 错误数据

json

{
  "type": "error",
  "subType": "js_error", // 错误类型
  "message": "Uncaught ReferenceError: foo is not defined",
  "stack": "ReferenceError: foo is not defined...",
  "filename": "app.js",
  "lineno": 10,
  "colno": 5,
  "timestamp": 1652345678901,
  "pageUrl": "https://example.com/page",
  "appId": "your-app-id",
  "breadcrumbs": [] // 错误发生前的用户行为面包屑
}

3. 用户行为数据

json

{
  "type": "user_behavior",
  "subType": "click", // 行为类型
  "target": {
    "tagName": "BUTTON",
    "text": "Submit",
    "className": "btn-primary",
    "selector": "#submit-btn"
  },
  "timestamp": 1652345678901,
  "pageUrl": "https://example.com/page",
  "appId": "your-app-id"
}

演示页面

SDK包含一个演示页面，用于展示各项功能：

启动开发服务器

bash

npm run dev

打开浏览器访问demo页面

演示页面提供了各种测试按钮，可以触发不同类型的性能指标、错误和用户行为，帮助你了解SDK的各项功能。

发布与使用注意事项

NPM发布信息

包名：frontend-monitor-sdk-px
版本：v0.0.2

使用注意事项

浏览器兼容性：支持所有现代浏览器（Chrome, Firefox, Safari, Edge）
性能影响：SDK经过优化，对页面性能影响极小，但请根据实际情况调整采样率
敏感数据：SDK会对密码等敏感信息进行脱敏处理，但仍建议根据项目需求调整采集策略
跨域问题：确保上报服务器配置了正确的CORS策略
上报频率：合理设置批量上报和定时上报参数，避免过多的HTTP请求

部署与发布建议

SDK部署

CDN部署：将SDK部署到CDN，可使用以下文件路径：
- 压缩版本：https://your-cdn.com/path/to/monitor.min.js
- 未压缩版本（开发调试）：https://your-cdn.com/path/to/monitor.js
NPM包使用：推荐直接通过NPM安装使用，便于版本管理

配置建议

配置适当的采样率，平衡数据准确性和性能开销
实现服务端的数据接收、存储和分析功能
设置数据清理策略，定期清理过期数据
监控上报接口的可用性和性能

NPM发布流程

更新版本号（package.json）
运行构建确保最新代码被打包：npm run build
登录NPM：npm login
发布包：npm publish

前端性能监控SDK ​

简介 ​

功能特性 ​

1. 性能监控 ​

2. 错误监控 ​

3. 用户行为监控 ​

4. 高级上报策略 ​

快速开始 ​

1. 安装方式 ​

从NPM安装 ​

从源码构建 ​

3. 使用方式 ​

3.1 通过CDN引入 ​

3.2 通过模块化引入 ​

配置选项 ​

包导出格式 ​

API参考 ​

1. 配置与初始化 ​

2. 自定义事件上报 ​

3. 面包屑记录 ​

数据格式 ​

1. 性能数据 ​

2. 错误数据 ​

3. 用户行为数据 ​

演示页面 ​

发布与使用注意事项 ​

NPM发布信息 ​

使用注意事项 ​

部署与发布建议 ​

SDK部署 ​

配置建议 ​

NPM发布流程 ​

前端性能监控SDK

简介

功能特性

1. 性能监控

2. 错误监控

3. 用户行为监控

4. 高级上报策略

快速开始

1. 安装方式

从NPM安装

从源码构建

3. 使用方式

3.1 通过CDN引入

3.2 通过模块化引入

配置选项

包导出格式

API参考

1. 配置与初始化

2. 自定义事件上报

3. 面包屑记录

数据格式

1. 性能数据

2. 错误数据

3. 用户行为数据

演示页面

发布与使用注意事项

NPM发布信息

使用注意事项

部署与发布建议

SDK部署

配置建议

NPM发布流程