@autoxing/front-trace

FrontTrace SDK 技术文档

版本：v1.0.14（npm：@autoxing/front-trace@1.0.14） 更新日期：2026-06-05

---

目录

1. 架构概览
2. 上下文生命周期
3. 环境兼容性
4. 多框架接入指南
5. API 参考
6. 使用示例
7. 与 Go Tracer 的链路对接
8. 上报数据格式
9. 配置项说明
10. 性能分析
11. 已知局限与改进建议

---

一、架构概览

业务代码
  │
  ├── HTTP 拦截（自动，三选一或叠加使用）
  │     ├── initAxisInterceptor()       → 拦截 Axis 全局对象
  │     ├── initUniRequestInterceptor() → 拦截 uni.request（UniApp 专用）
  │     └── initAxiosInterceptor()      → 拦截 axios 实例或全局 axios
  │           ├── 读取 currentCtx → 创建子 Span（HTTP 状态码在响应中精确记录）
  │           └── 注入链路头 x-trace-id / x-span-id / traceparent / x-trace-sample
  │                 ↑ 仅注入到出站请求，不写入上报数据包
  │
  └── 手动 startSpan（可选）
        ├── 自动更新 currentCtx（HTTP 拦截器自动挂在此下）
        ├── 自动 finish（微任务，同步 Span 专用）
        └── 手动 span.finish()（异步 Span 精确计时）
              │
              └── 自动恢复 currentCtx 为父级
                    │
                    ▼
         ┌ ─ ─ ─ ─ ─ 采样判定 ─ ─ ─ ─ ─ ─ ─ ┐
         │  _shouldSample(trace)               │
         │  ├─ SAMPLE_RATE 概率采样            │
         │  ├─ SAMPLE_STATUS_CODES 状态码采样   │
         │  ├─ SAMPLE_MIN_STATUS_CODE 阈值采样  │
         │  └─ SAMPLE_RES_MIN_DURATION 耗时采样 │
         └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
                    │ 通过
                    ▼
             内存队列 _memQueue（扁平 Span[]）
                    │
                    ▼ 定时 / 进程/页面退出
         ┌──────────┴────────────────────┐
         │                               │
      Worker 模式（浏览器）          降级模式（Worker 不可用 / Node.js / UniApp 原生）
      Worker 内执行:                主线程执行:
      ├─ _groupToTraces()           ├─ _groupToTraces()
      ├─ IDB 持久化                 ├─ localStorage/内存持久化
      └─ fetch 上报                 └─ fetch/uni.request 上报
         │                               │
         └──────────────┬────────────────┘
                        │
              ┌─────────▼─────────┐
              │   HTTP POST 上报   │
              │ 解析响应 body 提取  │
              │ data.traceControl  │
              └─────────┬─────────┘
                        │
              ┌─────────▼─────────┐
              │ _parseControlFrom │
              │   Response()      │
              │   → _applyControl │
              └─────────┬─────────┘
                        │
              ┌─────────▼─────────┐
              │  _retryQueue       │  ← 失败时入队重试
              │  内存兜底重试队列   │
              └───────────────────┘

运行模式自动降级链路：

ENABLE=false？
  └── 是 → 所有方法静默，零副作用，零内存占用（短路返回）

Node.js 环境？
  ├── 是 → 内存降级模式（无 Worker / 无 localStorage）
  │         退出钩子：process.on('beforeExit') + SIGTERM + SIGINT
  └── 否 → UniApp 环境？（uni 对象存在）
              ├── 是 → Web Worker 可用？（H5 / WebView）
              │          ├── 是 → Blob URL 内联 Worker（优先，无路径依赖）
              │          │         → CSP 限制 blob: 时降级到 WORKER_PATH 外部文件
              │          │         存储：IndexedDB → 内存
              │          └── 否 → 主线程降级模式（App/小程序原生层）
              │                  存储：uni.setStorageSync
              │                  上报：uni.request
              └── 否 → Web Worker 可用？
                          ├── 是 → Blob URL 内联 Worker（优先，无路径依赖）
                          │         → CSP 限制 blob: 时降级到 WORKER_PATH 外部文件
                          │         存储：IndexedDB → 内存
                          └── 否 → 主线程降级模式
                                    存储：localStorage → 内存

---

二、上下文生命周期

这是理解 SDK 行为的核心。SDK 维护一个全局属性 currentCtx，它在 startSpan/finish 之间自动流转，保证 HTTP 拦截器请求始终挂在当前业务 Span 下。

2.1 自动流转规则

