Flashduty RUM 分布式追踪最佳实践：实现前后端请求链路的完整监控
当用户反馈"页面加载慢"或"操作没有响应"时，问题可能出在前端渲染、网络传输，也可能出在后端服务。如何快速定位根因？Flashduty RUM 的 Trace 追踪功能正是为此而生——它将前端用户监控与分布式追踪系统深度集成，让你一目了然地查看完整的前后端请求链路。
本文将详细介绍如何配置和使用这一功能，帮助你实现端到端的性能监控和问题排查。
为什么需要前后端链路关联？
传统的监控方式中，前端和后端往往是"各管各的"：前端团队只看到请求发出去了，后端团队只看到请求进来了，但两者之间缺乏关联。这导致了几个常见痛点：
- 排查效率低：前端发现请求慢，但不知道后端哪个环节出了问题；后端看到慢请求，但不知道影响了哪些用户
- 沟通成本高：前后端团队需要反复对齐时间戳、请求参数来定位同一个请求
- 问题遗漏多：一些间歇性问题因为缺乏完整链路数据，难以复现和定位
Flashduty RUM 的 Trace 追踪功能通过在前端请求中注入追踪信息，将前后端数据串联起来，彻底解决这些问题。
工作原理
Trace 追踪基于 W3C Trace Context 标准实现，整个工作流程如下：
- 前端发起请求：RUM SDK 自动为配置的 API 请求添加
traceparent和tracestate请求头 - 后端接收处理：后端服务解析追踪头信息，继续在内部调用链路中传递
- 链路关联：前后端通过相同的
trace_id建立关联 - 可视化展示：在 RUM 查看器中查看完整的请求链路信息，或跳转到 trace 系统查看详情
追踪头信息详解
RUM SDK 会在请求中自动添加两个 HTTP 头：
traceparent 头（核心追踪信息）：
traceparent: 00-00000000000000008448eb211c80319c-b7ad6b7169203331-01
格式为 [version]-[trace-id]-[parent-id]-[trace-flags]：
| 字段 | 说明 |
|---|---|
version |
协议版本，当前为 00 |
trace-id |
128 位的 trace ID，16 进制处理后为 32 个字符 |
parent-id |
64 位的 span ID，16 进制处理后为 16 个字符 |
trace-flags |
采样标志，01 表示命中采样，00 表示非采样 |
tracestate 头（附加追踪状态）：
tracestate: dd=s:1;o:rum
其中 s:1 表示 trace 被采样，o:rum 表示数据来源为 RUM SDK。
配置步骤
第一步：SDK 配置
在 RUM SDK 初始化时添加追踪相关参数：
import { flashcatRum } from "@flashcatcloud/browser-rum";
flashcatRum.init({
applicationId: "<YOUR_APPLICATION_ID>",
clientToken: "<YOUR_CLIENT_TOKEN>",
service: "<SERVICE_NAME>",
env: "<ENV_NAME>",
version: "1.0.0",
sessionSampleRate: 100,
allowedTracingUrls: [
"https://api.example.com",
/https:\/\/.*\.my-api-domain\.com/,
url => url.startsWith("https://api.example.com"),
],
traceSampleRate: 20,
});
关键参数说明：
-
allowedTracingUrls（必填）：指定需要添加追踪信息的 API 端点，支持三种匹配方式：- 字符串：匹配以该值开头的 URL，如
"https://api.example.com" - 正则表达式：使用正则匹配 URL，如
/https:\/\/.*\.my-api-domain\.com/ - 函数：自定义匹配逻辑，如
(url) => url.startsWith("https://api")
- 字符串：匹配以该值开头的 URL，如
-
traceSampleRate（可选，默认 100）：追踪采样率，范围 0-100，控制多少比例的请求会被追踪
第二步：应用管理配置
SDK 配置完成后，在 Flashduty 控制台进行 trace 跳转配置：
- 进入应用管理页面
- 选择对应的 RUM 应用
- 配置 trace 系统的跳转地址（如已集成分布式追踪系统）
- 在高级配置中启用 Trace 追踪功能
在配置的跳转链接中，系统会自动将
${trace_id}替换为实际的 trace_id，方便直接跳转到对应的追踪详情页。
第三步：后端服务配置
后端服务需要做以下适配：
- 接收追踪头信息：正确解析
traceparent和tracestate请求头 - 传递追踪信息：在调用下游服务时继续传递追踪头信息
- 生成追踪数据：将请求处理过程记录到追踪系统中
大多数主流分布式追踪系统（如 Jaeger、Zipkin、OpenTelemetry Collector）都已内置对 W3C Trace Context 的支持，通常只需要简单配置即可。
使用场景
在 RUM 查看器中查看 Trace
配置完成后，在 RUM 查看器的 View 视图 中可以直接查看 trace 信息：
- 进入 RUM 查看器
- 选择包含 API 调用的页面视图
- 在视图详情中查看 Trace 信息
- 点击 trace 链接跳转至 trace 系统查看完整链路
通过 trace_id 查找资源
你也可以通过 trace_id 在查看器中进行资源查找：
- 在查看器搜索栏中输入
trace_id - 查看对应的资源和视图加载情况
- 分析资源加载性能与后端 API 调用的关联关系
也可以通过在 URL 上拼接参数直接查询相应的 resource：
https://console.flashcat.cloud/rum/explorer?appid=${YOUR_APP_ID}&end=${END_TIME}&eventType=resource&queryStr=trace_id%3A${TRACE_ID}&start=${START_TIME}其中start、end、appid均为选填参数，若不传则会复用当前默认查询的应用和时间范围。
端到端问题排查
当用户报告性能问题或异常时，可以按以下步骤排查：
- 定位用户会话：在 RUM 查看器中找到问题用户的会话
- 查看 trace 信息：查看问题页面的 trace 信息
- 分析请求链路：跳转到 trace 系统查看完整的请求链路
- 定位问题根因：判断是前端问题、服务问题，还是网络问题
最佳实践
1. 合理配置采样率
不同环境建议使用不同的采样率：
| 环境 | 建议采样率 | 说明 |
|---|---|---|
| 开发环境 | 100% | 确保所有请求都被追踪，方便调试 |
| 测试环境 | 50-80% | 平衡监控覆盖率和性能影响 |
| 生产环境 | 10-20% | 避免对应用性能造成显著影响 |
2. 精确配置追踪 URL
推荐做法 — 精确匹配 API 端点：
allowedTracingUrls: ["https://api.example.com/v1/", "https://api.example.com/v2/"];
避免做法 — 过于宽泛的匹配可能包含不需要追踪的静态资源：
// 不推荐：可能会追踪到静态资源请求
allowedTracingUrls: ["https://api.example.com"];
3. 跨域请求处理
如果 HTTP 请求涉及跨域，需要确保：
- 服务器配置了正确的 CORS 头信息
- 支持预检请求（Preflight Request）
Access-Control-Allow-Headers中包含traceparent和tracestate
4. 持续监控与优化
- 定期检查 trace 采样率对应用性能的影响
- 监控追踪数据的存储和查询性能
- 根据业务需求动态调整追踪策略
常见问题
为什么某些请求没有 trace 信息？
可能的原因包括：
- 请求 URL 不在
allowedTracingUrls配置范围内 - 请求被
traceSampleRate采样率过滤 - 请求在 SDK 初始化之前发起
- 跨域请求缺少必要的 CORS 配置
如何验证 trace 配置是否正确？
可以通过以下方式验证：
- 在浏览器开发者工具中检查网络请求头，确认包含
traceparent和tracestate - 在 RUM 查看器中查看是否有 trace 信息显示
- 在后端追踪系统中搜索对应的
trace_id，验证链路是否完整
总结
Flashduty RUM 的分布式追踪功能，基于 W3C Trace Context 标准，为前后端链路关联提供了开箱即用的解决方案。通过简单的三步配置（SDK 初始化、应用管理配置、后端适配），即可实现端到端的请求链路监控，大幅提升问题排查效率。
更多详细配置请参考 官方文档。
