@antglobal/rlog-sdk

基于 rrweb 的用户行为录制与上报 SDK，用于 Web 应用的会话回放、错误追踪和行为分析。

特性

• 全量录制 — 持续录制用户操作，定时上传
• 错误模式录制 — 仅在发生错误时上传前后时间窗口内的录制数据
• 多 Tab 隔离 — 每个标签页独立 Session，分布式锁保证数据安全
• 存储自动降级 — IndexedDB > LocalStorage > Memory
• 网络监控 — 拦截 XHR/Fetch，记录请求响应，支持黑白名单过滤
• 路由监控 — 监听 History API 和 Hash 变化，记录页面停留时间
• Console 录制 — 可选的 console 输出捕获（rrweb 插件）
• 上传重试 — 失败自动重试，超过阈值停止录制并派发事件
• Web Worker 上传 — 后台线程上传，不阻塞主线程
• 只采集不上报 — 可动态切换的 consume-only 模式
• 自定义事件 — 支持注入业务自定义事件到录制流
• 错误上报 — 全局 JS 错误和资源加载错误自动捕获

安装

npm install @antglobal/rlog-sdk

快速开始

import { init } from '@antglobal/rlog-sdk';

const rlog = init({
  serv: 'https://your-server.com/api/rlog/record',
  appId: 'your-app-id',
  cdnConfigUrl: 'https://your-cdn.com/rlog-config.json', // 可选，远程动态配置
});

// 停止录制
rlog.cancel();

// 停止录制并清除本地数据
rlog.cancel({ clearData: true });

API

核心

| 方法 | 说明 | |------|------| | init({ serv, appId, cdnConfigUrl? }) | 初始化 SDK，返回 { cancel } | | cancelRecord(options?) | 停止录制（推荐使用 rlog.cancel()） | | addCustomEvent(tag, payload) | 添加自定义事件到录制流 | | reportError(error) | 手动上报错误（Error 对象或字符串） |

网络配置

| 方法 | 说明 | |------|------| | setCustomHeaders(headers) | 设置全局自定义请求头（注入到 XHR/Fetch） | | getCustomHeaders() | 获取当前自定义请求头 | | setWhiteListUrls(urls) | 设置白名单 URL（仅监控这些请求） | | getWhiteListUrls() | 获取白名单 | | setBlackListUrls(urls) | 设置黑名单 URL（排除这些请求） | | getBlackListUrls() | 获取黑名单 |

黑名单优先于白名单。白名单为空时监控所有非黑名单请求。

路由监控

| 方法 | 说明 | |------|------| | updateRouterConfig(config) | 更新路由监控配置 | | getCurrentRouteInfo() | 获取当前路由信息 | | manualRouteChange(newRoute, prevRoute?) | 手动触发路由变化事件 | | stopRouterMonitor() | 停止路由监控 |

Consume-Only 模式

| 方法 | 说明 | |------|------| | setConsumeOnlyMode(enable) | 开启/关闭只采集不上报 | | isConsumeOnlyMode() | 查询当前是否为只采集模式 | | toggleConsumeOnlyMode() | 切换模式，返回新状态 |

调试工具

通过 debug 对象访问：

import { debug } from '@antglobal/rlog-sdk';

debug.getStorageAdapterType(); // 当前存储类型: 'indexeddb' | 'localstorage' | 'memory'
debug.getDeviceId();           // 设备 ID
debug.getSessionId();          // 当前 Tab 的 Session ID
debug.getStorageKey();         // 存储键 (deviceId_sessionId)
debug.resetUploadState();      // 重置上传状态
debug.getStorageState();       // Promise<{ adapterType, eventCount }>
debug.clearStorage();          // Promise<void> 清空存储
debug.getConfig();             // 当前 CDN 配置
debug.shouldRecordUrl(url);    // 判断 URL 是否会被网络监控记录

CDN 动态配置

通过 cdnConfigUrl 传入远程 JSON 配置，SDK 会定期拉取更新。完整配置项：

