@pluve/logger-sdk 0.0.4 → 0.0.6

package/README.md

@@ -2,47 +2,54 @@
 
 ## 简介
 
-- 轻量级前端日志采集 SDK，支持 H5 浏览器环境
+- 轻量级前端日志采集 SDK，支持 H5 浏览器环境和微信小程序
 - 使用 Beacon 和像素图（Image）方式上报，确保兼容性与可靠性
 - 标准化日志格式，易于分析和处理
+- 支持批量上报、异常重试、持久化存储等高级功能
 
 ## 安装与引入
 
 - 安装：`pnpm add @pluve/logger-sdk`
-- ESM：`import { LoggerSDK } from '@pluve/logger-sdk'`
+- ESM：`import LoggerSDK from '@pluve/logger-sdk'`
 - UMD：构建后全局为 `LoggerSDK`
 
-## 快速开始
+## 快速开始（单例 + init）
 
 ```ts
-import { LoggerSDK } from '@pluve/logger-sdk';
+import LoggerSDK from '@pluve/logger-sdk';
 
-const sdk = new LoggerSDK({
+// 推荐使用单例
+const sdk = LoggerSDK.getInstance();
+sdk.init({
   endpoint: '/api/log',
   appId: 'web-shop',
   env: 'prod', // prod/stage/dev
   debug: true,
+  // 默认批量关闭，如需开启：
+  // enableBatch: true,
 });
 
+// init 会自动上报一次 'session_start'，携带环境信息（UA/OS/屏幕等）
+// 后续事件默认不再合并环境标签（节省流量）
+
 // 记录错误日志
-sdk.track('error', 'TypeError: Cannot read property', {
+await sdk.track('error', 'TypeError: Cannot read property', undefined, {
   level: 'error',
   stack: 'Error stack trace...',
   userId: '123',
   tags: {
     component: 'checkout',
-    browser: 'Chrome 120',
   },
 });
 
 // 记录带 traceId 的错误（用于关联多个日志）
-sdk.track('error', 'Request failed', 'trace-abc-123', {
+await sdk.track('error', 'Request failed', 'trace-abc-123', {
   level: 'error',
   tags: { api: '/api/user' },
 });
 
 // 记录自定义事件
-sdk.track('custom', 'User clicked button', {
+await sdk.track('custom', 'User clicked button', undefined, {
   level: 'info',
   tags: { action: 'click', button: 'submit' },
 });
@@ -56,7 +63,7 @@ sdk.track('custom', 'User clicked button', {
 {
   "logId": "550e8400-e29b-41d4-a716-446655440000",  // 日志 ID（UUID v4）
   "traceId": "trace-123456",    // 可选：追踪 ID（用于关联多个日志）
-  "eventType": "error",          // 固定：error/crash/pageview/custom
+  "eventType": "error",          // 固定：error/crash/pageview/custom/session_start
   "ts": 1690000000000,           // 毫秒时间戳
   "appId": "web-shop",           // 应用标识
   "env": "prod",                 // prod/stage/dev
@@ -75,20 +82,48 @@ sdk.track('custom', 'User clicked button', {
 
 ## API
 
-### `new LoggerSDK(options: SDKOptions)`
+### 单例与初始化
+
+#### `LoggerSDK.getInstance(): LoggerSDK`
+
+获取全局唯一实例。
+
+#### `init(options: SDKOptions)`
+
+初始化 SDK、生成并锁定 sessionId、收集环境信息并上报一次 `session_start`。
+注意：锁定的 sessionId 将在销毁前用于所有日志上报。
 
-创建 SDK 实例。
+#### `new LoggerSDK(options?: SDKOptions)`
+
+创建 SDK 实例；如果传入 `options`，会在构造时自动调用 `init(options)`。
 
 **配置项：**
 
 ```typescript
 interface SDKOptions {
   endpoint: string; // 上报端点 URL（必选）
-  appId?: string; // 应用 ID，默认 'unknown'
+  appId: string; // 应用 ID（必选）
   env?: Env; // 环境标识：prod/stage/dev，默认 'dev'
   debug?: boolean; // 是否开启调试模式
   pixelParam?: string; // 像素上报参数名，默认 'data'
   maxPixelUrlLen?: number; // 像素上报 URL 最大长度，默认 1900
+  enableGzip?: boolean; // 是否启用 gzip（传输适配器内部处理）
+  
+  // 批量上报配置
+  enableBatch?: boolean; // 是否启用批量上报，默认 false（需显式开启）
+  batchSize?: number; // 批量上报最大数量，默认 10
+  batchInterval?: number; // 批量上报时间间隔（毫秒），默认 5000
+  maxQueueSize?: number; // 队列最大长度，默认 100
+  
+  // 持久化存储配置
+  enableStorage?: boolean; // 是否启用持久化存储，默认 true
+  storagePrefix?: string; // 持久化存储的 key 前缀，默认 'logger_sdk'
+  
+  // 重试配置
+  enableRetry?: boolean; // 是否启用重试，默认 true
+  maxRetries?: number; // 最大重试次数，默认 3
+  retryDelay?: number; // 重试基础延迟时间（毫秒），默认 1000
+  retryBackoff?: boolean; // 是否使用指数退避策略，默认 true
 }
 ```
 
@@ -158,10 +193,30 @@ sdk.track('error', 'Request failed', traceId, {
 
 设置用户 ID（用于后续日志关联）。
 
+### `trace(error: Error | string, options?)`
+
+错误专用方法，自动设置 `eventType: 'error'` 与 `level: 'error'`，不合并环境标签。
+
+```ts
+try {
+  throw new Error('Network Error');
+} catch (e) {
+  await sdk.trace(e as Error, { userId: 'u123', traceId: 'req-1' });
+}
+```
+
 ### `destroy()`
 
 销毁 SDK 实例，停止所有监听。
 
+销毁后单例会被清理；如需新会话，重新调用 `init()` 即可生成新的 sessionId。
+
+### 会话管理
+
+- 在 `init()` 时生成并锁定 `sessionId`
+- 在调用 `destroy()` 前，所有日志都会使用该 `sessionId`
+- 重新 `init()` 将开始新的会话（新的 `sessionId`）
+
 ## 自动采集
 
 SDK 会自动监听以下页面事件并上报：
@@ -189,6 +244,12 @@ SDK 使用两种上报方式，按优先级自动选择：
 
 如果 Beacon 失败，会自动降级到 Image 方式。
 
+### 微信小程序适配器
+
+- 环境：微信小程序
+- 支持：请求成功/失败/非 2xx 状态码与超时控制
+- Header Content-Type 会根据是否启用 gzip 自动调整
+
 ## 使用场景
 
 ### 错误监控
@@ -263,3 +324,178 @@ const sdk = new LoggerSDK({
   debug: true, // 开启调试
 });
 ```