时机	currentCtx 变化
SDK 初始化	null
startSpan(parentCtx, name) 被调用	更新为本次 Span 的 childCtx，同时记录 prevCtx = 调用前的 currentCtx
span.finish() 被调用	恢复为 prevCtx（进入前的值）
startSpan(null, name) 且 currentCtx 不为 null	挂在当前上下文下（不创建新链路）
startSpan(null, name) 且 currentCtx 为 null	创建新根上下文，开启独立链路

2.2 完整推演

场景 A：有业务 Span + HTTP 拦截（标准用法）

初始: currentCtx = null

startSpan(null, '加载用户列表')
  resolvedCtx = createRootCtx() = {T1, ''}
  prevCtx_op = null
  currentCtx = {T1, S_op}

axios.get('/api/users')  [axios 拦截器]
  ctx = currentCtx = {T1, S_op}
  startSpan({T1,S_op}, 'GET:/api/users')
    prevCtx_ax = {T1, S_op}
    currentCtx = {T1, S_ax}
    _noAutoFinish = true

[响应拦截器] span_ax._sc = 200, span_ax.finish()
  currentCtx → {T1, S_op} ✅

span_op.finish()
  currentCtx → null ✅

场景 B：无业务 Span，纯 HTTP 拦截

初始: currentCtx = null

axios.get('/api/users')
  ctx = createRootCtx() = {T1, ''}
  startSpan({T1,''}, 'GET:/api/users')
    prevCtx_ax = null
    currentCtx = {T1, S_ax}, _noAutoFinish = true

[响应拦截器] span_ax.finish()
  currentCtx → null ✅

场景 C：为什么 HTTP 拦截 Span 要 _noAutoFinish（Bug 复盘）

❌ 旧行为（已修复）：
  axios.get() → 创建 span，微任务 M1 调度 auto-finish
  [M1 早于网络回调运行]
  M1: span.finish(OK) → _done=true, _sc=0（状态码未知）
  [响应拦截器] span._done=true → 直接跳过 → HTTP 状态码丢失！

✅ 新行为（_noAutoFinish = true）：
  axios.get() → 创建 span，_noAutoFinish=true
  [M1 检测到 _noAutoFinish=true，跳过]
  [响应拦截器] span._sc=200, span.finish(OK) → 精确记录 ✅

2.3 并行场景注意事项

并行场景下 currentCtx 会被最后一个 startSpan 覆盖，并行时应显式传入 parentCtx：

// ✅ 并行推荐写法
const [rootCtx, rootSpan] = $trace.startSpan(null, 'root');
const [, spanA] = $trace.startSpan(rootCtx, 'A');
const [, spanB] = $trace.startSpan(rootCtx, 'B');

---

三、环境兼容性

环境	Worker 模式	降级模式	链路头注入	说明
现代浏览器（Chrome/Firefox/Safari）		—
Android WebView ≥ 4.4		—
Android WebView < 4.4		（localStorage）
iOS WKWebView		—
iOS UIWebView（已废弃）		（localStorage）
Electron Renderer		—
微信小程序 WebView		（内存）
Node.js ≥ 18		（内存）		fetch 原生支持
Node.js 16–17		（内存）		需全局注入 fetch polyfill
UniApp H5		—		Worker 模式，与浏览器一致
UniApp App（原生）	（WebView ）	（uni.setStorageSync）		WebView 中 H5 页面支持 Worker
UniApp 微信小程序	（WebView ）	（uni.setStorageSync）		WebView 中 H5 页面支持 Worker
UniApp 支付宝小程序		（uni.setStorageSync）

Node.js 注意： 始终走内存降级模式；SIGKILL 时数据不可避免丢失。

UniApp 注意： Worker 仅 H5 端生效；存储/上报层自动切换；页面隐藏需手动调用 onAppHide()。

---

四、多框架接入指南

SDK 已发布至 npm：@autoxing/front-trace

安装

npm install @autoxing/front-trace

---

4.1 浏览器 Script 标签（CDN，无需安装）

<script src="https://unpkg.com/@autoxing/front-trace/dist/trace-sdk.umd.min.js"></script>
<script>
  window.$trace.init({
    ENABLE:          true,
    SERVICE_NAME:    'my-web-app',
    UPLOAD_URL:      'https://trace.example.com/trace/v1.0/upload',
    UPLOAD_INTERVAL: 5000,
  });
  // 如使用 axios
  window.$trace.initAxiosInterceptor(axios);
</script>

---

4.2 npm / CommonJS（Node.js / webpack）

const $trace = require('@autoxing/front-trace');

$trace.init({
  ENABLE:       true,
  SERVICE_NAME: 'my-node-service',
  UPLOAD_URL:   'https://trace.example.com/trace/v1.0/upload',
});

// Node.js 16-17 需先注入 fetch polyfill
// globalThis.fetch = require('node-fetch');

---

4.3 Vue 插件（Vue 2 / Vue 3）

