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

# RUM 自定义看板

> 在 Flashduty RUM 中把查看器的聚合分析问题固化成自定义看板：面板类型、面板查询、看板变量、从查看器保存、表格下钻、版本历史与回收站。

## 概述

自定义看板是\*\*分析看板（Insights）\*\*页签栏里的额外页签，与内置的概览、性能、异常、资源页签并列。每个看板由若干面板（图表）组成，而面板的查询就是查看器的聚合分析问题：事件类型 + 统计方式 + 分组字段 + DQL 过滤。于是「错误集中在哪些浏览器」「哪个页面加载最慢」这类一次性分析可以固化成长期可看的看板，不必每次重新拼查询。

## 入口与路由

| 位置 | 地址 | 说明 |
| - | - | - |
| 看板页签 | `/rum/dashboard/custom/:id` | 打开单个看板；看板以页签形式出现在分析看板里 |
| 编辑态 | `/rum/dashboard/custom/:id?edit=1` | 打开即进入编辑，改动先落在浏览器里的草稿 |
| 新建看板 | `/rum/dashboard/custom/new?edit=1` | 由页签栏右侧的 **+** 菜单进入 |
| 看板管理 | `/rum/dashboard/manage` | 看板列表：搜索、删除、回收站 |

页签栏右侧的 **+** 菜单有两项：

* **新建看板**：打开一个空白看板的编辑态。需要**看板管理**权限，没有权限时该项不显示。
* **管理看板**：进入看板管理页；只是查看，不需要编辑权限。

页签栏按标题顺序列出全部看板，最多 100 个；超过 100 个的看板从看板管理页进入。

## 应用与时间范围

* 看板跟随页面右上角的**应用**与**时间范围**。打开看板时如果链接里没有时间范围，使用看板自己的默认时间范围；在看板里调整时间范围会同步改变页面的时间选择器。
* 切换页签时页面的应用与时间范围一并带过去。看板的 `env`、`service`、`version` 三个变量与内置页签的对应筛选条件互相转换，其他变量不跨页签保留。

## 面板类型

面板编辑器的**图表类型**提供四种：

