项目介绍

@8btc/trace-log 是一个前端日志与性能上报 SDK，支持：

• 日志上报：info / warn / error
• 自动采集：全局错误、fetch 请求、资源性能、Web Vitals
• 多种传输层：Beacon / XHR / Img / 华为云 LTS / Noop

完整使用文档

SDK 接入方式

1. 安装

npm install @8btc/trace-log
# 或
yarn add @8btc/trace-log

2. 初始化

import traceLog, { createLTSTransport } from '@8btc/trace-log'

traceLog.init({
  appId: 'your-app-id',
  transport: createLTSTransport({
    region: 'cn-north-4',
    projectId: 'your-project-id',
    groupId: 'your-log-group-id',
    streamId: 'your-log-stream-id',
  }),
  debug: false,
})

appId 为必填；若不传 transport，默认使用 NoopTransport（不会真正上报）。

3. 上报日志

traceLog.info('页面加载完成')
traceLog.warn('接口响应偏慢', { duration: 2300 }, 'perf')
traceLog.error('资源加载失败', { url: '/static/logo.png' }, 'resource')

4. 设置全局公共字段（可选）

traceLog.setCustomGlobalFields({
  env: 'production',
  userId: 'u-1001',
})

5. 按需关闭自动采集（可选）

traceLog.init({
  appId: 'your-app-id',
  transport: createLTSTransport({
    region: 'cn-north-4',
    projectId: 'your-project-id',
    groupId: 'your-log-group-id',
    streamId: 'your-log-stream-id',
  }),
  enableGlobalError: true,
  enableFetchIntercept: true,
  enablePerfObserver: true,
  enableWebVitals: true,
})

Fetch trace_id 说明

• SDK 会在 fetch 响应阶段读取响应头 trace_id。
• 当接口返回非 2xx 时，onFetchError 也会携带 traceId（若可获取）。
• 网络异常或主动取消请求（如 AbortError）通常没有响应头，此时 traceId 为空。
• 若是跨域请求，请确保服务端返回：
  • Access-Control-Expose-Headers: trace_id

常用传输层

• createBeaconTransport(dsn)：推荐，适合页面卸载场景
• createXhrTransport(dsn)：通用 XHR 上报
• createImgTransport(dsn)：图片打点方式，兼容性好
• createLTSTransport(config)：直连华为云 LTS
• createNoopTransport()：禁用上报（占位）

createLTSTransport 用法

需要先安装华为云 LTS Web SDK：

npm install lts-web-sdk

import traceLog, { createLTSTransport } from '@8btc/trace-log'

traceLog.init({
  appId: 'your-app-id',
  transport: createLTSTransport({
    region: 'cn-north-4', // LTS 所在 Region
    projectId: 'your-project-id',
    groupId: 'your-log-group-id',
    streamId: 'your-log-stream-id',
    debug: false, // 可选，开启后打印 SDK 内部日志
  }),
})

| 字段 | 类型 | 必填 | 说明 | | ----------- | --------- | ---- | ------------------------------ | | region | string | 是 | 华为云 Region，如 cn-north-4 | | projectId | string | 是 | 华为云项目 ID | | groupId | string | 是 | LTS 日志组 ID | | streamId | string | 是 | LTS 日志流 ID | | debug | boolean | 否 | 开启后输出 SDK 内部调试日志 |

项目结构

wujie-trace-log/
├── src/
├── test/
├── docs/
├── rollup.config.ts
└── tsconfig.json

开发命令

yarn build

本地调试（yarn link）

在其他项目中调试本包时，使用 yarn link 建立本地软链。

第一步：在本包目录注册

# 构建产物
yarn build

# 注册到全局
yarn link

第二步：在目标项目中链接

cd /path/to/your-project
yarn link "@8btc/trace-log"

链接成功后，目标项目会直接引用本地 dist/ 产物。每次修改源码后需重新执行 yarn build，或开启监听模式自动重建：

yarn build --watch

常见问题：link 后旧包没被替换

node_modules 里可能存在旧缓存，删除后重新 link：

rm -rf node_modules/@8btc/trace-log
yarn link "@8btc/trace-log"

解除链接

# 目标项目中
yarn unlink "@8btc/trace-log"
yarn install --force

# 本包中（可选，清除全局注册）
yarn unlink