Vue 3（推荐）：

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import axios from 'axios';
import $trace from '@autoxing/front-trace';

$trace.init({
  ENABLE:       true,
  SERVICE_NAME: 'my-vue3-app',
  UPLOAD_URL:   'https://trace.example.com/trace/v1.0/upload',
});
$trace.initAxiosInterceptor(axios);

const app = createApp(App);
app.use($trace);   // 注册 Vue 插件，组件内可用 this.$trace
app.mount('#app');

注意： app.use($trace, opts) 内部会调用 init(opts)，与手动 init() 二选一即可。推荐先手动 init() + initAxiosInterceptor()，初始化位置更明确。

Vue 2：

import Vue from 'vue';
import axios from 'axios';
import $trace from '@autoxing/front-trace';

$trace.init({ ENABLE: true, SERVICE_NAME: 'my-vue2-app', UPLOAD_URL: '...' });
$trace.initAxiosInterceptor(axios);
Vue.use($trace);

---

4.4 UniApp（全端兼容）

① main.js 初始化（最早执行位置）：

// main.js（UniApp Vue 3）
import { createSSRApp } from 'vue';
import App from './App.vue';
import $trace from '@autoxing/front-trace';

$trace.init({
  ENABLE:       true,
  SERVICE_NAME: 'my-uniapp',
  UPLOAD_URL:   'https://trace.example.com/trace/v1.0/upload',
});
// init() 在 UniApp 环境下自动调用 initUniRequestInterceptor()，拦截 uni.request，无需手动调用

// ⚠️ 如果项目中同时使用了 axios，需额外手动调用：
// import axios from 'axios';
// $trace.initAxiosInterceptor(axios);

export function createApp() {
  const app = createSSRApp(App);
  return { app };
}

② App.vue 桥接页面隐藏事件（重要）：

<!-- App.vue -->
<script>
import $trace from '@autoxing/front-trace';
export default {
  onHide() {
    // UniApp 小程序/App 无 pagehide，需手动桥接触发上报
    $trace.onAppHide();
  },
};
</script>

UniApp 各端能力对比：

端	Worker	持久化	上报方式	卸载事件
H5		IndexedDB → localStorage	fetch	pagehide（自动）
App（原生）		uni.setStorageSync	uni.request	手动 onAppHide()
微信小程序		uni.setStorageSync	uni.request	手动 onAppHide()
支付宝小程序		uni.setStorageSync	uni.request	手动 onAppHide()

---

五、API 参考

5.1 $trace.init(options?)

初始化 SDK。ENABLE 默认为 false，必须显式设为 true 才会真正启动。

npm / UniApp 模式下必须手动调用；浏览器 Script 引入时已自动调用（但仍需配置 ENABLE: true）。

支持多次调用，后调用的配置合并覆盖。配置项详见第九章。

5.2 $trace.initAxisInterceptor()

拦截全局 Axis 对象（window.Axis / global.Axis），自动注入链路头并记录 Span。ENABLE=false 时直接 return。

5.3 $trace.initAxiosInterceptor(axiosInstance?)

拦截 axios，通过 axios.interceptors.request/response.use 注入。ENABLE=false 时直接 return。

// 方式1：拦截全局 axios（自动查找 window.axios / 全局 axios）
$trace.initAxiosInterceptor();

// 方式2：直接传入 import 的 axios 对象（推荐，适用于 Vue/UniApp 等模块化项目）
import axios from 'axios';
$trace.initAxiosInterceptor(axios);

// 方式3：拦截自定义 axios 实例
const instance = axios.create({ baseURL: 'https://api.example.com' });
$trace.initAxiosInterceptor(instance);

5.4 $trace.initUniRequestInterceptor()

拦截 uni.request（UniApp 专用）。init() 在 UniApp 环境下自动调用，通常无需手动调用。ENABLE=false 时直接 return。

5.5 $trace.startSpan(parentCtx, name)

开启一个 Span，返回 [childCtx, span]。ENABLE=false 时返回无副作用的 noop span（所有方法均可正常调用，但不记录任何数据）。

参数	类型	说明
parentCtx	object | null	父上下文。传 null 时：若 currentCtx 不为 null 则挂在当前上下文，否则创建新根链路
name	string	Span 名称

返回值	说明
childCtx	传给下一个 startSpan：传相同 ctx → 并行；传 childCtx → 嵌套
span	同步操作默认微任务自动 finish；异步操作手动调用 span.finish() 精确计时

5.6 Span 方法一览

所有方法均支持链式调用（返回 this），且 ENABLE=false 时均为 noop，不会报错。

