分布式追踪功能

概述

Flashduty RUM 的 Trace 追踪功能将前端用户监控与分布式追踪系统深度集成，让您能够将 Web 应用程序的请求与其对应的后端跟踪关联起来。这种组合使您能够一目了然地查看完整的前端和后端数据，实现端到端的性能监控和问题排查。通过 Trace 追踪，您可以：

关联前后端请求：将前端用户操作与后端 API 调用关联
端到端问题排查：快速定位从前端到后端的完整请求链路问题
性能瓶颈分析：识别整个请求链路中的性能瓶颈点
用户体验优化：基于完整的请求链路数据优化用户体验

工作原理

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

前端发起请求

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

后端接收处理

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

链路关联

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

可视化展示

通过 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
});

关键配置参数

array

必填

指定需要添加追踪信息的 API 端点，支持以下类型：

类型	说明	示例
字符串	匹配以该值开头的 URL	`"https://api.example.com"`
正则表达式	使用正则表达式匹配 URL	`/https:\/\/.*\.my-api-domain\.com/`
函数	自定义匹配逻辑，返回 `true` 表示匹配	`(url) => url.startsWith("https://api")`

number

默认值:"100"

追踪采样率，控制多少比例的请求会被追踪（范围 0-100）

生产环境建议将 traceSampleRate 设置为 10-20，以平衡监控覆盖率和性能影响。

2. 应用管理配置

SDK 配置完成后，可在应用详情的 Link 集成 页签中配置 trace 跳转：

进入 应用管理 页面
选择对应的 RUM 应用并打开 Link 集成 页签
在 Tracing 卡片中填写链路追踪系统的跳转链接
保存链接后开启 Tracing 开关

在配置的跳转链接中，系统会自动将 ${trace_id} 替换为资源事件中的实际 trace_id。内置 Tracing 仅在资源事件包含 trace_id 时展示。

3. 后端服务配置

为了完整支持分布式追踪，后端服务需要：

接收追踪头信息：处理 traceparent 和 tracestate 请求头
传递追踪信息：在调用其他服务时继续传递追踪头信息
生成追踪数据：将请求处理过程记录到追踪系统中

追踪头信息说明

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

格式：dd=s:[sampling-priority];o:[origin]

字段	说明
`sampling-priority`	`1` 表示 trace 被采样
`origin`	始终为 `rum`，表示通过 RUM SDK 采集

使用场景

在 RUM 查看器中查看 Trace

配置完成后，包含 trace_id 的资源事件会显示 Tracing 跳转入口：

进入 RUM 查看器
筛选或打开包含 API 调用的资源事件
在资源列表的 trace_id 列点击 trace 链接，或在事件详情右上角打开 关联 Link
跳转至您的 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 默认查询的应用和时间范围。

端到端问题排查

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

定位用户会话

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

查看 trace 信息

查看问题页面的 trace 信息

分析请求链路

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

定位问题根因

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

最佳实践

合理配置采样率

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

精确配置追踪 URL

推荐做法
避免做法

精确匹配 API 端点：

allowedTracingUrls: [
  "https://api.example.com/v1/",
  "https://api.example.com/v2/"
]

过于宽泛的匹配可能包含不需要追踪的静态资源：

// 不推荐
allowedTracingUrls: [
  "https://api.example.com"
]

跨域请求处理

如果您的 HTTP 请求涉及跨域问题，需要确保：

服务器配置了正确的 CORS 头信息
支持预检请求（Preflight Request）
允许 traceparent 和 tracestate 头信息

性能监控

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

常见问题

为什么某些请求没有 trace 信息？

可能的原因包括：

请求 URL 不在 allowedTracingUrls 配置范围内
请求被 traceSampleRate 采样率过滤
请求在 SDK 初始化之前发起
跨域请求缺少必要的 CORS 配置

如何验证 trace 配置是否正确？

可以通过以下方式验证：

在浏览器开发者工具中检查网络请求头
确认请求包含 traceparent 和 tracestate 头信息
在 RUM 查看器中查看是否有 trace 信息显示

注意事项

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

快速开始

分析看板

SDK 接入

性能监控

异常追踪

查看器

会话重放

最佳实践

其他

概述

工作原理

配置步骤

1. SDK 配置

关键配置参数

2. 应用管理配置

3. 后端服务配置

追踪头信息说明

traceparent 头

tracestate 头

使用场景

在 RUM 查看器中查看 Trace

通过 trace_id 查找资源

端到端问题排查

最佳实践

合理配置采样率

精确配置追踪 URL

跨域请求处理

性能监控

常见问题

注意事项

​概述

​工作原理

​配置步骤

​1. SDK 配置

​关键配置参数

​2. 应用管理配置

​3. 后端服务配置

​追踪头信息说明

​traceparent 头

​tracestate 头

​使用场景

​在 RUM 查看器中查看 Trace

​通过 trace_id 查找资源

​端到端问题排查

​最佳实践

​合理配置采样率

​精确配置追踪 URL

​跨域请求处理

​性能监控

​常见问题

​注意事项

概述

工作原理

配置步骤

1. SDK 配置

关键配置参数

2. 应用管理配置

3. 后端服务配置

追踪头信息说明

traceparent 头

tracestate 头

使用场景

在 RUM 查看器中查看 Trace

通过 trace_id 查找资源

端到端问题排查

最佳实践

合理配置采样率

精确配置追踪 URL

跨域请求处理

性能监控

常见问题

注意事项