whitch-frontend-monitor/README.md

前端监控系统 - 一个轻量级的前端监控SDK

# Trae 前端监控系统

Trae 是一个轻量级的前端监控系统SDK，提供了错误监控、性能监控、用户行为监控和网络请求监控等功能。

## 功能特点

- 🚀 错误监控：捕获JS运行时错误、Promise异常和资源加载错误
- 📊 性能监控：收集页面性能指标、资源加载性能和Web Vitals指标
- 👨‍💻 用户行为：跟踪用户点击、路由变化和控制台输出
- 🌐 网络监控：监控XHR和Fetch请求

## 安装

```bash
npm install whitch-frontend-monitor
```

## 使用方法

### 基础配置

```javascript
import { TraeMonitor } from 'trae';

// 初始化监控实例
const monitor = TraeMonitor.getInstance({
  appId: 'your-app-id',        // 应用ID
  userId: 'user-id',           // 可选，用户ID
  reportUrl: 'your-api-url',   // 数据上报地址
  autoTracker: true,           // 可选，是否自动采集（默认true）
  delay: 1000,                 // 可选，上报延迟（默认1000ms）
  ignoreUrls: [],             // 可选，忽略的URL列表
  sampleRate: 1,              // 可选，采样率（0-1之间，默认1）
  maxRetry: 3,                // 可选，最大重试次数（默认3）
  compression: true           // 可选，是否启用压缩（默认true）
});

// 获取监控数据
const errors = monitor.getErrors();             // 获取错误监控数据
const performance = monitor.getPerformanceData(); // 获取性能监控数据
const behaviors = monitor.getBehaviors();        // 获取用户行为数据
const network = monitor.getNetworkData();        // 获取网络请求监控数据

// 销毁监控实例
monitor.destroy();
```

### 数据格式

#### 错误监控数据
```typescript
interface ErrorInfo {
  type: string;           // 错误类型
  message: string;        // 错误信息
  stack?: string;         // 错误堆栈
  filename?: string;      // 发生错误的文件
  position?: string;      // 错误位置（行号、列号）
  timestamp: number;      // 错误发生时间戳
}
```

#### 性能监控数据
```typescript
interface PerformanceInfo {
  type: string;           // 性能指标类型
  value: number;          // 性能指标值
  timestamp: number;      // 采集时间戳
}
```

#### 用户行为数据
```typescript
interface BehaviorInfo {
  type: string;           // 行为类型
  target?: string;        // 操作目标
  pageUrl: string;        // 页面URL
  timestamp: number;      // 行为发生时间戳
  metadata?: any;         // 额外信息
}
```

#### 网络请求数据
```typescript
interface NetworkInfo {
  type: string;           // 请求类型（xhr/fetch）
  method: string;         // 请求方法
  url: string;           // 请求URL
  status: number;        // 状态码
  duration: number;      // 请求耗时
  success: boolean;      // 是否成功
  timestamp: number;     // 请求发起时间戳
  error?: string;        // 错误信息
  response?: any;        // 响应数据
}
```

## 注意事项

1. 确保在应用初始化时尽早调用 `TraeMonitor.getInstance()`
2. 根据实际需求配置采样率和上报延迟
3. 合理配置 ignoreUrls 以过滤不需要监控的请求
4. 在应用销毁时调用 `monitor.destroy()` 以清理资源

## License

MIT