@pluve/logger-sdk 说明文档

概览

• 环境支持：浏览器
• 采集与采样：开关、日志等级白名单、分级/来源/路径采样率
• 传输适配：Beacon、像素图 Image
• 批量与队列：批量阈值与定时器、队列持久化（localforage）
• 重试策略：可配置最大次数与指数退避
• 压缩能力：可选 gzip 压缩，优先使用浏览器 CompressionStream，回退 fflate.gzipSync

快速开始

import { LoggerSDK, SecurityType } from '@pluve/logger-sdk';

const sdk = LoggerSDK.getInstance();

sdk.init({
  appId: 'app',
  logStage: 'product',
  debug: false,
  enableGzip: true,
  enableBatch: false,
  batchSize: 20,
  batchInterval: 15000,
  maxPixelUrlLen: 8192,
  enableRetry: false,
  userId: 'u-001',
  storeCode: 's-001',
  token: '<token>',
  securityType: SecurityType.BASE,
  sampleRate: 1,
  enableAutoCapture: true,
  autoCapture: { js: true, promise: true, resource: true },
});

// 业务日志
sdk.track({
  message: '用户点击了购买按钮',
  traceId: 'trace-xyz',
  logLevel: 'ERROR',
});

// 动态设置
sdk.identify('u-002');
sdk.setStoreCode('s-002');
sdk.setStage('testing');

配置项（节选）

• enableGzip：是否启用 gzip 压缩（默认 true）
• enableBatch：是否启用批量上报（默认需显式开启）
• batchSize：批量阈值（默认 20）
• batchInterval：批量定时器间隔（默认 15000ms）
• maxPixelUrlLen：像素图 URL 最大长度（默认 8192）
• enableStorage：队列持久化开关（默认 true）
• storeCode：店铺编码（可选）
• securityType：安全类型（默认 SecurityType.BASE / 'BASE'）
  • SecurityType.ACCOUNT_CENTER / '2B'：账号中心
  • SecurityType.EHP / 'EHP'：EHP 医疗
  • SecurityType.CUSTOMER / 'CUSTOMER'：C 端会员（预留）
  • SecurityType.BASE / 'BASE'：兜底 MD5
• token：鉴权 Token
• sampleRate/levelSampleRate/sourceSampleRate/pathSampleRate：采样配置
• enableAutoCapture：自动采集总开关（默认开启）
• autoCapture：细粒度开关 { js, promise, resource }

说明：

• enableGzip 仅在启用批量模式时生效；
• enableStorage 默认在开启批量时启用；即使未开启批量，若 enableStorage 未显式设为 false，也会启用
• autoCapture 默认全部开启；可按需关闭各子项，或关闭总开关

详细定义参考类型文件：sdkOptions.ts.

压缩实现

• gzipCompress(data)
  • 浏览器支持 CompressionStream 时，流式 gzip 压缩，再转 Base64 字符串
  • 不支持时，回退到 fflate.gzipSync，使用 btoa/Buffer 生成 Base64
  • 返回值为 Base64 字符串，适用于传输（像素图 URL/JSON 体）
• 代码参考：compression.ts.
• 备注：当前默认压缩级别，无级别可调参数暴露；如需级别控制可在 fflate 路径引入配置。

传输适配

• TransportAdapter 根据环境选择传输器：
  • 浏览器：优先 BeaconTransport（sendBeacon Blob），否则 PixelImageTransport（Image GET）
• PixelImageTransport
  • 字符串化 items，enableGzip 时压缩为 Base64；非 gzip 情况下优先使用全局 Base64，其次 btoa，再次 encodeURIComponent；URL 参数附带 gzip=1
  • 构造像素上报 URL（含 appId、appStage、items、cacheBuster）
  • URL 超长打印警告
• BeaconTransport
  • 使用 Blob 指定 Content-Type，通过 navigator.sendBeacon 发送

代码参考：

• 适配器选择：transportAdapter.ts
• Pixel Image：pixelImageTransport.ts
• Beacon：beaconTransport.ts

批量与队列

• 启用批量后，事件入队，当队列大小达到 batchSize 或定时器触发时 flush
• flush：按 appId|stage 分组与分块（最多 200/块），批量发送成功后出队
• 队列持久化：优先 IndexedDB（localforage），失败回退 localStorage；仅在浏览器环境启用
• 页面事件触发 flush：visibilitychange（hidden）、pagehide、beforeunload
• 代码参考：
  • queueManager.ts
  • loggerSDK.ts（flush/sendBatch）

