@pluve/logger-sdk 0.0.3 → 0.0.5

package/README.md

@@ -2,9 +2,10 @@
 
 ## 简介
 
-- 轻量级前端日志采集 SDK，支持 H5 浏览器环境
+- 轻量级前端日志采集 SDK，支持 H5 浏览器环境和微信小程序
 - 使用 Beacon 和像素图（Image）方式上报，确保兼容性与可靠性
 - 标准化日志格式，易于分析和处理
+- 支持批量上报、异常重试、持久化存储等高级功能
 
 ## 安装与引入
 
@@ -35,6 +36,12 @@ sdk.track('error', 'TypeError: Cannot read property', {
   },
 });
 
+// 记录带 traceId 的错误（用于关联多个日志）
+sdk.track('error', 'Request failed', 'trace-abc-123', {
+  level: 'error',
+  tags: { api: '/api/user' },
+});
+
 // 记录自定义事件
 sdk.track('custom', 'User clicked button', {
   level: 'info',
@@ -48,6 +55,8 @@ sdk.track('custom', 'User clicked button', {
 
 ```typescript
 {
+  "logId": "550e8400-e29b-41d4-a716-446655440000",  // 日志 ID（UUID v4）
+  "traceId": "trace-123456",    // 可选：追踪 ID（用于关联多个日志）
   "eventType": "error",          // 固定：error/crash/pageview/custom
   "ts": 1690000000000,           // 毫秒时间戳
   "appId": "web-shop",           // 应用标识
@@ -81,17 +90,34 @@ interface SDKOptions {
   debug?: boolean; // 是否开启调试模式
   pixelParam?: string; // 像素上报参数名，默认 'data'
   maxPixelUrlLen?: number; // 像素上报 URL 最大长度，默认 1900
+  
+  // 批量上报配置
+  enableBatch?: boolean; // 是否启用批量上报，默认 true
+  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
 }
 ```
 
-### `track(eventType, message, options?)`
+### `track(eventType, message, traceId?, options?)`
 
-记录事件日志。
+记录事件日志。每条日志会自动生成唯一的 `logId`（UUID v4 格式）。
 
 **参数：**
 
 - `eventType`: 事件类型（`'error' | 'crash' | 'pageview' | 'custom'`）
 - `message`: 摘要信息
+- `traceId`: (可选) 追踪 ID，用于关联多个相关日志
 - `options`: 可选配置
   - `level?`: 日志级别（`'info' | 'warn' | 'error' | 'fatal'`），默认 `'info'`
   - `stack?`: 堆栈信息
@@ -109,6 +135,12 @@ sdk.track('error', 'Failed to load resource', {
   tags: { resource: 'image.png' },
 });
 
+// 记录带 traceId 的错误（用于关联多个日志）
+sdk.track('error', 'API request failed', 'trace-xyz-789', {
+  level: 'error',
+  tags: { endpoint: '/api/users', statusCode: 500 },
+});
+
 // 记录页面浏览
 sdk.track('pageview', 'User viewed product page', {
   level: 'info',
@@ -116,6 +148,29 @@ sdk.track('pageview', 'User viewed product page', {
 });
 ```
 
+### 日志 ID 和追踪 ID
+
+- **logId**: 每条日志自动生成的唯一标识符（UUID v4 格式），用于全局唯一定位日志
+- **traceId**: 可选的追踪 ID，用于关联同一请求链路上的多个日志（例如：前端请求、后端处理、数据库查询等）
+
+```typescript
+// 在请求开始时生成 traceId
+const traceId = `trace-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+
+// 在请求的不同阶段使用相同的 traceId
+sdk.track('custom', 'Request started', traceId, {
+  level: 'info',
+  tags: { endpoint: '/api/checkout' },
+});
+
+// ... 请求处理 ...
+
+sdk.track('error', 'Request failed', traceId, {
+  level: 'error',
+  tags: { endpoint: '/api/checkout', error: 'Network timeout' },
+});
+```
+
 ### `identify(userId: string)`
 
 设置用户 ID（用于后续日志关联）。
@@ -225,3 +280,171 @@ 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 = new LoggerSDK({
+  endpoint: 'https://your-api.com/logs',
+  appId: 'my-app',
+  enableBatch: false,  // 禁用批量上报，每条日志立即发送
+  enableRetry: true,   // 仍然启用重试
+});
+```

package/dist/index.d.ts

@@ -1 +1,10 @@
 export { LoggerSDK } from './loggerSDK';
+export { defaultTransport, TransportAdapters } from './transportAdapter';
+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,8 +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 { LoggerSDK } from "./loggerSDK";
+export { defaultTransport, TransportAdapters } from "./transportAdapter";
+export { getEnvironmentInfo, parseBrowserInfo, isWeChatMiniProgram, gzipCompress, isGzipSupported } from "./utils";
+export { QueueManager } from "./queueManager";
+export { RetryManager } from "./retryManager";

package/dist/loggerSDK.d.ts

@@ -5,6 +5,14 @@ export declare class LoggerSDK {
     private closed;
     /** 预收集的环境信息 tags */
     private envTags;
+    /** 队列管理器 */
+    private queueManager?;
+    /** 重试管理器 */
+    private retryManager?;
+    /** 批量上报定时器 */
+    private batchTimer?;
+    /** 是否正在上报 */
+    private isSending;
     constructor(options: SDKOptions);
     private logDebug;
     /**
@@ -14,7 +22,7 @@ export declare class LoggerSDK {
     /**
      * 记录事件
      */
-    track(eventType: LogEventType, message: string, options?: {
+    track(eventType: LogEventType, message: string, traceId?: string, options?: {
         level?: LogEventLevel;
         stack?: string;
         userId?: string;
@@ -24,10 +32,26 @@ export declare class LoggerSDK {
      * 设置用户信息
      */
     identify(userId: string): void;
+    /**
+     * 手动刷新队列，立即上报所有待发送日志
+     */
+    flush(): Promise<void>;
     /**
      * 销毁实例
      */
-    destroy(): void;
+    destroy(): Promise<void>;
+    /**
+     * 发送单个事件（带重试）
+     */
+    private sendEvent;
+    /**
+     * 批量发送事件（带重试）
+     */
+    private sendBatch;
+    /**
+     * 启动批量上报定时器
+     */
+    private startBatchTimer;
     /**
      * 监听页面卸载事件
      */