vue-monitor-plugin

Vue前端监控系统

这是一个用于Vue应用的全面前端监控系统，能够收集性能指标、错误信息和用户行为数据，帮助开发者了解应用的实际运行状况并进行优化。

功能特点

性能监控

• 页面加载性能：收集完整的导航计时数据
• Web Vitals指标：监控LCP、FCP、CLS、FID等关键性能指标
• 资源加载分析：识别加载缓慢的资源
• 网络性能：DNS解析、TCP连接、请求和响应时间等
• 兼容性处理：自动降级以支持不同浏览器

错误监控

• JavaScript错误：捕获运行时异常
• Promise错误：捕获未处理的Promise拒绝
• 资源加载错误：监控图片、脚本等资源加载失败
• 网络请求错误：监控API请求失败和超时
• 自定义错误上报：支持手动上报错误

用户行为分析

• 页面访问：自动跟踪页面浏览
• 用户点击：记录用户点击行为
• 路由变化：监控SPA路由变化
• 用户交互状态：监控用户活跃状态
• 自定义事件：支持自定义埋点

数据处理与传输

• 批量发送：减少网络请求次数
• 数据采样：控制数据收集比例
• 会话管理：通过会话ID关联用户行为
• 页面卸载保障：确保数据在页面关闭时也能发送
• 自动重试：在发送失败时提供备选方案

TypeScript支持

该监控插件完全使用TypeScript编写，提供了完整的类型定义，使开发体验更加友好：

• 所有API接口和配置选项都有类型定义
• 自动补全和类型检查
• 编辑器集成（VS Code、WebStorm等）中的智能提示
• 类型安全的事件跟踪和错误报告

TypeScript类型包括：

• MonitoringOptions - 配置选项接口
• MonitoringAPI - 暴露给应用的API接口
• BaseInfo - 基础监控信息结构
• PerformanceData - 性能指标数据结构
• ElementInfo - DOM元素信息结构
• 以及更多...

安装

npm install vue-monitor-plugin --save
# 或
yarn add vue-monitor-plugin
# 或
pnpm add vue-monitor-plugin

这种方式会创建一个符号链接到插件项目。

基本使用

在Vue应用的入口文件（通常是main.js或main.ts）中引入并注册插件：

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import MonitoringPlugin from 'vue-monitor-plugin'

const app = createApp(App)

// 注册监控插件
app.use(MonitoringPlugin, {
  apiUrl: 'https://your-api-endpoint.com/collect',
  appId: 'your-app-id'
})

app.use(router)
app.mount('#app')

配置选项

可以通过在注册插件时传入配置对象来自定义监控行为：

interface MonitoringOptions {
  apiUrl: string;                          // 数据上报地址（必填）
  appId?: string;                          // 应用ID
  userId?: string;                         // 用户ID（可选，也可后续设置）
  enablePerformance?: boolean;             // 是否启用性能监控
  enableError?: boolean;                   // 是否启用错误监控
  enableBehavior?: boolean;                // 是否启用行为监控
  enableRoute?: boolean;                   // 是否启用路由监控
  sampleRate?: number;                     // 采样率(0-1)，0.5表示采集50%的数据
  maxBatchSize?: number;                   // 批量发送的最大条数
  flushInterval?: number;                  // 定时发送数据的间隔(ms)
  includeUserAgent?: boolean;              // 是否包含用户代理信息
  ignoreErrors?: (string | RegExp)[];      // 忽略的错误信息
  routeAttributes?: string[];              // 需要收集的路由属性
}

// 使用示例
app.use(MonitoringPlugin, {
  apiUrl: 'https://your-api-endpoint.com/collect',
  appId: 'your-app-id',
  sampleRate: 0.5,
  ignoreErrors: [
    'Script error.',
    /Failed to load resource/
  ],
  routeAttributes: ['fullPath', 'name', 'meta']
})

后续设置用户ID

许多应用在初始化阶段可能无法获取用户ID，比如用户需要登录后才能获取到ID。监控插件提供了多种方式在应用运行过程中设置用户ID：

1. 通过组件内API设置

在任何Vue组件中都可以使用以下方式设置用户ID：

<script setup lang="ts">
import { getCurrentInstance } from 'vue'

