sls-tracking-log

把浏览器和微信小程序的 Network 请求记录到阿里云 SLS。每个业务请求产生一条 request 日志和一条 response 日志，两条日志通过 requestId 关联。

SDK 只负责采集和上报，不判断业务 code、不提供告警、重试或离线补传。

这是纯客户端 SDK。Web 入口依赖浏览器 window，不要在 Node/SSR 服务端执行；SSR 项目应只在客户端生命周期中动态加载和初始化。

安装

npm install sls-tracking-log

使用前需要在目标 Logstore 开启 Web Tracking。微信小程序还需要把 SLS 地址加入合法请求域名。

Web

import { createNetworkLogger } from 'sls-tracking-log'

const logger = createNetworkLogger({
  appName: 'order-web',
  environment: 'production',
  sls: {
    host: 'cn-hangzhou.log.aliyuncs.com',
    project: 'your-project',
    logstore: 'frontend-network-log',
  },
  includeUrls: ['/api/'],
  excludeUrls: ['/api/health', '/api/polling'],
  customParams: {
    userId: '123456',
    tenantId: 'tenant-a',
  },
})

初始化后，SDK 会自动代理全局 fetch 和 XMLHttpRequest。excludeUrls 的优先级高于 includeUrls，SLS 上报地址始终自动排除。

不再采集时调用：

logger.destroy()

同一页面多次初始化会共享全局代理。所有实例的 appName、environment 和 SLS 配置必须相同；最后一个实例销毁后才会恢复原生网络对象。

微前端

多个子应用共享 window 时，原生 Fetch/XHR 无法知道请求来自哪个子应用。需要使用初始化实例绑定后的请求客户端：

const orderLogger = createNetworkLogger({
  appName: 'business-web',
  subAppName: 'order-center',
  environment: 'production',
  sls: {
    host: 'cn-hangzhou.log.aliyuncs.com',
    project: 'your-project',
    logstore: 'frontend-network-log',
  },
})

await orderLogger.fetch('/api/order')

const xhr = orderLogger.createXMLHttpRequest()
xhr.open('GET', '/api/order')
xhr.send()

直接调用全局 fetch 或 new XMLHttpRequest() 仍会被采集，但 subAppName 为空。

Axios

import axios from 'axios'

const api = axios.create({ baseURL: '/api' })
const uninstallAxios = orderLogger.installAxios(api)

await api.get('/order')

uninstallAxios()

Axios 的实际请求仍由全局 Fetch/XHR 采集，注册实例只负责绑定子应用上下文，因此不会重复生成日志。首版按 Axios 1.x 的浏览器默认适配器验证。

微信小程序

必须在调用 App() 和 Page() 之前初始化：

import { createNetworkLogger } from 'sls-tracking-log/mini'

const logger = createNetworkLogger({
  appName: 'order-mini',
  environment: 'production',
  sls: {
    host: 'cn-hangzhou.log.aliyuncs.com',
    project: 'your-project',
    logstore: 'frontend-network-log',
  },
  customParams: {
    userId: '123456',
  },
})

App({
  onLaunch() {},
})

SDK 会代理 wx.request，并包装 App.onHide、Page.onUnload。进入后台或页面卸载时，尚未结束的请求会记录为 client_unload。原回调、生命周期和 RequestTask.abort() 行为保持不变。

发送前处理

请求头和响应头不会被采集。请求或响应正文可能包含敏感信息，建议通过 beforeSend 做业务脱敏：

createNetworkLogger({
  // 其他配置
  beforeSend(log) {
    if (log.logType === 'request' && log.requestUrl.includes('/login')) {
      log.requestBody = '[REDACTED]'
    }

    if (log.requestUrl?.includes('/health')) {
      return false
    }
  },
})

beforeSend 是同步钩子，可以修改当前日志或返回 false 丢弃。钩子抛出异常时，该条日志会被丢弃，且不会影响业务请求。

正文处理

• JSON、字符串、URLSearchParams 和 FormData 普通字段会被序列化。
• FormData 文件、Blob 和 ArrayBuffer 只记录名称、类型和大小。
• Stream、opaque 响应不读取正文。
• 单个请求或响应正文最多保留 64 KiB UTF-8 内容；长度字段始终记录截断前大小。
• 循环引用或读取失败会写入 captureError，不会中断业务请求。

查询示例

按 requestId 还原请求：

requestId: "<requestId>"
| SELECT * ORDER BY timestamp ASC

查询 HTTP 错误：

logType: "response" AND httpStatus >= 400
| SELECT requestId, appName, subAppName, requestUrl,
         httpStatus, requestState, timestamp
  ORDER BY timestamp DESC

查询未正常完成的请求：

logType: "response" AND requestState != "completed"
| SELECT requestId, appName, requestUrl, requestState,
         errorName, errorMessage, timestamp
  ORDER BY timestamp DESC

限制

• Web Tracking 是客户端匿名写入，日志不能作为不可伪造的审计证据。
• 每个被采集的业务请求会额外产生两次立即上报。
• 强制结束页面或小程序时只做尽力上报，不承诺必达。
• HTTP 200 下的业务失败不会自动识别，需要查询响应正文。
• SDK 不重试 SLS 上报，也不使用 IndexedDB 或本地存储补传。

License

MIT