方法	对应 Go 策略	上报字段	说明
span.finish(status?)	span.End()	—	结束 Span，自动恢复 currentCtx。status 默认 SpanStatus.OK
span.setTag(key, value)	StartSpan(tags)	ops[].tgs	设置单个 Tag
span.setTags({k:v,...})	StartSpan(tags)	ops[].tgs	批量设置 Tags
span.addEvent(name, data?)	AddSpanEvent()	ops[].evs[]{n,t,d}	记录事件，t 为 Unix 纳秒
span.recordError(err, attrs?)	RecordError()	ops[].ers[]{er,t,as}	记录错误，同时将首条错误写入顶层 em
span.setBizStatus(code, msg)	SetBizResponse()	顶层 bs + bm	设置业务状态码和消息，仅根 Span 生效

5.7 $trace.SpanStatus

$trace.SpanStatus.OK    // 'ok'
$trace.SpanStatus.ERROR // 'error'

5.8 业务身份 API（权限检索的核心）

业务身份字段是 trace-worker 诊断系统按权限检索链路的核心维度。正确设置这三个 ID，可以：

• 按用户检索：查找某用户的所有历史调用链路
• 按业务/楼层检索：定位某业务模块的异常分布
• 按设备/机器人检索：追踪特定机器的所有操作记录
• 按用户+设备组合过滤：精确分析某用户操作某机器时的完整行为链路

SDK 提供三个身份设置方法，分别对应 trace-worker 中的检索索引，建议在全链路关键节点都正确设置：

方法	对应 Go diagnosis.Span 字段	trace-worker 检索字段	生命周期
$trace.setUserId(id)	UserID（uid）	user_id	登录后调用一次，持久存在，直到退出登录
$trace.setBusinessId(id)	BusinessID（bid）	business_id	事件触发时设置，事件结束后调用 clearEventContext() 清空
$trace.setDeviceId(id)	DeviceID（did）	device_id	事件触发时设置，事件结束后调用 clearEventContext() 清空
$trace.clearEventContext()	—	—	清空 businessId + deviceId，不影响 userId

设计原则（重要）：

• userId — 登录态唯一标识（如 openId），调用 setUserId() 后在当前页面生命周期内持续有效，每次上报的 Trace 对象中自动附带 uid 字段。退出登录时调用 setUserId('') 清除。
• businessId / deviceId — 属于 事件级上下文，在触发特定业务操作（如选中某楼层、绑定某台机器人）时设置，操作完成后必须调用 clearEventContext() 清空，否则会污染后续无关事件的 Span（导致诊断系统将不相关的操作归因到错误的业务/设备维度）。
• 三者可以同时存在，诊断系统支持按任意维度组合过滤。例如 userId + deviceId 的组合可精确检索"某用户在某机器人上的全部操作链路"。

典型业务身份注入链路示例：

// 1. 用户登录 → 全局设置 userId（持续有效）
$trace.setUserId(userInfo.openId);

// 2. 用户进入某个业务楼层 → 设置 businessId
$trace.setBusinessId(currentBiz.id);
// 此时所有 Span 自动携带 uid + bid

// 3. 用户选择某台机器人执行任务 → 设置 deviceId
$trace.setDeviceId(selectedRobot.serialNo);
// 此时所有 Span 携带 uid + bid + did

// 4. 执行任务操作...
const [, span] = $trace.startSpan(null, 'sendTask');
await axios.post('/api/robot/task', { ... });
span.finish();

// 5. 任务完成 → 清空事件级上下文（userId 保留）
$trace.clearEventContext();
// 后续 Span 只携带 uid，不再携带 bid/did

// 6. 用户退出登录 → 清除 userId
$trace.setUserId('');

5.9 $trace.onAppHide()（UniApp 专用）

在 App.vue 的 onHide 中调用，触发页面隐藏时的立即上报。

5.10 $trace.install(app, options?)（Vue 插件）

Vue 插件接口，等价于 init(options) + 挂载 this.$trace，通过 app.use() / Vue.use() 调用。

5.11 $trace.setCtx(ctx)（高级）

强制设置 currentCtx，用于 SPA 路由切换等需要手动管理上下文的场景。ENABLE=false 时直接 return。

---

六、使用示例

四条核心规则

1. startSpan(null, name) → 有 currentCtx 则挂在当前链路，否则自动创建新根链路
2. 相同 ctx 传给多个 startSpan → 并行（兄弟节点）
3. 用 childCtx 作为下一个 startSpan 的父 → 嵌套（父子节点）
4. HTTP 拦截器自动挂在 currentCtx 下，finish 后自动恢复，最终保证为 null

---

6.1 最简用法（HTTP 拦截自动追踪，零侵入）

// init + initAxiosInterceptor 后，所有 axios 请求自动追踪，无需业务侧任何改动
axios.get('/api/user/list');
axios.post('/api/order/create', { items: [] });

---

6.2 业务 Span + HTTP 请求自动挂载

