Rollbar.js Telemetry 遥测深度解析：用『面包屑』快速还原用户报错现场的完整指南
【免费下载链接】rollbar.jsError tracking and logging from Javascript to Rollbar项目地址: https://gitcode.com/gh_mirrors/ro/rollbar.js
Rollbar.js 是一款从 JavaScript 前端到 Node.js 后端的错误追踪与日志上报库，其Telemetry（遥测）功能会自动采集用户操作过程中的"面包屑"——包括点击、表单输入、网络请求、页面跳转等关键事件，在报错瞬间随错误一并上报，帮你快速还原用户报错现场，告别"在我机器上是好的"这类难题。
上图为 Rollbar 面板中的错误详情页：左侧是 Traceback（堆栈），配合遥测数据可还原事件发生前后的完整上下文
为什么你需要 Telemetry 面包屑？
💡 想象这样一个场景：用户反馈"点击提交按钮后页面报错了"，但你只收到一条孤零零的错误堆栈——
- 用户之前点了什么？填了哪些表单？
- 报错前哪个接口返回了 500？
- 他是从哪个页面跳转过来的？
Telemetry 就是解决这些问题的"行车记录仪"。它在内存中维护一个环形队列，持续记录最近100 条事件（上限可在 src/telemetry.js 中查看，队列逻辑见MAX_EVENTS常量），当错误发生时，这些面包屑会随错误一起打包发送到 Rollbar 面板，让你像看回放一样重现报错现场。
面包屑是怎么记录的？Telemeter 核心源码解析
遥测的核心类是Telemeter，位于 src/telemetry.js，所有类型的面包屑最终都通过它的capture()方法入队。每个面包屑事件的结构非常清晰：
| 字段 | 含义 |
|---|---|
type | 事件类型：error/log/network/dom/navigation/connectivity |
level | 日志级别，默认由getLevel()推断（error 类为error，其余多为info） |
timestamp_ms | 事件发生的毫秒级时间戳 |
body | 事件的具体内容（metadata），如点击的 DOM 元素、请求的 URL 等 |
source | 来源，浏览器端固定为client |
uuid | 与该事件关联的 Rollbar 错误 ID（如有） |
几个值得新手注意的细节：
- 队列自动裁剪：
push()方法在队列超出maxQueueSize时会丢弃最旧的事件，保证内存占用恒定； - 支持过滤：通过
filterTelemetry配置函数，你可以决定某条面包屑是否入库（比如屏蔽敏感页面）； - 与 OpenTelemetry 打通：
captureError、captureNetwork等方法会同时向telemetrySpan写入 OTEL 事件，实现传统遥测与分布式追踪的双通道。
面包屑最终如何出现在错误上报里？答案在 src/transforms.js：它把item.telemetryEvents写入上报体的data.body.telemetry字段，一并发送给 Rollbar 后端。
自动插桩：六大类事件无需手动埋点
🎉 最省心的是，浏览器端几乎零配置。插桩逻辑集中在 src/browser/telemetry.js 的Instrumenter类中，默认开启（autoInstrument默认值见该文件顶部的defaults对象）：
1. 网络请求（network）
自动包裹XMLHttpRequest和fetch，记录方法、URL、请求头、响应头、耗时等。特别实用的是状态码分级：levelFromStatus()会将 200–399 标记为info，而 400+ 或 0（网络中断）自动标记为error级别。还可以开启networkErrorOnHttp5xx等选项，把 HTTP 错误直接当作 Rollbar 错误上报。
2. Console 日志（log）
包裹console.debug/info/warn/error/log五个方法，让开发者随手写的日志也进入面包屑时间线——排障时往往比堆栈更早暴露线索。
3. DOM 交互（dom）
通过事件委托监听全页面的：
- 点击：
click/dblclick/contextmenu - 输入：
input/change（含表单的submit/invalid） - 焦点：
focus/blur - 窗口尺寸变化：
resize（含缩放比例） - 拖拽：
dragstart/drop等
⚠️ 隐私提示：输入框的值默认会经过脱敏处理——password类型直接替换为******，还可配合scrubTelemetryInputs、scrubFields、telemetryScrubber等选项定制脱敏规则（逻辑见handleInput与scrubInputValue方法）。
4. 页面导航（navigation）
Hook 了history.pushState和onpopstate，记录单页应用（SPA）中每一次路由跳转的from → to，让你清楚用户从哪条路径走进了"雷区"。
5. 网络状态（connectivity）
监听online/offline事件——用户掉网往往是"提交失败"类工单背后的真正原因。
6. CSP 违规（contentSecurityPolicy）
监听securitypolicyviolation事件，安全策略拦截了什么资源一目了然。
快速上手：三个关键配置
只需在初始化 Rollbar 时微调autoInstrument配置即可定制采集范围，常见操作如下：
- 关闭某类采集：设置
autoInstrument: { dom: false }停止记录 DOM 交互； - 把 HTTP 错误变成错误上报：开启
networkErrorOnHttp4xx: true； - 过滤敏感面包屑：提供
filterTelemetry函数，返回true的事件将被丢弃。
配合maxTelemetryEvents（上限 100）控制保留条数，就能在信息量与上报体积之间取得平衡。
从面包屑到定位：如何高效排查问题
🔍 拿到一条带遥测的错误后，建议按这个顺序复盘：
- 先看时间线：按
timestamp_ms排序，还原用户最后 1 分钟的操作序列； - 锁定可疑网络请求：找到错误前最后一条
level: error的network事件，检查其 URL 与状态码； - 对照导航路径：通过
navigation事件确认用户进入报错页面前的完整跳转链； - 关联 OTEL 追踪：若已开启 tracing，可通过面包屑中的 span 信息跨前后端串联整条调用链。
这样"用户报错现场"就从一句干巴巴的Uncaught Error变成了一段可回放的完整故事。
写在最后
Rollbar.js 的 Telemetry 用最轻量的设计实现了"错误现场回放"：一个 100 条上限的环形队列 + 六大类零配置自动插桩 + 完善的脱敏机制。对新手而言，你几乎不需要写任何埋点代码，只要引入 Rollbar，面包屑就会默默记录一切，在关键时刻成为你定位问题的最强证人。
📌 想深入源码的同学，可以从这三个文件入手：遥测队列 src/telemetry.js、浏览器插桩 src/browser/telemetry.js、上报转换 src/transforms.js。
【免费下载链接】rollbar.jsError tracking and logging from Javascript to Rollbar项目地址: https://gitcode.com/gh_mirrors/ro/rollbar.js
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
