@pluve/logger-sdk 0.0.1 → 0.0.3

package/README.md

@@ -1,108 +1,227 @@
 # @pluve/logger-sdk 使用说明
 
 ## 简介
-- 统一的前端日志采集 SDK，支持 H5 与微信小程序。
-- 能力包括：批量上报、分级路由（`info|warn|error`）、自动 PV/错误/性能采集、本地持久化与 IndexedDB 冗余、页面关闭时 `sendBeacon` 兜底。
+
+- 轻量级前端日志采集 SDK，支持 H5 浏览器环境
+- 使用 Beacon 和像素图（Image）方式上报，确保兼容性与可靠性
+- 标准化日志格式，易于分析和处理
 
 ## 安装与引入
+
 - 安装：`pnpm add @pluve/logger-sdk`
-- ESM：`import LoggerSDK from '@pluve/logger-sdk'`
-- UMD：构建后全局为 `LoggerSDK`，示例：`const { LoggerSDK } = window.LoggerSDK`
+- ESM：`import { LoggerSDK } from '@pluve/logger-sdk'`
+- UMD：构建后全局为 `LoggerSDK`
 
 ## 快速开始
+
 ```ts
-import LoggerSDK from '@pluve/logger-sdk';
+import { LoggerSDK } from '@pluve/logger-sdk';
 
 const sdk = new LoggerSDK({
-  endpoints: {
-    default: '/api/collect',
-    info: '/api/collect/info',
-    warn: '/api/collect/warn',
-    error: '/api/collect/error',
-  },
-  appId: 'your-app',
+  endpoint: '/api/log',
+  appId: 'web-shop',
+  env: 'prod', // prod/stage/dev
   debug: true,
-  enableAutoPV: true,
-  enablePerf: true,
 });
 
-sdk.track({ type: 'custom', level: 'info', ctx: { action: 'click_button' } });
+// 记录错误日志
+sdk.track('error', 'TypeError: Cannot read property', {
+  level: 'error',
+  stack: 'Error stack trace...',
+  userId: '123',
+  tags: {
+    component: 'checkout',
+    browser: 'Chrome 120',
+  },
+});
+
+// 记录自定义事件
+sdk.track('custom', 'User clicked button', {
+  level: 'info',
+  tags: { action: 'click', button: 'submit' },
+});
+```
+
+## 标准化日志格式
+
+上报的日志数据遵循以下标准格式：
+
+```typescript
+{
+  "eventType": "error",          // 固定：error/crash/pageview/custom
+  "ts": 1690000000000,           // 毫秒时间戳
+  "appId": "web-shop",           // 应用标识
+  "env": "prod",                 // prod/stage/dev
+  "level": "error",              // info/warn/error/fatal
+  "message": "TypeError: ...",   // 摘要
+  "stack": "...",                // 可选：长字符串
+  "url": "https://...",          // 发生页面
+  "userId": "123",               // 可选：用户ID（脱敏）
+  "sessionId": "...",            // 会话标识
+  "tags": {                       // 可选的结构化额外信息
+    "component": "checkout",
+    "browser": "Chrome 120"
+  }
+}
 ```
 
 ## API
-- `new LoggerSDK(options)`
-- `track(event, headers?)`：事件入队并持久化，必要时触发批量上报。位置 `packages/logger-sdk/src/loggerSDK.ts:121`
-- `flush(extraHeaders?)`：按批量大小取队列，同批按 `level` 并行上报并重试。位置 `packages/logger-sdk/src/loggerSDK.ts:156-221`
-- `flushAll()`：非阻塞轮询清空队列，尊重并发锁。位置 `packages/logger-sdk/src/loggerSDK.ts:223-233`
-- `identify(user)`：设置应用/用户信息（如 `appId`）。位置 `packages/logger-sdk/src/loggerSDK.ts:222`
-- `setCommon(params)`：动态覆写通用配置（如 `globalHeaders`）。位置 `packages/logger-sdk/src/loggerSDK.ts:227`
-- `destroy()`：停止定时器并关闭。位置 `packages/logger-sdk/src/loggerSDK.ts:232`
 
-## 自动采集
-- 错误采集：JS 错误、未捕获 Promise、资源加载错误。位置 `packages/logger-sdk/src/loggerSDK.ts:238-275`
-- 自动 PV：拦截 `history.pushState/replaceState` 与 `popstate`，采集单页浏览。位置 `packages/logger-sdk/src/loggerSDK.ts:277-299`
-- 性能采集：Navigation Timing + Paint Entries。位置 `packages/logger-sdk/src/loggerSDK.ts:301-328`
+### `new LoggerSDK(options: SDKOptions)`
 