async function handleLogin(username, password) {
  const [, loginSpan] = $trace.startSpan(null, 'login');
  try {
    await axios.post('/api/auth/login', { username, password });
    loginSpan.finish($trace.SpanStatus.OK);
  } catch (e) {
    loginSpan.recordError(e).finish($trace.SpanStatus.ERROR);
    throw e;
  }
}

链路图：

login
  └── POST:/api/auth/login   ← axios 自动挂在 login 下

---

6.3 嵌套追踪（父子 Span）

async function handleLogin(username, password) {
  const [ctx1, validateSpan] = $trace.startSpan(null, 'login:validateParams');
  validateInput(username, password); // 同步，微任务自动 finish

  const [ctx2, loginSpan] = $trace.startSpan(ctx1, 'login:request');
  await axios.post('/api/auth/login', { username, password })
    .then(() => loginSpan.finish($trace.SpanStatus.OK))
    .catch(e => { loginSpan.recordError(e).finish($trace.SpanStatus.ERROR); throw e; });

  const [, profileSpan] = $trace.startSpan(ctx2, 'login:fetchProfile');
  await axios.get('/api/user/profile')
    .then(() => profileSpan.finish($trace.SpanStatus.OK))
    .catch(e => { profileSpan.recordError(e).finish($trace.SpanStatus.ERROR); });
}

链路图：

login:validateParams
  └── login:request
        └── login:fetchProfile

---

6.4 并行追踪（兄弟 Span）

async function loadUserPage(userId) {
  const [rootCtx, rootSpan] = $trace.startSpan(null, 'loadUserPage');
  const [, profileSpan] = $trace.startSpan(rootCtx, 'fetchProfile');
  const [, ordersSpan]  = $trace.startSpan(rootCtx, 'fetchOrders');

  await Promise.allSettled([
    axios.get('/api/user/profile', { params: { userId } })
      .then(() => profileSpan.finish($trace.SpanStatus.OK))
      .catch(e => profileSpan.recordError(e).finish($trace.SpanStatus.ERROR)),
    axios.get('/api/user/orders', { params: { userId } })
      .then(() => ordersSpan.finish($trace.SpanStatus.OK))
      .catch(e => ordersSpan.recordError(e).finish($trace.SpanStatus.ERROR)),
  ]);
  rootSpan.finish($trace.SpanStatus.OK);
}

链路图：

loadUserPage
  ├── fetchProfile
  └── fetchOrders

---

6.5 Tags / Event / Error / BizStatus（全功能示例）

async function sendRobotTask(robot, task) {
  const [, span] = $trace.startSpan(null, 'sendRobotTask');

  // 设置 Tags（对应 Go StartSpan(tags) → ops[].tgs）
  span.setTags({ robotId: robot.serialNo, taskType: task.type, priority: task.priority });

  // 记录事件（对应 Go AddSpanEvent → ops[].evs）
  span.addEvent('task.prepared', { taskId: task.id });

  try {
    const res = await axios.post('/api/robot/task', task);

    span.addEvent('task.submitted', { serverTaskId: res.data.taskId });

    // 设置业务状态码（对应 Go SetBizResponse → trace.bs + trace.bm）
    // 仅根 Span 生效，写入顶层 trace 对象
    if (res.data.code !== 200) {
      span.setBizStatus(res.data.code, res.data.message);
    }

    span.finish($trace.SpanStatus.OK);
  } catch (e) {
    // 记录错误（对应 Go RecordError → ops[].ers）
    span.recordError(e, { phase: 'http', robotId: robot.serialNo });
    span.finish($trace.SpanStatus.ERROR);
    throw e;
  }
}

---

6.6 业务身份注入（userId / businessId / deviceId）

重要： userId、businessId、deviceId 是 trace-worker 诊断系统按权限检索链路的核心字段。 正确设置这三个 ID 才能在后端实现按用户、楼层、机器人的链路检索和异常分析。 三者关系：userId 登录态持久有效，businessId/deviceId 事件级需及时清空。

// ─── 登录成功后（全局执行一次）────────────────────────────────────
$trace.setUserId(userInfo.openId);   // 持久存在，整个会话有效

// ─── 用户选择业务楼层 + 机器人，开始操作 ─────────────────────────
$trace.setBusinessId(currentBiz.id);
$trace.setDeviceId(selectedRobot.serialNo);

// 此后所有 Span 自动携带 uid/bid/did
const [, span] = $trace.startSpan(null, 'sendTask');
await axios.post('/api/robot/task', payload);
span.finish($trace.SpanStatus.OK);

// ─── 操作完成，清空事件级上下文 ─────────────────────────────────
$trace.clearEventContext();   // businessId + deviceId 清空；userId 保留
// 此后的 Span 只携带 uid，不携带 bid/did

