Rollbar.js Tracing 指南：如何快速打通前后端分布式追踪链路-开发者社区

Rollbar.js Tracing 指南：如何快速打通前后端分布式追踪链路

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

后端突然 500，日志里只剩报错堆栈：用户当时点了哪个按钮、走了哪段流程，无从确认。Rollbar.js Tracing 把浏览器里的一次操作和服务端错误挂到同一个 traceId 下，让这条前后端错误链路变得可查。

🧩 它解决什么问题：Trace、Span、Context 三个概念

传统错误追踪只告诉你"哪里报错了"，却不告诉你"整个请求经历了什么"。把浏览器到服务端的完整请求串起来，就是分布式追踪要干的事，而 Rollbar.js Tracing 基于OpenTelemetry（OTel，业界通用的可观测性数据模型）实现，你只需记住三件事：

Trace：一次完整请求的生命周期，用全局唯一的 traceId 标识
Span：请求中的某一段操作（一次接口调用、一个业务函数），用 spanId 标识，可挂在父 Span 之下
Context：装着 traceId 的"容器"，会沿着调用链自动带到下一层代码

前端和后端上报的 Span 只要携带同一个 traceId，Rollbar 就能把它们拼装成一条端到端链路。

⚡ 最快启用：一行配置 + withSpan 创建第一个追踪 Span

打开总开关

Tracing 默认是关闭的，初始化时打开tracing.enabled即可。此时 Rollbar 会自动创建 Tracer、SpanProcessor，并基于 sessionStorage 建一个 Session，会话标识随之持久化，同一次访问期间的多个 Span 都共享它（实现见 src/tracing/tracing.js 与 src/tracing/session.js）：

const rollbar = new Rollbar({ accessToken: 'YOUR_POST_CLIENT_ITEM_TOKEN', tracing: { enabled: true }, });

它做了什么：开启 Tracing 模块并自动创建会话，后续 Span 都会自动共享这个会话标识。

用 withSpan 包裹关键业务

主推写法是withSpan：回调执行期间它把当前 Span 设为"活跃 Span"，回调结束后自动恢复上下文，不需要你手动清理：

rollbar.tracing.withSpan('checkout-payment', { attributes: { orderId: '123' }, }, () => { callPaymentAPI(); rollbar.error(new Error('支付失败')); });

它做了什么：回调内上报的rollbar.error()会自动附带 trace_id、span_id、session_id，不用手写任何关联逻辑。若 Span 要跨多个异步步骤，可改用startSpan手动创建、最后调span.end()（src/tracing/span.js），还支持setAttribute加业务属性、addEvent记录关键事件。

🔁 一个 traceId 的旅程：上下文传播与 Span 上报

前端内部：子 Span 自动继承 traceId

在已有 Span 的上下文里再创建 Span 时，Tracer 会自动继承父级的 traceId，并生成新的 spanId 作为父引用（实现见 src/tracing/tracer.js）。维护"当前活跃的是哪个上下文"的是 ContextManager，支持进入/退出任意上下文（src/tracing/contextManager.js），所以嵌套的业务代码不用手动传 ID。

跨到后端：traceparent 头传递

前端请求后端时，会在请求头里带上 OTel 标准的traceparent（W3C Trace Context 格式，内容就是 traceId 加当前 spanId）：

traceparent: 00-<traceId>-<spanId>-01

它做了什么：把上下文写进请求头，服务端 SDK 读取后继续以同一个 traceId 创建 Span——这样即使错误最终抛在服务端，你也能回溯到前端触发它的操作。

上报：监听结束事件，按 OTLP 批量导出

SpanProcessor：监听 Span 的onStart/onEnd事件，配置tracing.transformSpan可以在导出前修改 Span（src/tracing/spanProcessor.js）
SpanExporter：把 Span 转成 OTLP（OpenTelemetry 标准传输格式），按 instrumentation scope（SDK 模块标识）分组，经api.postSpans批量上报到 session 端点；默认端点在 src/tracing/defaults.js，换成自建 OTel 收集器只需改这里（src/tracing/exporter.js）

🔍 在控制台验证链路：附 3 个常见坑

触发一次带 Span 的错误后，打开 Rollbar 控制台的 Items 页面：错误条目会带频率统计与 Traceback 详情，其中 Trace 信息可点击，一键跳转查看完整调用链。完整的错误与 Span 关联断言见 test/browser.rollbar.test.ts。

三个常见坑：

没开总开关：tracing.enabled默认 false，不写这一项就不会有任何 Span 上报，控制台自然是空的
Session 依赖 sessionStorage：开新标签页或清除站点数据都会产生新会话，别期待跨端共享会话 ID
错误报在回调外：withSpan回调之外的rollbar.error()拿不到活跃上下文，错误不会关联到任何 Span

📋 Rollbar.js Tracing 配置速查

配置项	作用	说明
`tracing.enabled`	总开关，默认`false`	src/tracing/defaults.js
`tracing.endpoint`	Span 上报地址	默认 session 端点，可替换自建收集器
`tracing.transformSpan`	导出前自定义修改 Span	src/tracing/spanProcessor.js
`payload.environment`	环境名，自动写入 Resource 属性	src/tracing/tracing.js