| 类型 | 说明 |
| - | - |
| **时序** | 统计值随时间的走势，可选折线或柱状画法 |
| **表格** | 按分组的明细，一行一个分组，可点击下钻（见[表格下钻](#表格下钻)） |
| **单值** | 一个关键数字，可设置阈值着色；单值面板不使用分组 |
| **文本** | Markdown 说明文字，不绑定查询 |

## 添加面板

<Steps>
  <Step title="进入编辑态">
    打开看板后点击右上角的 **编辑**，或用带 `?edit=1` 的链接进入。编辑态是浏览器里的一份草稿，整盘一次提交；刷新页面草稿即丢失，离开前会提示未保存。
  </Step>

  <Step title="添加图表">
    点击 **添加图表** 打开面板编辑弹窗。看板按页签与分组组织面板，一个新看板自带一个页签。
  </Step>

  <Step title="配置查询">
    选择应用（或**跟随页面应用**）、事件类型、统计方式与统计字段、分组字段与**取前**组数，再按需写 DQL 过滤条件。查询就绪后预览自动运行：选择类控件改动后延迟重跑，DQL 输入框按回车或失焦时运行。保存不要求预览成功。
  </Step>

  <Step title="选择图表类型并命好名字">
    标题留空时按查询自动生成，例如「P75 首字节时间 · 按浏览器名称」；描述留空时以应用名作面板副标题，用来区分查询不同应用的面板。
  </Step>

  <Step title="应用并保存看板">
    在弹窗里点 **应用** 把面板放回画布，再点 **保存** 提交。保存时可以写**版本说明**（选填），一次保存产生一个新版本。
  </Step>
</Steps>

## 面板查询

一条面板查询由以下部分组成，与查看器的聚合分析一致：

| 组成 | 说明 |
| - | - |
| **应用** | 具体某个应用，或**跟随页面应用**（`$app`，看板跟着页面的应用切换） |
| **事件类型** | `Sessions`、`Views`、`Resources`、`Actions`、`Errors`、`Long Tasks`、`Vitals` |
| **统计方式 / 统计字段** | 计数、去重计数、平均值、求和、最小值、最大值、P50 / P75 / P90 / P95 / P99；除计数外需要选统计字段 |
| **分组字段 / 取前** | 按某个字段拆开，保留前 `5`、`10`、`20` 或 `50` 组 |
| **DQL 过滤** | 与查看器的搜索语法一致，见[数据查询语法](../explorer/data-query) |

分组字段受字段基数限制，规则与查看器相同，见[聚合分析 · 分组字段](../explorer/analytics#分组字段)：事件的 ID 字段不能用于分组，其他高基数字段只能配计数或求和且时间范围最长 7 天。

结果按抽样估算时，面板会显示**采样估算**标记与说明。

## 看板变量

看板顶部是变量栏。新看板默认带 `env`、`service`、`version` 三个字段变量，默认值都是**全部**（全部表示不加该条件）。

| 变量类型 | 说明 |
| - | - |
| 内置 `$app` | 页面的当前应用。面板查询里选**跟随页面应用**就等于用 `$app`；只有应用的 `application_id` 能引用它 |
| 字段变量 | 候选值取自某个 RUM 字段的取值，多选，「全部」可用 |
| 自定义变量 | 手动填写候选值（每行一个，`显示名=值` 或纯值），单选或多选 |

* 在面板的 DQL 里用 `${name}` 或 `$name` 引用变量，例如 `env:${env}`。一个变量选了多个值时展开为 `(a OR b)`；选中**全部**或没有取值时，包含该引用的整条条件（`env:${env}`、`-env:${env}`、`NOT env:${env}`，以及含有它的值列表）会被整条去掉，而不是当成空值查询。
* 引用在浏览器里替换后才查询，因此面板的 DQL 必须能替换成完整语句才有结果。
* 新建面板时，过滤条件会自动带上看板的字段变量（该事件类型有这些字段时）。
* 变量改名会同步改写引用它的查询；仍被引用的变量不能删除，需要先清理引用。
* 变量的选择保存在链接里（形如 `var-env=...` 的参数），复制链接即可分享同一组筛选。

<Note>
  RUM 看板只有两种自定义变量：取某个 RUM 字段的取值的字段变量，与手填候选的自定义变量。数据源变量与 Prometheus / SQL / 日志类变量查询不适用，看板里不会出现。
</Note>

## 从查看器保存到看板

在查看器的聚合分析图表工具栏里点 **保存到看板**，可以把当前这个分析问题直接固化成一个看板面板：

* 图表类型可选**时序 / 表格 / 单值**；饼图与分布图暂不支持，按钮会提示「饼图和分布图还不能保存到看板」。
* 可以**追加到现有看板**（打开该看板的编辑态并追加这个面板，保存前不写入任何数据），也可以**新建看板**（先创建只含这个面板的看板，再打开它的编辑态）。
* 面板沿用当前的时间范围与过滤条件，并自动带上看板的 `env` / `service` / `version` 变量，标题按查询自动生成。

具体操作与限制见[聚合分析 · 保存到看板](../explorer/analytics#保存到看板)。

## 表格下钻

**表格**面板的每一行都带一个「在查看器中打开 `字段 = 值`」的链接，点击后跳到查看器的聚合分析：沿用该面板的查询与统计方式，把过滤条件缩到这一行的分组值，时间范围用看板当前的。

* 没有分组的表格没有下钻链接。
* 分组值里有引号、括号等无法精确表达为 DQL 条件的字符时，链接改用通配匹配（近似匹配），标题后面会标出「（通配符近似匹配）」。

## 版本历史与恢复

看板右上角 **⋯** 菜单里的 **版本历史** 打开版本列表：

* 每次保存（含删除、恢复）产生一个新版本，最多保留最近 **20** 个版本，更早的版本自动清理。
* 表格列出**版本**、**时间**、**操作人**与**说明**，当前版本标为**当前**。同一次打开时勾选两个版本可以**对比**两版保存内容的差异。
* 选择早期版本可以**恢复**：恢复是用该版本的内容做一次新的保存，因此会产生一个新版本，恢复前的版本仍留在历史里，可以再恢复回来。

## 删除与回收站

* 看板右上角 **⋯** 菜单里的 **删除** 把看板移入回收站，确认提示为「『看板标题』将进入回收站，30 天后自动清除。」
* 看板管理页的 **回收站** 列出已删除的看板，提示「删除的看板保留 30 天，可在这里恢复。」，点行尾的**恢复**按钮（图标）把看板放回列表，并重新出现在页签栏里。
* 回收站里的看板超过 30 天后被彻底清除，无法恢复。

<Note>
  RUM 看板没有目录（文件夹）：看板不做分组，管理页也没有目录树与跨目录移动。看板列表支持按标题关键词搜索。
</Note>

## 权限

新建、编辑、删除与恢复看板需要**看板管理**权限。没有该权限时：

* 页签栏 **+** 菜单里没有**新建看板**，看板的管理页没有**新建看板**按钮与删除、恢复入口；
* 看板右上角没有**编辑**，**⋯** 菜单里没有**克隆**与**删除**；
* 仍然可以查看全部看板、切换变量与时间范围，也可以用**导出 JSON** 与**版本历史**查看内容。

## 数值限制

| 项 | 上限 |
| - | - |
| 看板内的页签数 | 10 |
| 每个页签的分组数 | 10 |
| 每个页签的面板数 | 30 |
| 整个看板的面板数 | 100 |
| 每个页签的查询数 | 100 |
| 整个看板的查询数 | 300 |
| 变量数 | 20 |
| 每个变量的候选值 | 1000 |
| 单个面板的数据链接 | 5 |
| 时序面板的查询数 | 1–26 |
| 表格 / 单值面板的查询数 | 恰好 1 |
| 文本面板的 Markdown 大小 | 64 KB |
| 标题长度 | 189 字符 |
| 描述长度 | 1024 字符 |
| 看板定义大小 | 1 MB |
| 默认时间范围可选值 | `now-15m`、`now-30m`、`now-1h`、`now-3h`、`now-6h`、`now-12h`、`now-24h`、`now-7d` |
| 自动刷新可选值 | 不刷新、`30s`、`1m`、`5m` |

## 下一步

<CardGroup cols={2}>
  <Card title="Web RUM 分析" icon="chart-line" href="./web">
    内置分析看板的四个分析维度
  </Card>

  <Card title="聚合分析" icon="chart-column" href="../explorer/analytics">
    统计方式、分组、图表类型与下钻
  </Card>

  <Card title="数据查询语法" icon="magnifying-glass" href="../explorer/data-query">
    面板过滤条件用的搜索语法
  </Card>

  <Card title="查看器概览" icon="compass" href="../explorer/overview">
    列表与分析两种查看方式
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.