---

6.7 SPA 路由切换追踪

let _routeSpan = null;

router.beforeEach((to, from, next) => {
  const [routeCtx, routeSpan] = $trace.startSpan(null, `navigate:${to.path}`);
  $trace.setCtx(routeCtx);
  _routeSpan = routeSpan;
  next();
});

router.afterEach(() => {
  if (_routeSpan) {
    _routeSpan.finish($trace.SpanStatus.OK);
    _routeSpan = null;
  }
});

---

七、与 Go Tracer 的链路对接

7.1 链路头对照

前端注入头	Go 常量	后端行为
x-trace-id: {traceId}	liteTraceHeaderTraceID	后端提取作为本次请求的 TraceID
x-span-id: {spanId}	liteTraceHeaderSpanID	后端以此作为 ParentSpanID，前端 Span 成为后端 Span 的父节点
traceparent: 00-{tid}-{sid}-01	W3C traceparent	兼容 APISIX 网关、OpenTelemetry 生态
x-trace-sample: 1	liteTraceHeaderSample	告知后端强制采样此请求

重要： 这些链路头只注入到出站 HTTP 请求中，不写入上报数据包（hs 字段已移除）。

7.2 前后端链路连接原理

前端 Span（traceId=AAA, spanId=111, parentSpanId=''）
  └── HTTP 请求携带 x-trace-id=AAA, x-span-id=111
        │
        ▼
   Go 后端 Middleware
        ├── 提取 x-trace-id=AAA → 本次 TraceID=AAA
        └── 提取 x-span-id=111  → ParentSpanID=111
              │
              ▼
        后端 Span（traceId=AAA, spanId=222, parentSpanId=111）

7.3 业务身份字段传递路径与权限检索

前端 SDK 直接写入 uid/bid/did 字段上报；后端服务通过 HTTP Header（x-openid / x-business-id / x-device-id）传递。trace-worker 的 toSpans 转换时优先取直接字段，为空时从 Header 回落：

前端上报：{ uid: "user123", bid: "biz456", did: "robot789" }
                │
                ▼
        trace-worker toSpans
                │  ct.UserID != ""     → 直接使用
                │  ct.UserID == ""     → headers["x-openid"]
                │  ct.BusinessID != "" → 直接使用
                │  ct.BusinessID == "" → headers["x-business-id"]
                │  ct.DeviceID != ""   → 直接使用
                │  ct.DeviceID == ""   → headers["x-device-id"]
                ▼
        diagnosis.Span { UserID: "user123", BusinessID: "biz456", DeviceID: "robot789" }

权限检索说明： trace-worker 诊断系统对 uid / bid / did 字段建立了独立索引，支持以下三种检索模式：

• 按用户检索（user_id 索引）：查询指定用户的所有历史链路，用于用户行为回溯和故障排查
• 按业务/楼层检索（business_id 索引）：定位特定业务模块的异常分布和性能基线
• 按设备/机器人检索（device_id 索引）：追踪特定设备的全量操作记录
• 组合检索：支持 user_id + device_id、business_id + device_id 等多维组合过滤

因此前端 SDK 正确设置 userId / businessId / deviceId 是诊断系统正常运行的前提。 建议在全链路的关键操作节点（登录、选业务、选设备、事件完成）都调用对应 API，确保身份维度不遗漏。

7.4 上报接口（trace-worker）

前端 SDK 上报到 trace-worker 服务：

POST /trace/v1.0/upload
Content-Type: application/json
Body: [childTrace, ...]   ← JSON 数组，批量上报

trace-worker 收到后：

1. 从请求中提取真实客户端 IP，注入每条 trace 的 cip 字段（自动处理反向代理）
2. 批量 InsertMany 直接入库（ax_raw_spans MongoDB 集合）
3. 与 Kafka 消息路径完全等价，经 WorkerManager 重放到诊断流程

---

八、上报数据格式

每次上报的 JSON Body 为 Trace 对象数组，与 Go Tracer Kafka 消息（childTrace）格式完全兼容：

[
  {
    "tid": "ce6e59474608400281a57beb3da5576f",
    "st":  1779263662070000000,
    "et":  1779263662829100000,
    "m":   "POST",
    "p":   "/api/robot/task",
    "sc":  200,
    "pid": "",
    "sid": "e9f9e784a3ab40b380d21a233ea35dcc",
    "sn":  "robot-h5",
    "sip": "frontend",
    "uid": "oHrGS5bNcK0waXofc5WGNm8TJXxY",
    "bid": "biz-floor-3",
    "did": "robot-SN-00123",
    "bs":  4001,
    "bm":  "任务队列已满",
    "ops": [
      {
        "n":   "sendRobotTask",
        "sid": "a1b2c3d4e5f60001",
        "pid": "",
        "st":  1779263662070000000,
        "et":  1779263662100000000,
        "tgs": { "taskType": "navigate", "priority": 1 },
        "evs": [
          { "n": "task.prepared", "t": 1779263662075000000, "d": { "taskId": "T001" } },
          { "n": "task.submitted", "t": 1779263662095000000, "d": { "serverTaskId": "S999" } }
        ]
      }
    ]
  }
]

