@be-link/cls-logger 1.0.1-beta.20 → 1.0.1-beta.22

package/README.md

@@ -2,79 +2,86 @@
 
 腾讯云 CLS（`tencentcloud-cls-sdk-js-web` / `tencentcloud-cls-sdk-js-mini`）日志上报封装，支持 Web、H5 和小程序环境，提供统一的调用方式。
 
+## 特性
+
+- 自动环境适配（Web / H5 / 小程序）
+- 内存队列批量上报，减少网络请求
+- 页面关闭时 `sendBeacon` 保证日志不丢失
+- 支持浏览器空闲时上报（`requestIdleCallback`）
+- 错误即时上报，信息日志批量上报
+- 自动采集：请求监控、性能监控、错误监控、行为埋点
+- 失败重试 + 本地缓存兜底
+
 ## 安装
 
 ```bash
 pnpm add @be-link/cls-logger
 ```
 
-> **注意**：
->
-> 1. SDK 内部会自动根据运行环境加载对应的腾讯云 SDK（Web 或小程序），无需手动安装额外依赖。
-> 2. 如果业务对包体积有极致要求，建议使用**分环境引入方式**（见下文）。
+### 依赖说明
 
-## 使用
+| 入口                       | 依赖                                         | 说明                                |
+| -------------------------- | -------------------------------------------- | ----------------------------------- |
+| `@be-link/cls-logger`      | `tencentcloud-cls-sdk-js-web`                | 统一入口，自动适配环境              |
+| `@be-link/cls-logger/web`  | `tencentcloud-cls-sdk-js-web` + `web-vitals` | Web/H5 专用，含 Web Vitals 性能监控 |
+| `@be-link/cls-logger/mini` | `tencentcloud-cls-sdk-js-mini`               | 小程序专用                          |
 
-### 1. 统一引入方式（推荐快速接入）
+> **注意**：所有依赖已内置，无需手动安装。
 
-无需关心运行环境（Web 或 小程序），SDK 内部会自动识别并适配。此方式包含全量逻辑，支持动态加载 SDK。
+## 快速开始
+
+### 1. 统一引入方式（推荐快速接入）
 
 ```ts
 import clsLogger from '@be-link/cls-logger';
 
-// 初始化（建议在应用入口处调用）
 clsLogger.init({
   projectId: 'my-project',
   appId: 'my-app-id',
-  // 默认配置可不传
-  // tencentCloud: {
-  //   endpoint: 'https://ap-shanghai.cls.tencentcs.com',
-  //   topicID: '17475bcd-6315-4b20-859c-e7b087fb3683',
-  // },
   source: 'my-source',
 });
 ```
 
-### 2. 分环境引入方式（推荐生产环境使用）
+### 2. 分环境引入方式（推荐生产环境）
 
-为了获得更小的包体积（Tree Shaking）和更清晰的逻辑，建议根据项目类型引入不同的入口。此方式将物理隔离 Web 和小程序的特有逻辑（如 Web 的 `fetch` 拦截 vs 小程序的 `wx.request` 拦截）。
-
-#### Web / H5 项目：
+#### Web / H5：
 
 ```ts
-// 仅包含 Web 相关逻辑，不再包含小程序代码
 import { clsLogger } from '@be-link/cls-logger/web';
 
 clsLogger.init({
   projectId: 'my-web-project',
-  // tencentCloud: { ... }, // 可选
   source: 'web-source',
 });
 ```
 
-#### 小程序项目：
+#### 小程序：
 
 ```ts
-// 仅包含小程序相关逻辑，不再包含 Web 代码
 import { clsLogger } from '@be-link/cls-logger/mini';
 
 clsLogger.init({
   projectId: 'my-mini-project',
-  appId: 'wx123456789', // 小程序建议传入 appId
-  // tencentCloud: { ... }, // 可选
+  appId: 'wx123456789',
   source: 'mini-source',
 });
 ```
 
-## 常用 API
+## API
 
-### 开发日志
+### 日志方法
 
 ```ts
-// info / warn / error
+// 信息日志（走批量队列）
 clsLogger.info('应用启动', { startUpTime: 120 });
 
-// Error 日志（支持直接传入 Error 对象，自动解析堆栈）
+// 警告日志（走批量队列）
+clsLogger.warn('资源加载慢', { duration: 3000 });
+
+// 错误日志（默认即时上报）
+clsLogger.error('支付失败', { orderId: '123' });
+
+// Error 对象（自动解析堆栈）
 try {
   doSomething();
 } catch (err) {
@@ -82,7 +89,17 @@ try {
 }
 ```
 
