@mtn-ui-z/monitor 0.0.1

package/README.md

@@ -0,0 +1,344 @@
+# @mtn-ui-z/monitor
+
+前端监控 SDK，用于监控前端错误、性能、PV、API 请求、用户行为等数据。
+
+## 功能特性
+
+- **错误监控** - JS 错误、Promise 未捕获异常、资源加载失败、Vue 组件错误
+- **性能监控** - FP/FCP/LCP/FID/CLS/TTI/TTFB/DNS/TCP 等关键性能指标
+- **PV 监控** - 自动监听路由变化，支持 SPA 应用
+- **API 监控** - 拦截 fetch/XMLHttpRequest，记录请求耗时、状态码、接口报错
+- **用户行为监控** - 点击事件、滚动行为、页面可见性变化
+- **自定义事件** - 支持手动埋点上报自定义事件
+- **长任务监控** - Long Task、内存使用情况
+- **采样控制** - 支持采样率配置
+- **多种上报方式** - 支持 sendBeacon、fetch、自定义上报函数
+
+## 安装
+
+```bash
+pnpm add @mtn-ui-z/monitor
+```
+
+## 快速开始
+
+### Vue 插件方式
+
+```ts
+import { createApp } from 'vue'
+import { MtnMonitor } from '@mtn-ui-z/monitor'
+import App from './App.vue'
+
+const app = createApp(App)
+
+app.use(MtnMonitor, {
+  reportUrl: 'https://your-api.com/monitor',
+  appId: 'my-app',
+  env: 'production',
+  sampleRate: 1,
+})
+
+app.mount('#app')
+```
+
+### 手动初始化
+
+```ts
+import { monitor } from '@mtn-ui-z/monitor'
+
+monitor.init({
+  reportUrl: 'https://your-api.com/monitor',
+  appId: 'my-app',
+  env: 'production',
+})
+
+// 手动上报错误
+try {
+  // your code
+} catch (error) {
+  monitor.reportError(error as Error)
+}
+```
+
+### Vue 组件中使用
+
+```ts
+import { getCurrentInstance } from 'vue'
+
+export default {
+  setup() {
+    const { proxy } = getCurrentInstance()
+
+    // 使用 $monitor
+    proxy.$monitor.reportError(new Error('xxx'))
+
+    // 或使用 provide/inject
+    const monitor = inject('monitor')
+  }
+}
+```
+
+## 配置选项
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `reportUrl` | `string` | - | 上报地址 |
+| `appId` | `string` | - | 应用标识 |
+| `env` | `'development' \| 'production' \| 'test'` | `'production'` | 环境 |
+| `errorEnabled` | `boolean` | `true` | 是否启用错误监控 |
+| `performanceEnabled` | `boolean` | `true` | 是否启用性能监控 |
+| `pvEnabled` | `boolean` | `true` | 是否启用 PV 监控 |
+| `apiEnabled` | `boolean` | `true` | 是否启用 API 监控 |
+| `behaviorEnabled` | `boolean` | `false` | 是否启用用户行为监控 |
+| `longTaskEnabled` | `boolean` | `false` | 是否启用长任务监控 |
+| `sampleRate` | `number` | `1` | 采样率 (0-1) |
+| `report` | `(data: MonitorData) => void` | - | 自定义上报函数 |
+
+## 上报数据结构
+
+### 错误数据 (ErrorData)
+
+```json
+{
+  "type": "error",
+  "errorType": "js",
+  "message": "Error message",
+  "stack": "Error stack...",
+  "url": "https://example.com/page",
+  "line": 10,
+  "column": 5,
+  "userId": "user123",
+  "timestamp": 1699999999999,
+  "appId": "my-app",
+  "env": "production"
+}
+```
+
+### 性能数据 (PerformanceData)
+
+```json
+{
+  "type": "performance",
+  "metric": "fcp",
+  "value": 1200,
+  "url": "https://example.com/page",
+  "timestamp": 1699999999999,
+  "appId": "my-app",
+  "env": "production"
+}
+```
+
+### PV 数据 (PvData)
+
+```json
+{
+  "type": "pv",
+  "url": "https://example.com/page",
+  "referrer": "https://example.com/other",
+  "userId": "user123",
+  "timestamp": 1699999999999,
+  "appId": "my-app",
+  "env": "production"
+}
+```
+
+### API 数据 (ApiData)
+
+```json
+{
+  "type": "api",
+  "url": "https://example.com/api/user",
+  "method": "GET",
+  "status": 200,
+  "duration": 120,
+  "success": true,
+  "timestamp": 1699999999999,
+  "appId": "my-app",
+  "env": "production"
+}
+```
+
+### 用户行为数据 (BehaviorData)
+
+```json
+{
+  "type": "behavior",
+  "behaviorType": "click",
+  "element": "button",
+  "text": "提交",
+  "path": "div > form > button",
+  "x": 100,
+  "y": 50,
+  "timestamp": 1699999999999,
+  "appId": "my-app",
+  "env": "production"
+}
+```
+
+### 自定义事件数据 (CustomData)
+
+```json
+{
+  "type": "custom",
+  "eventName": "button_click",
+  "data": { "buttonId": "submit-btn" },
+  "url": "https://example.com/page",
+  "timestamp": 1699999999999,
+  "appId": "my-app",
+  "env": "production"
+}
+```
+
+### 长任务数据 (LongTaskData)
+
+```json
+{
+  "type": "longtask",
+  "taskType": "longTask",
+  "duration": 120,
+  "attribution": "script",
+  "url": "https://example.com/page",
+  "timestamp": 1699999999999,
+  "appId": "my-app",
+  "env": "production"
+}
+```
+
+## API
+
+### monitor.init(options)
+
+初始化监控 SDK。
+
+### monitor.reportError(error, errorType?)
+
+手动上报错误。
+
+- `error` - Error 对象
+- `errorType` - 错误类型 `'js' | 'resource' | 'promise' | 'vue'`
+
+### monitor.reportPerformance(metric, value)
+
+手动上报性能数据。
+
+- `metric` - 指标类型 `'page' | 'resource' | 'fcp' | 'fp' | 'lcp' | 'fid' | 'cls' | 'tti' | 'ttfb' | 'dns' | 'tcp' | 'download'`
+- `value` - 指标值 (ms)
+
+### monitor.reportCustomEvent(eventName, eventData?)
+
+手动上报自定义事件。
+
+- `eventName` - 事件名称
+- `eventData` - 事件数据对象
+
+### monitor.reportPv()
+
+手动上报页面访问。
+
+### monitor.setUserId(userId)
+
+设置用户 ID。
+
+### monitor.destroy()
+
+销毁监控实例。
+
+## 配合后端使用
+
+监控 SDK 上报的数据为 JSON 格式，后端只需提供一个 POST 接口即可接收：
+
+```ts
+// 示例: Express 接口
+app.post('/api/monitor', (req, res) => {
+  const data = req.body
+  console.log('[Monitor]', data.type, data)
+
+  // 存储到数据库或发送到日志服务
+  saveToDatabase(data)
+
+  res.json({ success: true })
+})
+```
+
+## Vue 错误捕获
+
+在 Vue 3 中使用 app.config.errorHandler 配合监控：
+
+```ts
+import { createApp } from 'vue'
+import { MtnMonitor, monitor } from '@mtn-ui-z/monitor'
+import App from './App.vue'
+
+const app = createApp(App)
+
+app.use(MtnMonitor, {
+  reportUrl: 'https://your-api.com/monitor',
+})
+
+// Vue 全局错误处理（可选，插件已自动处理）
+app.config.errorHandler = (err, instance, info) => {
+  console.error('Vue Error:', err, info)
+  // 错误已通过 ErrorMonitor 自动上报
+}
+
+app.mount('#app')
+```
+
+## 用户行为监控
+
+启用用户行为监控后，会自动采集以下数据：
+
+### 点击事件
+
+```json
+{
+  "type": "behavior",
+  "behaviorType": "click",
+  "element": "button",
+  "text": "提交订单",
+  "path": "div > form > button.submit-btn",
+  "x": 200,
+  "y": 100
+}
+```
+
+可通过 `data-monitor-id` 或 `data-monitor-label` 属性添加自定义标识：
+
+```html
+<button data-monitor-id="submit-btn" data-monitor-label="提交订单">
+  提交
+</button>
+```
+
+### 滚动事件
+
+```json
+{
+  "type": "behavior",
+  "behaviorType": "scroll",
+  "scrollTop": 500,
+  "scrollPercent": 50
+}
+```
+
+### 页面可见性
+
+```json
+{
+  "type": "behavior",
+  "behaviorType": "pageHide"
+}
+```
+
+## 浏览器兼容性
+
+- Chrome 80+
+- Firefox 75+
+- Safari 14+
+- Edge 80+
+
+需要浏览器支持以下 API：
+- Performance Observer
+- Promise.prototype.finally
+- fetch / navigator.sendBeacon
+- Long Task API (可选，内存监控需要)