-## 页面关闭兜底
-- 当页面隐藏或关闭时触发 `flushBeacon()`，使用 `navigator.sendBeacon` 尝试上报队列，不阻塞、不移除队列。
-- 监听位置：`packages/logger-sdk/src/loggerSDK.ts:270-293`
-- 方法位置：`packages/logger-sdk/src/loggerSDK.ts:333-350`
-- 传输适配器 Beacon 通道：`packages/logger-sdk/src/transportAdapter.ts:12-20`
+创建 SDK 实例。
 
-## 配置项（SDKOptions）
-```ts
+**配置项：**
+
+```typescript
 interface SDKOptions {
-  endpoints: Partial<Record<'info'|'warn'|'error'|'default', string>>;
-  appId?: string;
-  env?: 'h5' | 'wechat' | 'unknown';
-  batchSize?: number;           // 默认 10
-  flushInterval?: number;       // 默认 5000ms
-  retryCount?: number;          // 默认 3
-  retryBase?: number;           // 默认 300ms（指数退避基数）
-  storageKey?: string;          // 默认 'logger_sdk_cache_v2'
-  maxCacheSize?: number;        // 默认 2000
-  timeout?: number;             // 默认 10000ms
-  debug?: boolean;
-  transport?: (payload: any, opts?: SDKOptions & { endpoint?: string, headers?: Record<string,string> }) => Promise<void>;
-  globalHeaders?: Record<string,string>;
-  enableAutoPV?: boolean;       // 默认 true
-  enablePerf?: boolean;         // 默认 true
-  useBeacon?: boolean;          // 传输适配器识别 Beacon 的标志（SDK 内部在 flushBeacon 时传入）
+  endpoint: string; // 上报端点 URL（必选）
+  appId?: string; // 应用 ID，默认 'unknown'
+  env?: Env; // 环境标识：prod/stage/dev，默认 'dev'
+  debug?: boolean; // 是否开启调试模式
+  pixelParam?: string; // 像素上报参数名，默认 'data'
+  maxPixelUrlLen?: number; // 像素上报 URL 最大长度，默认 1900
 }
 ```
 
-## 传输适配器
-- 默认选择：`sendBeacon`（兜底）→ 微信 `wx.request` → 浏览器 `fetch`。
-- 可自定义：实现 `transport(payload, opts)`，识别 `opts.useBeacon` 后走轻量通道。
+### `track(eventType, message, options?)`
 
-## 持久化与冗余
-- H5：`localStorage` + IndexedDB 冗余队列。初始化位置 `packages/logger-sdk/src/loggerSDK.ts:50-61`
-- 微信：`wx.*Storage`。实现位置 `packages/logger-sdk/src/storeAdapter.ts`
+记录事件日志。
 
-## 最佳实践
-- 分级路由：至少提供 `default`，按需配置 `info|warn|error` 的独立地址。
-- 吞吐与可靠性：高频场景提高 `batchSize`（如 20–50），缩短 `flushInterval`（如 3000–5000ms）；弱网提高 `retryCount` 或 `retryBase`。
-- 统一头部：在 `globalHeaders` 添加溯源头（如 `x-trace-id`、`x-app-version`）。
-- 页面关闭兜底：无需手动调用，SDK 已自动在合适时机触发；若使用自定义 `transport`，注意识别 `useBeacon`。
+**参数：**
 
-## 示例：自定义传输
-```ts
-const transport = async (payload: any, opts?: any) => {
-  const body = JSON.stringify(payload);
-  if (opts?.useBeacon && navigator.sendBeacon) {
-    navigator.sendBeacon(opts.endpoint || '', new Blob([body], { type: 'application/json' }));
-    return;
-  }
-  await fetch(opts?.endpoint || '', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json', ...(opts?.globalHeaders || {}), ...(opts?.headers || {}) },
-    body,
+- `eventType`: 事件类型（`'error' | 'crash' | 'pageview' | 'custom'`）
+- `message`: 摘要信息
+- `options`: 可选配置
+  - `level?`: 日志级别（`'info' | 'warn' | 'error' | 'fatal'`），默认 `'info'`
+  - `stack?`: 堆栈信息
+  - `userId?`: 用户 ID
+  - `tags?`: 额外的结构化信息
+
+**示例：**
+
+```typescript
+// 记录错误
+sdk.track('error', 'Failed to load resource', {
+  level: 'error',
+  stack: error.stack,
+  userId: '123',
+  tags: { resource: 'image.png' },
+});
+
+// 记录页面浏览
+sdk.track('pageview', 'User viewed product page', {
+  level: 'info',
+  tags: { productId: 'P123' },
+});
+```
+
+### `identify(userId: string)`
+
+设置用户 ID（用于后续日志关联）。
+
+### `destroy()`
+
+销毁 SDK 实例，停止所有监听。
+
+## 自动采集
+
+SDK 会自动监听以下页面事件并上报：
+
+- **页面隐藏**（`visibilitychange`）：当页面变为隐藏状态时
+- **页面卸载**（`pagehide`, `beforeunload`）：当用户离开页面时
+
+这些事件使用 Beacon API 上报，确保在页面关闭时仍能成功发送。
+
+## 上报方式
+
+SDK 使用两种上报方式，按优先级自动选择：
+
+### 1. Beacon API（优先）
+
+- **兼容性**：Chrome 39+, Firefox 31+, Edge 14+
+- **特点**：页面卸载时可靠传输，不阻塞页面关闭
+- **限制**：无法获取响应，队列大小限制（通常 64KB）
+
+### 2. Image 像素上报（降级）
+
+- **兼容性**：所有浏览器
+- **特点**：轻量级，无跨域限制
+- **限制**：URL 长度限制（默认 1900 字符）
+
+如果 Beacon 失败，会自动降级到 Image 方式。
+
+## 使用场景
+
+### 错误监控
+
+```typescript
+// 全局错误捕获
+window.addEventListener('error', (event) => {
+  sdk.track('error', event.message, {
+    level: 'error',
+    stack: event.error?.stack,
+    tags: {
+      filename: event.filename,
+      lineno: event.lineno,
+      colno: event.colno,
+    },
   });
-};
+});
 
-const sdk = new LoggerSDK({ endpoints: { default: '/api/collect' }, transport });
+// Promise 错误捕获
+window.addEventListener('unhandledrejection', (event) => {
+  sdk.track('error', 'Unhandled Promise Rejection', {
+    level: 'error',
+    stack: event.reason?.stack || String(event.reason),
+  });
+});
 ```
 
+### 页面浏览统计
+
+```typescript
+// 记录页面浏览
+sdk.track('pageview', document.title, {
+  level: 'info',
+  tags: {
+    path: window.location.pathname,
+    referrer: document.referrer,
+  },
+});
+```
+
+### 用户行为追踪
+
+```typescript
+// 记录用户点击
+button.addEventListener('click', () => {
+  sdk.track('custom', 'Button clicked', {
+    level: 'info',
+    userId: currentUserId,
+    tags: {
+      buttonId: button.id,
+      page: 'checkout',
+    },
+  });
+});
+```
+
+## 最佳实践
+
+1. **设置正确的环境标识**：确保在不同环境（prod/stage/dev）使用正确的配置
+2. **使用有意义的 message**：摘要信息应简洁明了，便于快速定位问题
+3. **合理使用 tags**：将额外的结构化信息放在 tags 中，便于分析和过滤
+4. **用户隐私保护**：userId 应该经过脱敏处理
+5. **控制日志量**：避免在高频操作中记录过多日志
+
 ## 调试
-- 开启 `debug: true` 查看控制台内部日志。
-- 生成 UMD Demo HTML：`LoggerSDK.generateDemoHtml()`（方法位置：`packages/logger-sdk/src/loggerSDK.ts:330-361`）。
+
+开启调试模式查看控制台输出：
+
+```typescript
+const sdk = new LoggerSDK({
+  endpoint: '/api/log',
+  debug: true, // 开启调试
+});
+```

package/dist/index.js

@@ -0,0 +1,9 @@
+/*
+ * @Author       : 黄震 huangzhen@yfpharmacy.com
+ * @Date         : 2025-11-21 14:25:26
+ * @LastEditors  : 黄震 huangzhen@yfpharmacy.com
+ * @LastEditTime : 2025-12-04 15:56:03
+ * @Description  : 描述
+ * Copyright (c) 2025 by 益丰大药房连锁股份有限公司, All Rights Reserved.
+ */
+export { LoggerSDK } from "./loggerSDK";

package/dist/loggerSDK.d.ts

@@ -0,0 +1,36 @@
+import { SDKOptions, LogEventType, LogEventLevel } from './types';
+export declare class LoggerSDK {
+    private opts;
+    private seq;
+    private closed;
+    /** 预收集的环境信息 tags */
+    private envTags;
+    constructor(options: SDKOptions);
+    private logDebug;
+    /**
+     * 收集环境信息并生成 tags（仅在初始化时执行一次）
+     */
+    private collectEnvironmentTags;
+    /**
+     * 记录事件
+     */
+    track(eventType: LogEventType, message: string, options?: {
+        level?: LogEventLevel;
+        stack?: string;
+        userId?: string;
+        tags?: Record<string, any>;
+    }): Promise<void>;
+    /**
+     * 设置用户信息
+     */
+    identify(userId: string): void;
+    /**
+     * 销毁实例
+     */
+    destroy(): void;
+    /**
+     * 监听页面卸载事件
+     */
+    private attachUnloadHandlers;
+}
+export default LoggerSDK;