-### 自定义埋点 (Track)
+### 即时上报选项
+
+```ts
+// info/warn 强制即时上报
+clsLogger.info('重要事件', { data: 1 }, { immediate: true });
+
+// error 走批量队列（默认是即时上报）
+clsLogger.error('非关键错误', { data: 1 }, { immediate: false });
+```
+
+### 自定义埋点
 
 ```ts
 clsLogger.track('click_event', {
@@ -91,9 +108,7 @@ clsLogger.track('click_event', {
 });
 ```
 
-### 统计埋点 (Stat)
-
-用于简单的计数/分布统计。
+### 统计埋点
 
 ```ts
 clsLogger.stat({
@@ -104,67 +119,245 @@ clsLogger.stat({
 });
 ```
 
-## 功能特性
+## 配置项
 
-### 1. 自动环境适配
+### 完整配置示例
 
-- **Web / H5**: 自动采集浏览器环境信息（UserAgent、屏幕尺寸、网络状态等）。
-- **小程序**: 自动采集小程序环境信息（系统信息、微信版本、网络类型等）。
+```ts
+clsLogger.init({
+  // 基础配置
+  enabled: true, // 是否启用，默认 true
+  projectId: 'my-project', // 项目标识
+  appId: 'wx123456789', // 应用 ID（小程序必填）
+  appVersion: '1.0.0', // 应用版本
+  source: 'my-source', // CLS source
+
+  // 腾讯云 CLS 配置
+  tencentCloud: {
+    endpoint: 'https://ap-shanghai.cls.tencentcs.com',
+    topicID: 'your-topic-id',
+    retry_times: 3,
+  },
 
-### 2. 请求监控 (Request Monitor)
+  // 批量上报配置
+  batch: {
+    maxSize: 50, // 队列达到此数量立即发送，默认 20
+    intervalMs: 1000, // 定时批量发送间隔，默认 500ms
+    startupDelayMs: 3000, // 启动合并窗口，默认 0（不启用）
+    useIdleCallback: true, // 使用浏览器空闲时间上报，默认 false
+    idleTimeout: 3000, // 空闲回调超时时间，默认 3000ms
+  },
 
-默认开启。
+  // 请求监控配置
+  requestMonitor: {
+    enabled: true, // 是否开启，默认 true
+    sampleRate: 1, // 采样率 0~1，默认 1
+    ignoreUrls: [/localhost/], // 忽略的 URL
+    includeMethod: true, // 是否携带 method，默认 true
+    includeQuery: true, // 是否携带 query，默认 true
+    includeBody: true, // 是否携带 body，默认 true
+    maxParamLength: 2000, // 参数最大长度，默认 2000
+  },
+
+  // 错误监控配置
+  errorMonitor: {
+    enabled: true, // 是否开启，默认 true
+    sampleRate: 1, // 采样率 0~1，默认 1
+    captureResourceError: true, // 是否采集资源加载错误，默认 true
+    maxTextLength: 4000, // stack/message 最大长度，默认 4000
+    dedupeWindowMs: 3000, // 错误去重窗口，默认 3000ms
+    dedupeMaxKeys: 200, // 去重缓存最大 key 数，默认 200
+    ignoreMessages: [
+      // 忽略的错误信息（默认值）
+      'Script error.',
+      'Script error',
+      /^ResizeObserver loop/,
+      'Permission was denied',
+    ],
+  },
+
+  // 性能监控配置
+  performanceMonitor: {
+    enabled: true, // 是否开启，默认 true
+    sampleRate: 1, // 采样率 0~1，默认 1
+    webVitals: true, // 是否采集 Web Vitals（含 TTFB），默认 true
+    resourceTiming: true, // 是否采集资源加载耗时，默认 true
+    ignoreUrls: [/localhost/], // 忽略的资源 URL
+    maxTextLength: 2000, // 性能指标文本最大长度，默认 2000
+  },
+
+  // 行为埋点配置
+  behaviorMonitor: {
+    enabled: true, // 是否开启，默认 true
+    pv: true, // PV 是否开启，默认 true
+    uv: true, // UV 是否开启，默认 true
+    click: true, // 点击是否开启，默认 true
+    sampleRate: 1, // 采样率 0~1，默认 1
+    uvExpireDays: 30, // UV 标识过期天数，默认 30
+    clickTrackIdAttr: 'data-track-id', // 点击元素埋点标识属性名
+    clickMaxTextLength: 120, // 点击文本最大长度，默认 120
+  },
+
+  // 设备信息配置
+  deviceInfo: {
+    enabled: true, // 是否开启，默认 true
+    includeUserAgent: true, // 是否包含 UA，默认 true
+    includeNetwork: true, // 是否包含网络信息，默认 true
+  },
 
-- **Web**: 拦截 `fetch` / `XMLHttpRequest`。
-- **小程序**: 拦截 `wx.request` / `wx.cloud.callFunction`。
+  // 自定义基础字段
+  generateBaseFields: () => ({
+    userId: getUserId(),
+    userName: getUserName(),
+    environment: 'production',
+  }),
+});
+```
+
+## 常见场景配置
 
