跳转到主要内容

​
概述

Flashduty RUM 的 Trace 追踪功能将前端用户监控与分布式追踪系统深度集成，让您能够将 Web 应用程序的请求与其对应的后端跟踪关联起来。这种组合使您能够一目了然地查看完整的前端和后端数据，实现端到端的性能监控和问题排查。 通过 Trace 追踪，您可以：
  • 关联前后端请求：将前端用户操作与后端 API 调用关联
  • 端到端问题排查：快速定位从前端到后端的完整请求链路问题
  • 性能瓶颈分析：识别整个请求链路中的性能瓶颈点
  • 用户体验优化：基于完整的请求链路数据优化用户体验

​
工作原理

Trace 追踪基于 W3C Trace Context 标准实现，通过在 HTTP 请求头中注入追踪信息来关联前后端请求：
1

前端发起请求

RUM SDK 自动为配置的 API 请求添加追踪头信息
2

后端接收处理

后端服务接收并处理带有追踪信息的请求
3

链路关联

通过相同的 trace_id 将前后端数据关联起来
4

可视化展示

通过 trace 关联根据 trace_id 查看完整的请求链路信息

​
配置步骤

​
1. SDK 配置

首先需要在 RUM 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
array
必填
指定需要添加追踪信息的 API 端点，支持以下类型：
类型说明示例
字符串匹配以该值开头的 URL"https://api.example.com"
正则表达式使用正则表达式匹配 URL/https:\/\/.*\.my-api-domain\.com/
函数自定义匹配逻辑，返回 true 表示匹配(url) => url.startsWith("https://api")
​
traceSampleRate
number
默认值:"100"
追踪采样率，控制多少比例的请求会被追踪（范围 0-100）
生产环境建议将 traceSampleRate 设置为 10-20，以平衡监控覆盖率和性能影响。

​
2. 应用管理配置

SDK 配置完成后，可在应用管理页面进行 trace 跳转相关配置：
  1. 进入 应用管理 页面
  2. 选择对应的 RUM 应用
  3. 配置 trace 系统的跳转地址（如已集成分布式追踪系统）
  4. 在 高级配置 中启用 Trace 追踪 功能
在配置的跳转链接中，系统会自动将 ${trace_id} 替换为实际的 trace_id。
Trace 追踪配置

Trace 追踪配置界面

​
3. 后端服务配置

为了完整支持分布式追踪，后端服务需要：
  1. 接收追踪头信息：处理 traceparent 和 tracestate 请求头
  2. 传递追踪信息：在调用其他服务时继续传递追踪头信息
  3. 生成追踪数据：将请求处理过程记录到追踪系统中

​
追踪头信息说明

RUM SDK 会在配置的请求中自动添加以下 HTTP 头信息：

​
traceparent 头

traceparent: 00-00000000000000008448eb211c80319c-b7ad6b7169203331-01
格式：[version]-[trace-id]-[parent-id]-[trace-flags]
字段说明
version当前为 00
trace-id128 位的 trace ID，16 进制处理后为 32 个字符
parent-id64 位的 span ID，16 进制处理后为 16 个字符
trace-flags采样标志，01 表示命中采样，00 表示非采样

​
tracestate 头

tracestate: dd=s:1;o:rum
格式：dd=s:[sampling-priority];o:[origin]
字段说明
sampling-priority1 表示 trace 被采样
origin始终为 rum，表示通过 RUM SDK 采集

​
使用场景

​
在 RUM 查看器中查看 Trace

配置完成后，在 RUM 查看器的 View 视图 中可以查看对应的 trace 信息：
  1. 进入 RUM 查看器
  2. 选择包含 API 调用的页面视图
  3. 在视图详情中查看 Trace 信息
  4. 点击 trace 链接可跳转至 trace 系统查看详细的请求链路
RUM 查看器 Trace 信息

在 RUM 查看器中查看 Trace 信息

​
通过 trace_id 查找资源

通过 trace_id 也可以在查看器中进行资源查找：
  1. 在查看器搜索栏中输入 trace_id
  2. 查看对应的资源和视图加载情况
  3. 分析资源加载性能与后端 API 调用的关联关系
通过 trace_id 查找资源

通过 trace_id 查找资源

也可以通过在 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 默认查询的应用和时间范围。

​
端到端问题排查

当用户报告性能问题或者异常时：
1

定位用户会话

在 RUM 查看器中找到问题用户的会话
2

查看 trace 信息

查看问题页面的 trace 信息
3

分析请求链路

跳转到 trace 系统查看完整的请求链路
4

定位问题根因

判断是前端问题、服务问题，还是网络问题

​
最佳实践

​
合理配置采样率

环境建议采样率说明
开发环境100%确保所有请求都被追踪
测试环境50-80%平衡监控覆盖率和性能
生产环境10-20%避免对性能造成影响

​
精确配置追踪 URL

精确匹配 API 端点：
allowedTracingUrls: [
  "https://api.example.com/v1/",
  "https://api.example.com/v2/"
]

​
跨域请求处理

如果您的 HTTP 请求涉及跨域问题，需要确保：
  • 服务器配置了正确的 CORS 头信息
  • 支持预检请求（Preflight Request）
  • 允许 traceparent 和 tracestate 头信息

​
性能监控

  • 定期检查 trace 采样率对应用性能的影响
  • 监控追踪数据的存储和查询性能
  • 根据业务需求调整追踪策略

​
常见问题

可能的原因包括：
  • 请求 URL 不在 allowedTracingUrls 配置范围内
  • 请求被 traceSampleRate 采样率过滤
  • 请求在 SDK 初始化之前发起
  • 跨域请求缺少必要的 CORS 配置
可以通过以下方式验证：
  1. 在浏览器开发者工具中检查网络请求头
  2. 确认请求包含 traceparent 和 tracestate 头信息
  3. 在 RUM 查看器中查看是否有 trace 信息显示

​
注意事项

  • 隐私合规：确保 trace 数据收集符合相关隐私法规要求
  • 性能影响：合理设置采样率，避免对应用性能造成显著影响
  • 数据安全：避免在 trace 数据中包含敏感信息
  • 跨域配置：确保后端服务正确配置 CORS 以支持追踪头信息

​
相关文档

RUM 高级配置

了解 RUM SDK 的完整配置选项

RUM 查看器

掌握 RUM 查看器的使用方法