8.1 顶层 Trace 字段

字段	类型	Go childTrace	SDK 填写	说明
tid	string	tid		TraceID（32位hex）
st	int64	st		开始时间，Unix 纳秒（JS ms × 1,000,000）
et	int64	et		结束时间，Unix 纳秒
m	string	m		HTTP 方法（GET/POST/...）或 FRONTEND（手动 Span）
p	string	p		URL 路径部分（去掉 scheme://host），或操作名
sc	int	sc		HTTP 状态码（由响应拦截器精确记录）
pid	string	pid		上游 SpanID（空 = 根链路）
sid	string	sid		本 Span 的 SpanID
sn	string	sn		服务名（CONFIG.SERVICE_NAME）
sip	string	sip		固定值 "frontend"，标识来源为前端
cip	string	cip	服务端注入	客户端真实 IP，由 trace-worker 从请求头提取
em	string	em	（可选）	错误信息，recordError() 首条或 finish(ERROR) 时写入
bs	int	bs	（可选）	业务状态码，setBizStatus(code, msg) 写入，仅根 Span 生效
bm	string	bm	（可选）	业务状态消息，配合 bs 使用
uid	string	uid	（可选）	用户 ID，setUserId() 设置后自动附带
bid	string	bid	（可选）	业务 ID，setBusinessId() 设置后自动附带
did	string	did	（可选）	设备/机器人 ID，setDeviceId() 设置后自动附带
hs	—	hs	不上报	W3C 链路头只注入出站请求，不写入数据包
ops	array	ops		子操作列表

8.2 ops[] 子操作字段（对应 Go childOp）

字段	类型	Go childOp	说明
n	string	n	子操作名称
sid	string	sid	子 Span ID
pid	string	pid	父 Span ID
st	int64	st	开始时间，Unix 纳秒
et	int64	et	结束时间，Unix 纳秒
tgs	object	tgs	Tags，setTag/setTags() 写入（可选）
evs	array	evs	事件列表，addEvent() 写入（可选）
evs[].n	string	n	事件名称
evs[].t	int64	t	事件时间，Unix 纳秒
evs[].d	object	d	事件附加数据
ers	array	ers	错误列表，recordError() 写入（可选）
ers[].er	string	er	错误描述
ers[].t	int64	t	错误发生时间，Unix 纳秒
ers[].as	object	as	错误附加属性

时间精度： JS Date.now() 精度为毫秒，统一 × 1,000,000 转为纳秒，与 Go time.Now().UnixNano() 一致。

---

九、配置项说明

配置项	类型	默认值	说明
ENABLE	boolean	false	总开关。默认关闭，代码集成后功能完全静默；显式设为 true 才启动
SERVICE_NAME	string	'frontend'	服务名，写入 sn 字段，建议按项目设置（如 'robot-h5'）
MAX_SPANS	number	500	内存队列最大 Span 数，超限按完整链路丢弃最旧
UPLOAD_INTERVAL	number	3000	定时上报间隔（ms）
UPLOAD_BATCH	number	50	单次上报最大 Trace 条数
EXPIRE	number	604800000（7天）	持久化数据过期时间（ms）
UPLOAD_URL	string | string[]	'/trace/v1.0/upload'	上报接口地址，支持单地址字符串或多地址数组
UPLOAD_URL_SELECTION	string	'random'	多地址选择策略：'random'（随机）/ 'round-robin'（轮询）/ 'primary'（主节点，仅失败时切换）
UPLOAD_HEADERS	object	{'Authorization': 'APPCODE c328ac72cc814008a5c664c637cab8ab'}	上报请求自定义 Header，未填时自动补充默认 Authorization
WORKER_PATH	string	'./trace.worker.js'	Worker 文件路径，仅当 CSP 禁止 blob: 时才需配置
SAMPLE_RATE	number	1	采样率（1=全量采集；<1 按比例随机采样，如 0.1=10%）
SAMPLE_MIN_STATUS_CODE	number	0	最小强制采样状态码（如 400=所有 >=400 的状态码强制采样；0=不启用）
SAMPLE_STATUS_CODES	number[]	[]	特定状态码强制采样列表，如 [499, 502, 503]
SAMPLE_STATUS_CODE_FILTERS	number[]	[]	从强制采样中排除的状态码，如与 SAMPLE_MIN_STATUS_CODE 配合排除特定码
SAMPLE_RES_MIN_DURATION	number	0	最小强制采样耗时（ms），超过该时长的请求强制采样（0=不启用）
DEBUG	boolean	false	调试日志开关（true=输出 console.debug/warn；false=完全静默）