const { proxy } = getCurrentInstance()

// 用户登录成功后设置用户ID
function onLoginSuccess(userData) {
  proxy.$monitoringTools.setUserId(userData.id)
}
</script>

在选项式API中：

export default {
  methods: {
    onLoginSuccess(userData) {
      this.$monitoringTools.setUserId(userData.id)
    }
  }
}

2. 通过Vuex/Pinia状态管理设置

在状态管理的action中设置：

// Pinia store
export const useUserStore = defineStore('user', {
  actions: {
    async login(credentials) {
      const userData = await api.login(credentials)
      this.user = userData
      
      // 获取app实例设置用户ID
      const app = getCurrentInstance()?.appContext.app
      app.config.globalProperties.$monitoringTools.setUserId(userData.id)
      return userData
    }
  }
})

3. 更新多个配置选项

如果需要同时更新多个配置选项：

// 使用updateOptions方法更新多个配置
proxy.$monitoringTools.updateOptions({
  userId: userData.id,
  appVersion: APP_VERSION,
  sampleRate: 0.8 // 增加采样率
})

注意事项

1. 设置用户ID后，后续所有的监控数据都会自动关联该用户ID
2. 用户退出登录时，考虑清除或重置用户ID：proxy.$monitoringTools.setUserId('')
3. 为了保护用户隐私，确保仅使用不包含敏感信息的用户标识符（如数据库ID或匿名标识符）

在组件中使用

插件注册后，可以在任何组件中通过$monitoringTools访问监控API：

<script setup lang="ts">
import { getCurrentInstance } from 'vue'

const { proxy } = getCurrentInstance()

// 手动上报自定义事件
function handleImportantAction() {
  // 执行操作...
  
  // 记录事件
  proxy.$monitoringTools.trackEvent('important_action', {
    actionId: 123,
    value: 'something important'
  })
}

// 手动上报错误
function handleCustomError(error: Error) {
  proxy.$monitoringTools.trackError(error, {
    componentName: 'SearchComponent',
    additionalInfo: 'Failed during search'
  })
}

// 设置用户ID（例如在用户登录后）
function onUserLogin(userId: string) {
  proxy.$monitoringTools.setUserId(userId)
}
</script>

全局API

插件也会在全局window对象上暴露一些API，方便在非组件代码中使用：

// 记录自定义事件
window.trackEvent('purchase_completed', {
  productId: 'prod-123',
  price: 99.99,
  currency: 'USD'
})

// 手动上报错误
window.trackError(new Error('Something went wrong'), {
  severity: 'high',
  context: 'payment-processing'
})

数据格式

插件收集的数据大致为以下格式：

{
  // 基础信息（所有数据类型通用）
  timestamp: 1620000000000,         // 时间戳
  url: 'https://example.com/page',  // 页面URL
  sessionId: 'xxxx-xxxx-xxxx-xxxx', // 会话ID
  userId: 'user-123',               // 用户ID（如果设置）
  appId: 'app-123',                 // 应用ID 
  appVersion: '1.0.0',              // 应用版本
  userAgent: '...',                 // 用户代理信息
  language: 'zh-CN',                // 用户语言
  screenSize: '1920x1080',          // 屏幕尺寸
  viewport: '1200x800',             // 视口尺寸
  
  // 根据事件类型不同，包含不同的额外数据
  type: 'performance',             // 数据类型（performance/error/behavior/custom_event等）
  eventName: 'page_load',          // 事件名称
  ...具体事件的详细数据
}

注意事项

1. 性能影响：监控代码会对应用性能产生一定影响，可以通过采样率来减轻
2. 数据安全：确保不收集敏感信息，特别是表单输入值
3. 服务器负载：设置合理的批量发送参数，避免过于频繁地发送小量数据
4. 合规性：根据当地法规（如GDPR、CCPA等）确保用户隐私保护
5. 兼容性：部分性能API在老旧浏览器中可能不可用，但插件会自动降级

故障排除

• 数据未发送：检查apiUrl配置是否正确
• 性能数据不完整：某些浏览器可能不支持所有性能API
• 控制台警告：查看是否有关于API不支持的警告信息

贡献

欢迎通过Issue或Pull Request贡献代码或提出建议。

许可证

MIT