> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 分布式追踪功能

> 了解如何在 Flashduty RUM 中配置和使用分布式追踪功能，实现前后端请求链路的完整监控

## 概述

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

通过 Trace 追踪，您可以：

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

## 工作原理

Trace 追踪基于 [W3C Trace Context](https://www.w3.org/TR/trace-context/) 标准实现，通过在 HTTP 请求头中注入追踪信息来关联前后端请求：

<Steps>
  <Step title="前端发起请求">
    RUM SDK 自动为配置的 API 请求添加追踪头信息
  </Step>

  <Step title="后端接收处理">
    后端服务接收并处理带有追踪信息的请求
  </Step>

  <Step title="链路关联">
    通过相同的 `trace_id` 将前后端数据关联起来
  </Step>

  <Step title="可视化展示">
    通过 trace 关联根据 `trace_id` 查看完整的请求链路信息
  </Step>
</Steps>

## 配置步骤

### 1. SDK 配置

首先需要在 RUM SDK 中配置分布式追踪功能。在初始化 RUM SDK 时添加以下参数：

```javascript theme={null}
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
});
```

#### 关键配置参数

<ParamField body="allowedTracingUrls" type="array" required>
  指定需要添加追踪信息的 API 端点，支持以下类型：

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

<ParamField body="traceSampleRate" type="number" default="100">
  追踪采样率，控制多少比例的请求会被追踪（范围 0-100）
</ParamField>

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

### 2. 应用管理配置

SDK 配置完成后，可在应用管理页面进行 trace 跳转相关配置：

1. 进入 **应用管理** 页面
2. 选择对应的 RUM 应用
3. 配置 trace 系统的跳转地址（如已集成分布式追踪系统）
4. 在 **高级配置** 中启用 **Trace 追踪** 功能

<Tip>
  在配置的跳转链接中，系统会自动将 `${trace_id}` 替换为实际的 trace\_id。
</Tip>

<Frame caption="Trace 追踪配置界面">
  <img src="https://docs-cdn.flashcat.cloud/imges/png/138f9f58afbdf3a532f4e7d1ed8748ff.png" alt="Trace 追踪配置" />
</Frame>

### 3. 后端服务配置

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

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

## 追踪头信息说明

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

### traceparent 头

```
traceparent: 00-00000000000000008448eb211c80319c-b7ad6b7169203331-01
```

<Info>
  格式：`[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` 表示非采样      |
</Info>

### tracestate 头

```
tracestate: dd=s:1;o:rum
```

<Info>
  格式：`dd=s:[sampling-priority];o:[origin]`

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

## 使用场景

### 在 RUM 查看器中查看 Trace

配置完成后，在 RUM 查看器的 **View 视图** 中可以查看对应的 trace 信息：

1. 进入 **RUM 查看器**
2. 选择包含 API 调用的页面视图
3. 在视图详情中查看 **Trace 信息**
4. 点击 trace 链接可跳转至 trace 系统查看详细的请求链路

<Frame caption="在 RUM 查看器中查看 Trace 信息">
  <img src="https://docs-cdn.flashcat.cloud/imges/png/6a34dfabea8e5ed490bd1ea2024581e6.png" alt="RUM 查看器 Trace 信息" />
</Frame>

### 通过 trace\_id 查找资源

通过 `trace_id` 也可以在查看器中进行资源查找：

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

<Frame caption="通过 trace_id 查找资源">
  <img src="https://docs-cdn.flashcat.cloud/imges/png/0c283dc836389e1a7a94103ed586aaa8.png" alt="通过 trace_id 查找资源" />
</Frame>

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

### 端到端问题排查

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

<Steps>
  <Step title="定位用户会话">
    在 RUM 查看器中找到问题用户的会话
  </Step>

  <Step title="查看 trace 信息">
    查看问题页面的 trace 信息
  </Step>

  <Step title="分析请求链路">
    跳转到 trace 系统查看完整的请求链路
  </Step>

  <Step title="定位问题根因">
    判断是前端问题、服务问题，还是网络问题
  </Step>
</Steps>

## 最佳实践

### 合理配置采样率

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

### 精确配置追踪 URL

<Tabs>
  <Tab title="推荐做法">
    精确匹配 API 端点：

    ```javascript theme={null}
    allowedTracingUrls: [
      "https://api.example.com/v1/",
      "https://api.example.com/v2/"
    ]
    ```
  </Tab>

  <Tab title="避免做法">
    过于宽泛的匹配可能包含不需要追踪的静态资源：

    ```javascript theme={null}
    // 不推荐
    allowedTracingUrls: [
      "https://api.example.com"
    ]
    ```
  </Tab>
</Tabs>

### 跨域请求处理

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

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

### 性能监控

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

## 常见问题

<AccordionGroup>
  <Accordion title="为什么某些请求没有 trace 信息？">
    可能的原因包括：

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

  <Accordion title="如何验证 trace 配置是否正确？">
    可以通过以下方式验证：

    1. 在浏览器开发者工具中检查网络请求头
    2. 确认请求包含 `traceparent` 和 `tracestate` 头信息
    3. 在 RUM 查看器中查看是否有 trace 信息显示
  </Accordion>
</AccordionGroup>

## 注意事项

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