推荐生产配置：

// 单地址
$trace.init({
  ENABLE:          true,
  SERVICE_NAME:    'your-project-name',
  UPLOAD_URL:      'https://trace.example.com/trace/v1.0/upload',
  UPLOAD_INTERVAL: 5000,
});

// 多地址（随机负载均衡）
$trace.init({
  ENABLE:          true,
  SERVICE_NAME:    'your-project-name',
  UPLOAD_URL:      ['https://trace1.example.com/upload', 'https://trace2.example.com/upload'],
  UPLOAD_URL_SELECTION: 'random',
});

// 多地址（主备模式）
$trace.init({
  ENABLE:          true,
  SERVICE_NAME:    'your-project-name',
  UPLOAD_URL:      ['https://primary.example.com/upload', 'https://backup.example.com/upload'],
  UPLOAD_URL_SELECTION: 'primary',
});

// 采样控制 + 调试日志
$trace.init({
  ENABLE:                    true,
  SERVICE_NAME:              'robot-h5',
  UPLOAD_URL:                'https://trace.example.com/trace/v1.0/upload',
  UPLOAD_INTERVAL:           5000,
  SAMPLE_RATE:               0.5,            // 50% 随机采样
  SAMPLE_MIN_STATUS_CODE:    400,            // 所有 4xx/5xx 强制采样
  SAMPLE_RES_MIN_DURATION:   3000,           // 超过 3 秒的请求强制采样
  DEBUG:                     false,          // 关闭调试日志
});

按环境动态控制：

$trace.init({
  ENABLE:       process.env.NODE_ENV === 'production',
  SERVICE_NAME: 'robot-h5',
  UPLOAD_URL:   process.env.VUE_APP_TRACE_URL,
});

---

十、性能分析

10.1 主线程影响（Worker 模式）

操作	执行位置	主线程耗时
genId()	主线程	≈ 0.01ms
startSpan()	主线程	≈ 0.05ms
拦截器注入（axios/uni.request）	主线程	≈ 0.1ms，仅追加 4 个 Header
postMessage()	主线程→Worker	≈ 0.2ms
_shouldSample()（采样判定）	主线程	≈ 0.01ms
_groupToTraces()（分组排序+字段映射）	Worker	零主线程影响
IndexedDB 读写 / fetch 上报	Worker	零主线程影响

Worker 模式下，主线程除 startSpan() 和 postMessage() 外无任何数据计算开销，对 60FPS（16.7ms/帧）的影响可以忽略。

10.2 降级模式（无 Worker）主线程影响

操作	主线程耗时
_groupToTraces()（50条 Span）	≈ 0.5ms
_httpPost() / sendBeacon	异步，不阻塞
localStorage 读写	≈ 0.1ms

10.2 内存占用估算

项目	单条大小	500条上限
Span 对象（内存队列）	≈ 300 字节	≈ 150 KB
Trace 对象（持久化）	≈ 500 字节	≈ 250 KB
_retryQueue（重试队列）	≈ 500 字节	≈ 250 KB（与持久化共享）

10.3 数据可靠性

场景	机制	可靠性
正常关闭页面（浏览器）	sendBeacon
移动端切换 App（bfcache）	pagehide + sendBeacon
网络断开时关闭页面	IDB / localStorage 持久化，下次启动重试
上报失败（无持久化环境）	_retryQueue 内存重试队列，下次定时周期重试
Worker 崩溃	主线程降级自动接管
Node.js 正常退出	process.on('beforeExit') 异步上报
Node.js SIGTERM/SIGINT	同步清理 + process.exit()
Node.js SIGKILL	不可避免丢失	—

---

十一、已知局限与改进建议

优先级	问题	当前状态 / 建议方案
—	采样率控制	v1.0.14 已实现：SAMPLE_RATE + SAMPLE_STATUS_CODES + SAMPLE_MIN_STATUS_CODE + SAMPLE_RES_MIN_DURATION
高	Node.js 无持久化	_retryQueue 内存重试队列已兜底；进程崩溃仍不可避免丢失；可进一步定期序列化写文件
中	并行 HTTP 请求 currentCtx 无法精确分配	并行场景需显式传 ctx，见2.3 节
中	不支持原生 fetch / XMLHttpRequest 拦截	增加 initFetchInterceptor() / initXHRInterceptor()
低	无 $trace.getHeaders(span) 辅助	Node.js 手动注入链路头较繁琐，可封装辅助方法