-### 3. 性能监控 (Performance Monitor)
+### 场景 1：首屏请求过多
 
-默认开启。
+页面首次加载时日志请求过多，影响其他请求：
+
+```ts
+clsLogger.init({
+  batch: {
+    startupDelayMs: 3000, // 启动 3 秒内的日志合并发送
+    maxSize: 100, // 提高队列阈值
+    intervalMs: 1000, // 延长批量间隔
+    useIdleCallback: true, // 使用浏览器空闲时间上报
+  },
+});
+```
 
-- **Web**: 采集 FCP, LCP, CLS, FID 等 Core Web Vitals 及资源加载耗时。
-- **小程序**: 支持采集页面首屏渲染耗时 (`firstRender`)、路由切换耗时 (`route`) 及启动耗时 (`appLaunch`)。
+### 场景 2：减少资源监控日志
 
-### 4. 行为埋点 (Behavior Monitor)
+开发环境资源过多，或生产环境不需要全量资源监控：
 
-默认开启，支持 PV (Page View) 和 UV (User View) 自动上报。
+```ts
+clsLogger.init({
+  performanceMonitor: {
+    resourceTiming: false, // 关闭资源监控
+    // 或者采样
+    // sampleRate: 0.1,      // 10% 采样
+    // 或者过滤
+    // ignoreUrls: [/localhost/, /node_modules/],
+  },
+});
+```
 
-- **UV ID**: 自动生成并持久化。小程序环境下优先尝试使用 `openid`。
-- **点击追踪**: 自动监听点击事件。
-  - **Web**: 识别带 `data-track-id` 的元素。
-    ```html
-    <!-- HTML -->
-    <button data-track-id="submit_btn">提交</button>
-    ```
-  - **小程序**: 识别带 `data-track-id` 的组件（需在 `dataset` 中）。
-    ```html
-    <!-- WXML -->
-    <button data-track-id="submit_btn" bindtap="handleClick">提交</button>
-    ```
+### 场景 3：过滤无意义的错误
 
-## 高级用法
+过滤第三方 SDK 的跨域错误：
 
-### 内存队列与批量发送
+```ts
+clsLogger.init({
+  errorMonitor: {
+    ignoreMessages: [
+      // 默认规则
+      'Script error.',
+      'Script error',
+      /^ResizeObserver loop/,
+      'Permission was denied',
+      // 自定义规则
+      /火山SDK/,
+      /VolcEngine/,
+      /network error/i,
+    ],
+  },
+});
+```
 
-SDK 默认开启内存队列，每 500ms 或达到 20 条日志时自动批量上报，以减少网络请求次数。可通过 `batch` 参数配置：
+### 场景 4：高并发场景（直播间）
 
 ```ts
 clsLogger.init({
   batch: {
-    maxSize: 20,
-    intervalMs: 500,
-    startupDelayMs: 1000, // 启动阶段合并窗口
+    maxSize: 100, // 提高队列阈值
+    intervalMs: 2000, // 延长批量间隔
+    useIdleCallback: true, // 空闲时上报
+  },
+  performanceMonitor: {
+    resourceTiming: false, // 关闭资源监控
+  },
+  requestMonitor: {
+    sampleRate: 0.1, // 请求监控采样 10%
   },
 });
 ```
 
