> ## 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 支持收集和上报 Web Vitals 相关的性能指标，帮助您全面监控和优化网站性能。通过这些指标，您可以了解用户在访问网站时的实际体验，并针对性地进行优化。

## Web Vitals 指标概览

Flashduty RUM 支持以下 [核心 Web Vitals 指标](https://web.dev/articles/vitals?hl=zh-cn)：

| 指标       | 全称       | 说明              |
| -------- | -------- | --------------- |
| **LCP**  | 最大内容绘制   | 衡量页面主要内容的加载性能   |
| **INP**  | 交互到下一帧延迟 | 衡量整体交互响应性能      |
| **CLS**  | 累计布局偏移   | 衡量视觉稳定性         |
| **FCP**  | 首次内容绘制   | 衡量首次内容渲染时间      |
| **FID**  | 首次输入延迟   | 衡量页面交互性能（辅助指标）  |
| **TTFB** | 首次字节时间   | 衡量服务器响应速度（辅助指标） |

这些指标会在用户访问页面时自动收集，并通过 SDK 上报到 Flashduty 平台，您可以在分析看板中查看详细的性能数据。

<Warning>
  对于在后台打开的页面（例如，在新标签页或无焦点的窗口中），不会收集到 INP 和 LCP 的数据。
</Warning>

## 指标计算方法

<AccordionGroup>
  <Accordion title="LCP - 最大内容绘制">
    **计算方法：** 从页面开始加载（`navigationStart`）到最大可见内容元素（如图片、文本块）渲染完成的时间。

    **用例：** 监控主页或关键页面内容加载速度，识别资源加载瓶颈。
  </Accordion>

  <Accordion title="FCP - 首次内容绘制">
    **计算方法：** 测量从用户第一次导航到页面到页面内容的任何部分在屏幕上呈现的时间。

    **用例：** 用于测量感知加载速度，有助于向用户保证某些事情正在发生。
  </Accordion>

  <Accordion title="INP - 交互到下一帧延迟">
    **计算方法：** 测量所有用户交互（点击、轻触、键盘输入）到下一帧渲染的延迟时间。

    **用例：** 评估页面整体交互响应性能，优化高延迟交互场景。
  </Accordion>

  <Accordion title="CLS - 累计布局偏移">
    **计算方法：** 统计所有意外布局偏移的分数（偏移距离 × 影响区域）。

    **用例：** 识别动态内容或广告导致的页面跳动问题。
  </Accordion>

  <Accordion title="FID - 首次输入延迟">
    **计算方法：** 从用户第一次交互开始到浏览器处理事件的时间差。

    **用例：** 优化交互密集型页面（如表单、导航菜单）的响应速度。
  </Accordion>
</AccordionGroup>

## 监控单页应用 (SPA)

对于单页应用程序，RUM 浏览器 SDK 通过 `loading_type` 属性区分 `initial_load` 和 `route_change` 两种导航类型。

<Tabs>
  <Tab title="History SPA">
    如果网页上的某个交互操作导致 URL 发生变化，但页面并未完全刷新，RUM SDK 会使用 `loading_type:route_change` 启动一个新的 `view`。

    RUM 使用 [History API](https://developer.mozilla.org/zh-CN/docs/Web/API/History) 来跟踪 URL 的变化。
  </Tab>

  <Tab title="Hash SPA">
    RUM SDK 会自动监控依赖哈希（`#`）导航的框架。SDK 会监听 `HashChangeEvent` 并发出一个新的 `view`。

    来自 HTML 锚点且不影响当前视图上下文的事件将被忽略。
  </Tab>
</Tabs>

<Tip>
  对于 SPA 应用，如需监控路由切换后的性能，建议使用自定义性能监控功能来测量特定组件或交互的性能指标。
</Tip>

## 自定义性能监控

### 组件级性能测量

使用 `customVital` API 监控特定组件或交互的性能，适用于：

* 关键组件渲染时间
* 用户交互响应时间
* 业务流程耗时

<CodeGroup>
  ```javascript 测量组件渲染 theme={null}
  // 开始计时
  const ref = window.FC_RUM.startDurationVital("componentRendering", {
    description: "login-form",
    context: { clientId: "xxx", componentVersion: "1.0.0" },
  });

  // 结束计时
  window.FC_RUM.stopDurationVital(ref);
  ```

  ```javascript 直接报告耗时 theme={null}
  window.FC_RUM.addDurationVital("dropdownRendering", {
    startTime: 1707755888000, // UNIX 时间戳（毫秒）
    duration: 10000, // 耗时（毫秒）
  });
  ```
</CodeGroup>

### 性能时间点记录

使用 `addTiming` API 记录关键时间点，适用于：

* 关键元素加载（如首屏图片）
* 用户首次交互（如首次滚动）
* 业务节点时间戳

<CodeGroup>
  ```javascript 记录首次滚动 theme={null}
  document.addEventListener("scroll", function handler() {
    document.removeEventListener("scroll", handler);
    window.FC_RUM.addTiming("first_scroll");
  });
  ```

  ```javascript 异步场景 theme={null}
  document.addEventListener("scroll", function handler() {
    document.removeEventListener("scroll", handler);
    const timing = Date.now();
    window.FC_RUM.onReady(() => {
      window.FC_RUM.addTiming("first_scroll", timing);
    });
  });
  ```
</CodeGroup>

## 注意事项

<CardGroup cols={2}>
  <Card title="命名规范" icon="tag">
    * 指标名称避免空格、特殊字符
    * 使用描述性命名（如 `login_form_render`）
    * 保持命名一致性
  </Card>

  <Card title="性能影响控制" icon="gauge">
    * 控制自定义指标数量
    * 避免频繁计时
    * 合理设置采样率
  </Card>
</CardGroup>

## 常见问题

<AccordionGroup>
  <Accordion title="页面加载时间异常">
    * 检查慢加载资源（图片、脚本）
    * 排查第三方脚本阻塞
    * 分析长时间运行的 JavaScript
  </Accordion>

  <Accordion title="活动状态判定不准确">
    * 确认是否存在频繁的后台请求
    * 检查长连接或流式请求的处理
    * 使用 `excludedActivityUrls` 排除干扰
  </Accordion>

  <Accordion title="自定义指标问题">
    * 验证指标名称是否符合规范
    * 确保计时器正确启停
    * 检查异步场景的时间戳准确性
  </Accordion>

  <Accordion title="Web Vitals 指标为空">
    | 原因       | 说明                                                     |
    | -------- | ------------------------------------------------------ |
    | 后台页面     | 页面在新标签页或无焦点窗口中打开，导致 INP 和 LCP 无法收集                     |
    | SPA 路由切换 | 在 `loading_type:route_change` 时，核心 Web Vitals 指标不会重新收集 |
    | 引入方式     | 页面在 SDK 完全初始化前就已加载完成                                   |
    | 页面生命周期   | 页面在指标收集完成前就被关闭或导航离开                                    |
    | 浏览器兼容性   | 旧版本浏览器不支持某些 Web Vitals API                             |
    | 页面无内容    | 页面没有可测量的内容元素（如空白页面）                                    |
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="性能分析" icon="chart-line" href="./performance-analysis">
    深入分析性能数据
  </Card>

  <Card title="诊断优化" icon="wrench" href="./diagnosis-optimization">
    学习问题诊断与优化方法
  </Card>
</CardGroup>