重试策略

• 单个事件 sendEvent 与批量 sendBatch 均支持 executeWithRetry
• 可配置最大次数、基础延迟、指数退避
• 代码参考：retryManager.ts

采样与开关

• 后端注册返回：
  • collectSwitch：采集开关（0 关闭）
  • collectLogLevel：采集日志等级白名单
  • samplingRate：全局采样率
• 前端 shouldSend：
  • 综合 level/source/path/global 采样率
  • 基于 seed 哈希概率决定是否发送
• 参考：
  • loggerSDK.ts（shouldSend）
  • api.ts

数据格式

• LogEvent：标准化日志格式（logId/seq/appId/stage/level/traceId/frontendId/url/location/message/throwable/userId/storeCode/tags）
  • 类型参考：logEvent.ts
• ReportData：上报批次（appId/appStage/items[]）

限制与注意

• Beacon：浏览器与网络环境兼容性依赖，失败仅打印不抛出
• 像素图：URL 长度受限；压缩可显著降低长度但 Base64 会比二进制略增
• 压缩：CompressionStream 不提供压缩级别参数；fflate 同步压缩适合小批量数据
• 安全：不要在日志中包含敏感数据（token、密码、隐私信息等）
• 依赖：js-base64、localforage 均为 peerDependencies；UMD 外部化由应用或 CDN 提供全局；ESM/CJS 下由应用安装解析

流程图

• 完整 Mermaid 流程图见文件：
  • logger-sdk.mermaid
  • logger-sdk.svg

类型与打包

• 类型入口：package.json exports.types 与 typesVersions 指向 dist/types
• TypeScript 解析：推荐在应用设置 moduleResolution: "bundler" 或 "nodenext"/"node16"
• 声明构建：yarn build-types（tsconfig.types.json 禁用默认 @types 扫描，避免冲突）

依赖说明

• peerDependencies（由应用安装或 CDN 提供）
  • js-base64（^3.7.5）
  • localforage（^1.10.0）
• 安装示例（应用侧）
  • yarn add js-base64 localforage
• CDN 全局（UMD 产物）
  • 先引入 js-base64 提供全局 Base64，再引入 logger-sdk UMD
  • localforage 可选（IndexedDB 持久化），未提供时回退到 localStorage
• 构建外部化（UMD）
  • .fatherrc.ts 已将 js-base64 与 localforage 外部化映射到全局变量
• 运行时回退策略
  • PixelImageTransport：优先使用全局 Base64，其次 btoa，再次 encodeURIComponent
  • 压缩：CompressionStream 优先；回退 fflate.gzipSync + btoa/Buffer
  • 队列：优先 localforage（IndexedDB）；失败回退 localStorage（仅浏览器启用）

编码细节（传输 × 压缩）

• BeaconTransport（sendBeacon）

  • 未压缩
    • Body：JSON（safeStringify(payload)）
    • Content-Type：application/json（通过 Blob 指定）
    • 发送方式：navigator.sendBeacon(endpoint, blob)
  • 启用压缩（满足批量条件或显式开启）
    • items：safeStringify(items) 后 gzipCompress → Base64
    • Body：JSON（...payload, items: Base64）
    • Content-Type：application/json（Blob）

• PixelImageTransport（Image GET）

  • 未压缩
    • items：safeStringify(items)
    • 编码：优先使用 Base64.encode(items)，其次 encodeURIComponent(items)
    • Query 参数：items=encodeURIComponent(编码结果)；gzip=0；携带 appId、appStage、cacheBuster
  • 启用压缩
    • items：safeStringify(items) 后 gzipCompress → Base64
    • Query 参数：items=encodeURIComponent(Base64)；gzip=1；携带 appId、appStage、cacheBuster
  • URL 长度检查：默认最大 8192，超长打印警告

说明：

• Base64 来源优先级：全局 Base64（CDN 或应用注入） > 原生 btoa > encodeURIComponent 回退
• 压缩实现优先级：CompressionStream（浏览器） > fflate.gzipSync（通用），均返回 Base64 字符串便于传输
• 所有传输模式的 items 都基于统一结构（level/traceId/frontendId/location/message/throwable）