+
+## 高级功能
+
+### 批量上报
+
+SDK 支持批量上报功能，可以显著减少网络请求次数，提高性能：
+
+- **队列缓存**：日志先缓存到内存队列，达到条件后批量发送
+- **智能触发**：支持按数量阈值和时间间隔触发上报
+- **手动控制**：提供 `flush()` 方法可手动立即上报
+
+### 异常重试
+
+为确保日志可靠上报，SDK 提供了自动重试机制：
+
+- **自动重试**：上报失败时自动重试（默认最多3次）
+- **指数退避**：采用指数退避策略（1秒→2秒→4秒...）
+- **随机抖动**：添加0-30%随机延迟避免惊群效应
+
+### 持久化存储
+
+为了防止因页面意外关闭导致日志丢失，SDK 支持持久化存储：
+
+- **自动保存**：队列数据自动保存到 localStorage（浏览器）或 Storage（微信小程序）
+- **自动恢复**：页面刷新后自动恢复未上报的日志
+
+## 核心流程
+
+```mermaid
+graph TB
+    A[用户调用 track() 方法] --> B{SDK是否已销毁?}
+    B -- 是 --> C[直接返回，不处理]
+    B -- 否 --> D[生成标准化日志对象]
+    D --> E{是否启用批量上报?}
+    E -- 否 --> F[直接上报日志]
+    E -- 是 --> G[将日志加入队列]
+    G --> H{队列大小是否达到批处理阈值?}
+    H -- 是 --> I[立即触发批量上报]
+    H -- 否 --> J[等待下次触发]
+    
+    F --> K{是否启用重试机制?}
+    K -- 是 --> L[使用重试管理器发送]
+    K -- 否 --> M[直接发送请求]
+    
+    L --> N[重试管理器执行发送任务]
+    N --> O{发送是否成功?}
+    O -- 是 --> P[上报完成]
+    O -- 否 --> Q[是否达到最大重试次数?]
+    Q -- 否 --> R[计算延迟时间<br/>（指数退避+随机抖动）]
+    R --> S[等待后重试]
+    S --> N
+    Q -- 是 --> T[上报失败，记录错误]
+    
+    M --> U{发送是否成功?}
+    U -- 是 --> P
+    U -- 否 --> T
+    
+    I --> V[执行批量上报]
+    V --> W[从队列获取待发送日志]
+    W --> X[调用重试管理器发送批量日志]
+    X --> Y{批量发送是否成功?}
+    Y -- 是 --> Z[从队列中移除已发送日志]
+    Y -- 否 --> AA[保留队列中的日志，下次重试]
+    
+    J --> AB{定时器是否触发?}
+    AB -- 是 --> AC[执行批量上报]
+    AB -- 否 --> AD{页面是否卸载?}
+    AD -- 是 --> AE[调用 flush() 方法上报所有日志]
+    
+    subgraph 队列管理
+        AF[内存队列]
+        AG[持久化存储<br/>localStorage/Storage]
+        AF <--> AG
+    end
+    
+    subgraph 传输适配器
+        AH[Beacon 适配器]
+        AI[Image 像素适配器]
+        AJ[微信小程序适配器]
+        AK[自动选择最佳适配器]
+        AH --> AK
+        AI --> AK
+        AJ --> AK
+    end
+    
+    Z --> P
+    AA --> P
+    AC --> V
+    AE --> V
+```
+
+## 使用示例
+
+### 基础使用（默认启用所有高级功能）
+
+```typescript
+import { LoggerSDK } from '@pluve/logger-sdk';
+
+const sdk = new LoggerSDK({
+  endpoint: 'https://your-api.com/logs',
+  appId: 'my-app',
+  env: 'prod',
+  debug: false,
+});
+
+// 记录错误日志
+sdk.track('error', 'TypeError: Cannot read property', {
+  level: 'error',
+  stack: 'Error stack trace...',
+  userId: '123',
+  tags: {
+    component: 'checkout',
+    browser: 'Chrome 120',
+  },
+});
+```
+
+### 批量上报配置
+
+```typescript
+const sdk = new LoggerSDK({
+  endpoint: 'https://your-api.com/logs',
+  appId: 'my-app',
+  
+  // 批量上报配置
+  enableBatch: true,     // 启用批量上报
+  batchSize: 20,         // 队列达到20条时批量上报
+  batchInterval: 10000,  // 或每隔10秒上报一次
+  maxQueueSize: 100,     // 队列最大100条日志
+  
+  // 持久化存储配置
+  enableStorage: true,   // 启用持久化存储
+  storagePrefix: 'my_app_logger',
+});
+```
+
+### 重试机制配置
+
+```typescript
+const sdk = new LoggerSDK({
+  endpoint: 'https://your-api.com/logs',
+  appId: 'my-app',
+  
+  // 重试配置
+  enableRetry: true,     // 启用重试机制
+  maxRetries: 5,         // 最多重试5次
+  retryDelay: 2000,      // 基础延迟2秒
+  retryBackoff: true,    // 启用指数退避
+});
+```
+
+### 手动刷新队列
+
+```typescript
+// 立即上报所有待发送日志
+await sdk.flush();
+```
+
+### 禁用批量上报（实时上报）
+
+```typescript
+const sdk = LoggerSDK.getInstance();
+sdk.init({
+  endpoint: 'https://your-api.com/logs',
+  appId: 'my-app',
+  enableBatch: false, // 默认即为 false；每条日志立即发送
+  enableRetry: true,
+});
+```
+
+## 重要说明
+
+- `init()` 会自动上报 `session_start`，携带环境信息标签（仅此一次）
+- 普通事件默认不合并环境标签，建议仅在必要时通过 `tags` 传入额外信息
+- 推荐使用 `LoggerSDK.getInstance()` 获取单例，避免多实例重复初始化