-### 失败重试与本地缓存
+## 功能说明
+
+### 1. 批量上报机制
+
+SDK 使用内存队列批量上报日志：
+
+| 触发条件 | 说明                                                   |
+| -------- | ------------------------------------------------------ |
+| 队列满   | 达到 `maxSize` 立即发送                                |
+| 定时器   | 每 `intervalMs` 毫秒发送一次                           |
+| 页面关闭 | `visibilitychange` + `pagehide` 触发 `sendBeacon` 发送 |
+| 启动合并 | `startupDelayMs` 窗口内的日志尽量合并                  |
+
+### 2. 即时上报 vs 批量上报
+
+| 方法      | 默认行为 | 说明                                                     |
+| --------- | -------- | -------------------------------------------------------- |
+| `error()` | 即时上报 | 错误需要及时发现，可通过 `{ immediate: false }` 改为批量 |
+| `info()`  | 批量上报 | 可通过 `{ immediate: true }` 改为即时                    |
+| `warn()`  | 批量上报 | 可通过 `{ immediate: true }` 改为即时                    |
+| `track()` | 批量上报 | -                                                        |
+
+### 3. 页面关闭保障
 
-上报失败的日志会自动进入重试流程（指数退避算法）。若多次重试仍失败，日志会落盘到本地缓存（`localStorage` 或小程序 `Storage`），在下次应用启动时尝试重新上报。
+页面关闭时（`visibilitychange` / `pagehide`），SDK 会：
 
-### 手动注入 SDK
+1. 使用 `navigator.sendBeacon` 同步发送队列中的日志
+2. 如果 `sendBeacon` 不可用，将日志缓存到本地存储
+3. 下次启动时自动重试发送缓存的日志
 
-在某些特殊构建环境（如某些不允许动态 require 的小程序框架）下，可以手动注入：
+### 4. 失败重试机制
+
+- 上报失败后使用指数退避算法重试
+- 多次重试仍失败，日志落盘到本地缓存
+- 下次应用启动时自动尝试重新上报
+- 本地缓存最多保留 200 条（可配置 `failedCacheMax`）
+
+### 5. 自动采集内容
+
+#### 请求监控
+
+- **Web**: 拦截 `fetch` / `XMLHttpRequest`
+- **小程序**: 拦截 `wx.request` / `wx.cloud.callFunction`
+
+#### 性能监控
+
+- **Web**: 使用 [Google web-vitals](https://github.com/GoogleChrome/web-vitals) 库实现
+  - **FCP** (First Contentful Paint): 首次内容渲染
+  - **LCP** (Largest Contentful Paint): 最大内容渲染（用户交互后自动停止）
+  - **CLS** (Cumulative Layout Shift): 累积布局偏移（5秒会话窗口算法）
+  - **INP** (Interaction to Next Paint): 交互到绘制延迟（替代 FID）
+  - **TTFB** (Time to First Byte): 首字节时间
+  - **资源加载耗时**: PerformanceResourceTiming
+  - 自动处理 BFCache 恢复时的指标重置
+  - 上报数据包含 `rating` 字段：`'good'` | `'needs-improvement'` | `'poor'`
+- **小程序**: 首屏渲染、路由切换、启动耗时
+
+#### 错误监控
+
+- **Web**: `window.onerror`, `unhandledrejection`, 资源加载错误
+- **小程序**: `wx.onError`, `wx.onUnhandledRejection`, `App.onError`
+
+#### 行为埋点
+
+- **PV**: 页面访问
+- **UV**: 用户访问（自动生成持久化 ID）
+- **点击**: 带 `data-track-id` 属性的元素点击
+
+## 手动注入 SDK
+
+在某些特殊构建环境下，可以手动注入 SDK：
 
 ```ts
 import { clsLogger } from '@be-link/cls-logger/mini';
@@ -172,6 +365,25 @@ import * as MiniSdk from 'tencentcloud-cls-sdk-js-mini';
 
 clsLogger.init({
   tencentCloud: { topicID: 'xxx', endpoint: 'xxx' },
-  sdk: MiniSdk, // 手动传入 SDK 实例
+  sdk: MiniSdk,
 });
 ```
+
+## 类型定义
+
+```ts
+import type {
+  ClsLoggerInitOptions,
+  BatchOptions,
+  ReportOptions,
+  RequestMonitorOptions,
+  ErrorMonitorOptions,
+  PerformanceMonitorOptions,
+  BehaviorMonitorOptions,
+  DeviceInfoOptions,
+} from '@be-link/cls-logger';
+```
+
+## License
+
+MIT