{
  "enable": false,
  "uploadInterval": 2000,
  "configUpdateInterval": 300000,
  "captureMode": "full",
  "packEvents": false,
  "clearStorageBeforeRecord": true,
  "http": false,
  "maxRetryCount": 3,
  "consumeOnly": false,
  "urlParamsToCache": [],
  "sampling": {
    "canvas": 15,
    "mousemove": 50,
    "scroll": 100,
    "input": "last"
  },
  "ignoreClass": "rr-ignore",
  "blockClass": "rr-block",
  "maskTextClass": "rr-mask",
  "console": {
    "enable": false,
    "level": ["log", "warn", "error", "info"],
    "lengthThreshold": 1000,
    "stringifyOptions": {
      "stringLengthLimit": 500,
      "numOfKeysLimit": 50,
      "depthOfLimit": 4
    }
  },
  "routerMonitor": {
    "enable": false,
    "trackHashChange": true,
    "trackHistoryChange": true,
    "trackPageStayTime": true,
    "ignoreRoutes": []
  },
  "errorCapture": {
    "beforeDuration": 30000,
    "afterDuration": 30000,
    "httpErrorThreshold": 400
  }
}

配置说明

| 字段 | 默认值 | 说明 | |------|--------|------| | enable | false | 采集总开关 | | uploadInterval | 2000 | 上传间隔（ms） | | configUpdateInterval | 300000 | 配置刷新间隔（ms） | | captureMode | "full" | "full" 全量录制 / "error" 错误触发录制 | | packEvents | false | 是否压缩事件数据 | | clearStorageBeforeRecord | true | 录制前是否清空存储 | | http | false | 是否开启网络请求监控 | | maxRetryCount | 3 | 上传失败最大重试次数 | | consumeOnly | false | 只采集不上报 | | sampling.canvas | 15 | Canvas 采样率（fps） | | sampling.mousemove | 50 | 鼠标移动采样间隔（ms） | | sampling.scroll | 100 | 滚动防抖间隔（ms） | | sampling.input | "last" | "all" 全部 / "last" 仅最终值 | | errorCapture.beforeDuration | 30000 | 错误前录制时长（ms） | | errorCapture.afterDuration | 30000 | 错误后继续录制时长（ms） | | errorCapture.httpErrorThreshold | 400 | HTTP 错误状态码阈值 |

采集模式

Full 模式（默认）

持续录制所有用户操作，按 uploadInterval 定时上传，每批最多 100 条事件。

Error 模式

事件持续写入本地存储，仅在错误发生时触发上传。上传时间窗口为 [now - beforeDuration, now + afterDuration]。若 afterDuration 期间再次发生错误，窗口自动延长。

架构

src/
├── index.ts                    # 公共 API 导出
└── lib/
    ├── init.ts                 # SDK 初始化与销毁
    ├── config.ts               # CDN 配置管理
    ├── rrweb.ts                # rrweb 录制启动
    ├── storage-manager.ts      # 存储管理（序列化队列）
    ├── uploader.ts             # 上传调度（全量/错误模式）
    ├── upload-worker-manager.ts # Web Worker 管理
    ├── upload-worker.ts        # Worker 上传逻辑
    ├── net.ts                  # 网络监控（XHR/Fetch 拦截）
    ├── api.ts                  # 上传接口
    ├── request.ts              # HTTP 请求工具
    ├── router-monitor.ts       # 路由监控
    ├── error.ts                # 错误捕获
    ├── error-trigger.ts        # 错误模式状态机
    ├── utils.ts                # 工具函数
    ├── logger.ts               # 日志输出
    ├── constants.ts            # 常量定义
    └── drive/
        ├── storage-interface.ts    # StorageAdapter 接口
        ├── indexeddb-adapt.ts      # IndexedDB 适配器
        ├── localstorage-adapt.ts   # LocalStorage 适配器（含分布式锁）
        ├── memory-adapt.ts         # Memory 适配器
        └── safe-storage.ts         # 安全 KV 存储（降级到内存）

多 Tab 并发

• 每个标签页分配唯一 sessionId，存储键为 deviceId_sessionId
• Session 注册表追踪活跃标签页
• SDK 初始化时自动清理孤儿 session 的残留数据
• LocalStorage 操作通过分布式锁（CAS + 超时）保证原子性

上传重试

上传失败时事件回退到队列头部，下个周期重试。连续失败达到 maxRetryCount 后：

1. 派发 rlog-upload-failure 自定义事件（window + rrweb）
2. 停止 rrweb 录制
3. 停止上传循环

监听失败事件：

window.addEventListener('rlog-upload-failure', (e) => {
  console.log('上传失败', e.detail);
});

开发

npm run dev    # 开发模式
npm run build  # 构建（ESM + CJS）

License

MIT