package/dist/index.d.ts

@@ -4,3 +4,7 @@ export type { TransportAdapter, TransportOptions } from './transportAdapter';
 export type { SDKOptions, LogEvent, LogEventType, LogEventLevel, Env } from './types';
 export type { PlatformType, EnvironmentInfo } from './utils';
 export { getEnvironmentInfo, parseBrowserInfo, isWeChatMiniProgram, gzipCompress, isGzipSupported } from './utils';
+export { QueueManager } from './queueManager';
+export type { QueueOptions } from './queueManager';
+export { RetryManager } from './retryManager';
+export type { RetryOptions } from './retryManager';

package/dist/index.js

@@ -2,10 +2,12 @@
  * @Author       : 黄震 huangzhen@yfpharmacy.com
  * @Date         : 2025-11-21 14:25:26
  * @LastEditors  : 黄震 huangzhen@yfpharmacy.com
- * @LastEditTime : 2025-12-04 15:56:03
+ * @LastEditTime : 2025-12-18 13:26:30
  * @Description  : 描述
  * Copyright (c) 2025 by 益丰大药房连锁股份有限公司, All Rights Reserved.
  */
 export { LoggerSDK } from "./loggerSDK";
 export { defaultTransport, TransportAdapters } from "./transportAdapter";
-export { getEnvironmentInfo, parseBrowserInfo, isWeChatMiniProgram, gzipCompress, isGzipSupported } from "./utils";
+export { getEnvironmentInfo, parseBrowserInfo, isWeChatMiniProgram, gzipCompress, isGzipSupported } from "./utils";
+export { QueueManager } from "./queueManager";
+export { RetryManager } from "./retryManager";

package/dist/loggerSDK.d.ts

@@ -1,11 +1,29 @@
 import { SDKOptions, LogEventType, LogEventLevel } from './types';
 export declare class LoggerSDK {
-    private opts;
+    private static instance;
+    private opts?;
     private seq;
     private closed;
-    /** 预收集的环境信息 tags */
+    /** 预收集的环境信息 tags（仅用于初始化上报） */
     private envTags;
-    constructor(options: SDKOptions);
+    /** 是否已初始化 */
+    private initialized;
+    /** 初始化时生成并锁定的会话标识 */
+    private sessionId;
+    /** 队列管理器 */
+    private queueManager?;
+    /** 重试管理器 */
+    private retryManager?;
+    /** 批量上报定时器 */
+    private batchTimer?;
+    /** 是否正在上报 */
+    private isSending;
+    constructor(options?: SDKOptions);
+    static getInstance(): LoggerSDK;
+    /**
+     * 初始化：配置参数、收集环境信息与 UA，并生成 sessionId，完成初始上报
+     */
+    init(options: SDKOptions): void;
     private logDebug;
     /**
      * 收集环境信息并生成 tags（仅在初始化时执行一次）
@@ -24,10 +42,26 @@ export declare class LoggerSDK {
      * 设置用户信息
      */
     identify(userId: string): void;
+    /**
+     * 手动刷新队列，立即上报所有待发送日志
+     */
+    flush(): Promise<void>;
     /**
      * 销毁实例
      */
-    destroy(): void;
+    destroy(): Promise<void>;
+    /**
+     * 发送单个事件（带重试）
+     */
+    private sendEvent;
+    /**
+     * 批量发送事件（带重试）
+     */
+    private sendBatch;
+    /**
+     * 启动批量上报定时器
+     */
+    private startBatchTimer;
     /**
      * 监听页面卸载事件
      */