> ## 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.

# 实体树

> 从 Prometheus 指标标签持续发现实体，使用动态分组和可继承规则统一管理实体告警。

当主机、容器、实例或业务模块持续扩缩容时，逐个维护监控对象和告警规则很容易失效。实体树从 Prometheus 查询结果中自动发现这些动态资源，将它们整理为稳定的实体，并根据标签自动归入不同分组。

您可以在上层分组配置通用告警规则，让规则自动作用于匹配的后代实体；当某个环境或业务需要不同阈值时，只需在对应分组覆盖参数。这样既能减少重复规则，也能让告警策略跟随实体变化。

当前版本以实体告警为主要使用场景。实体树先建立统一、稳定的实体视图，也为后续围绕实体查看指标和分析上下文提供一致入口。

<Frame caption="实体树从数据源发现实体，并按动态分组继承告警策略">
  <img src="https://static.flashcat.cloud/images/flashmonit/entity-alert-architecture-light-v1.png" alt="多个 Prometheus 数据源发现实体，实体进入动态分组并继承告警策略" />
</Frame>

## 适用场景

实体树适合以下场景：

* Kubernetes Pod、云主机、数据库实例等对象频繁创建、销毁或变化
* 多个环境或业务使用相同指标，但告警阈值不同
* 您希望按区域、环境、集群、团队或服务等标签自动管理告警范围
* 多个 Prometheus 数据源需要复用同一套实体定义和告警策略

如果监控对象固定、每条规则只对应一个明确查询，继续使用普通告警规则通常更直接。

## 实体树如何组织监控

| 概念 | 作用 | 示例 |
| - | - | - |
| **实体类别** | 定义从哪些数据源、通过什么查询发现一类实体，以及哪些标签可以稳定标识实体 | 节点、Pod、数据库实例 |
| **实体** | 一条持续被发现的具体资源。同一数据源内，身份标签值相同的查询结果会归并到同一个实体 | instance=10.0.0.8:9100 |
| **动态分组** | 使用实体标签自动划分范围。实体属性变化后，所属分组会随之更新 | 生产环境、支付服务、华东区域 |
| **实体告警规则** | 在某个分组创建并自动作用于匹配的后代实体 | 节点 CPU 使用率过高 |
| **规则覆盖** | 在子分组调整继承规则的告警级别、参数或连续命中次数 | 生产环境阈值 90%，测试环境阈值 95% |

<Note>
  同一组身份标签值在不同数据源中会形成不同实体。您可以在工作区切换数据源，分别查看实体、规则执行结果和活跃告警。
</Note>

## 使用前准备

开始前，请确认：

* 当前租户已启用 Monitors，并已部署告警引擎
* 已创建至少一个 Prometheus 数据源
* 您的账号拥有实体树查看权限；创建或修改配置还需要实体树管理权限、相应实体类别或分组的管理权限，以及对所选用数据源的查询权限
* 告警引擎版本满足实体树页面提示的要求

<Warning>
  如果告警引擎版本不兼容，页面会提示升级，实体和实体告警状态可能暂时不可用。普通告警规则不受影响。
</Warning>

## 配置实体树

### 1. 申请开通

进入 **Monitors → 实体树**。如果当前租户尚未开通，点击 **申请开通**。申请提交后，页面会显示申请时间；审核通过后即可开始配置。

### 2. 创建实体类别

实体类别决定系统如何发现并识别一类资源。点击 **创建实体类别**，完成以下配置：

| 配置项 | 说明 |
| - | - |
| **名称** | 使用用户容易理解的资源类别名称，例如“节点”或“数据库实例” |
| **管理团队** | 选择后，该团队成员可以管理该实体类别及其全部分组；不选择时，仅创建者和租户管理员可以管理 |
| **数据源（精确匹配）** | 按数据源 ID 选择，不受数据源改名影响 |
| **数据源（名称通配）** | 使用名称模式自动匹配数据源，支持 \*、? 和字符范围。适合自动纳入命名规范一致的新数据源 |
| **发现 PromQL** | 返回待发现实体的即时向量。查询结果中的标签会成为实体的候选属性 |
| **身份标签** | 一个或多个稳定标签，共同唯一标识实体 |
| **多值标签** | 可选。同一实体对应多条结果时，将指定标签的非空值合并为集合 |
| **同步周期** | 重新发现实体的间隔，默认 15 秒 |
| **失联保留时间** | 实体暂时从一次成功的发现结果中消失后，继续保留状态的时间，最少 3600 秒 |

精确匹配和名称通配可以同时使用，系统会使用两者匹配到的全部数据源。至少配置一种匹配方式。

<Note>
  保存实体类别时还会校验数据源权限：主体账号和租户管理员不受此限制，其他成员必须对本次选中的每个 Prometheus 数据源都拥有查询（只读）权限；名称通配按保存当下匹配到的数据源逐个校验，匹配到任一您无权查询的数据源即拒绝保存，并返回无权限引用该数据源的错误。缩小或移除数据源选择不受此限制——失去某个数据源的权限后，仍然可以把该数据源从实体类别中去掉。实体类别的数据源列表同样按查看者权限过滤，您无权查询的数据源不会出现在它的数据源配置和已解析数据源列表中。
</Note>

配置时有以下约束：名称通配不支持 `{}` 花括号语法；名称最多 128 个字符，发现 PromQL 最多 1024 个字符；编辑已有实体类别时，不能在同一次保存中同时修改身份标签和多值标签，需要分两次完成。

发现 PromQL 输入框的右上角提供 **AI 帮我写** 入口（鼠标悬停或光标聚焦到输入框时渐显），可以让 AI 查询助手生成或改写发现查询；助手在实体树中只回填查询语句，不会切换数据源。详见 [AI 查询助手](/zh/monitors/quickstart/quickstart#ai-查询助手)。

例如，以下查询可以发现带有 instance 标签的节点：

```promql theme={null}
up{job="node"}
```

填写查询后，点击 **预览**，再从查询结果中选择身份标签。预览会帮助您检查：

* 每条结果是否都包含身份标签
* 同一身份是否出现普通单值标签冲突
* 多条结果会如何按身份合并

<Tip>
  选择长期稳定、能唯一定位资源的标签作为身份标签，例如 instance、pod\_uid 或数据库实例 ID。不要使用会频繁变化的状态、版本或发布批次标签，否则同一资源可能被识别为新实体。
</Tip>

如果一个实体天然对应多个属性值，例如同一节点属于多个业务组，可以将相应标签配置为多值标签。多值标签不能同时作为身份标签。

### 3. 创建动态分组

创建实体类别后，页面左侧会显示实体类别和分组树。左侧面板顶部的搜索框可以按名称搜索实体类别和分组，匹配的节点会高亮并自动展开。在目标节点的操作菜单中选择 **创建子分组**，并使用标签条件定义实体范围。创建或编辑分组时，抽屉中还提供可选的 **管理团队** 配置：当前分组的团队权限会向子分组继承，同时保留实体类别和上级分组已有权限。

| 操作符 | 含义 |
| - | - |
| = | 标签值相等；值留空时匹配标签缺失或没有值 |
| != | 标签值不等；值留空时匹配至少有一个值 |
| =\~ | 标签值匹配正则表达式 |
| !\~ | 标签值不匹配正则表达式 |

匹配条件的标签名必须符合 `^[A-Za-z_][A-Za-z0-9_]*$` 格式，且 `__name__` 为系统保留字段，不能使用。

选择实体类别和数据源后，标签名和匹配值输入框会针对当前实体类别、数据源和分组范围内的实体快照自动补全候选项，每个候选项会标注命中它的实体数量。使用 `=~` 或 `!~` 时，匹配值输入框进入正则候选模式，选中候选项会自动转义为正则字面量；候选项较多时页面会提示继续输入以缩小范围。部分实体缺失所选标签或值为空时，值候选顶部会出现 **为空（缺失或没有值）** 选项。当前 Edge 版本不支持运行时查询时，正则候选不可用，但仍可手动输入正则表达式并保存。

同一分组中的多个条件必须全部满足。子分组还会继承全部上级分组的条件。

例如，您可以先创建 env = prod 的“生产环境”分组，再在其下创建 service = payment 的“支付服务”分组。第二个分组最终只包含同时满足两个条件的实体。

<Note>
  实体可以同时命中多个同级分组。请让同级分组表达清晰、互不冲突的管理维度，并在配置不同规则覆盖时检查最终告警范围。
</Note>

### 4. 创建实体告警规则

选择要承载规则的分组，打开 **规则** 标签页，然后点击 **创建规则**。

| 配置项 | 说明 |
| - | - |
| **规则名称** | 告警名称，支持使用页面提供的模板变量 |
| **PromQL** | 用于判断告警条件的查询。可使用参数占位符，让不同告警级别或分组复用同一查询 |
| **告警级别** | 可分别启用 Critical、Warning 和 Info，并配置参数与连续命中次数 |
| **恢复方式** | 选择“条件不再命中”，或使用独立恢复 PromQL |
| **连续恢复次数** | 连续满足恢复条件多少次后恢复告警 |
| **高级配置** | 配置执行周期、时区、执行延迟和重复通知。执行周期支持 `@every` 固定间隔（如 `@every 60s`）或六字段 Cron（秒 分 时 日 月 周，如 `0 */5 * * * *`）；使用 Cron 必须选择有效 IANA 时区（默认 `Asia/Shanghai`），Cron 中不能内嵌时区，`@every` 周期无需填写时区。新建规则默认每 60 秒执行一次，每 3600 秒重复通知一次、最多重复 3 次 |
| **标签与注解** | 为告警补充路由标签和说明；规则名称与注解支持模板变量 |

规则创建在当前分组，并自动作用于当前分组和所有匹配的后代实体。规则列表会分别展示 **本组规则** 和 **继承规则**，帮助您判断规则来自哪个层级。

告警条件 PromQL 输入框的右上角同样提供 **AI 帮我写** 入口，可以让 AI 查询助手生成或改写语句；实体树中助手只回填查询语句，不会切换数据源。详见 [AI 查询助手](/zh/monitors/quickstart/quickstart#ai-查询助手)。

<Tip>
  在 PromQL 中定义一个可复用的 threshold 参数，然后为 Critical、Warning 和 Info 填写不同的参数值。这样只需维护一条查询，就能表达多个告警级别。
</Tip>

<Note>
  规则标签与注解的名称必须匹配 `^[A-Za-z_][A-Za-z0-9_]*$`，且不能使用系统保留名称 `check` 或以 `__entity_alert_`、`__flashduty_` 开头的名称；与实体身份标签同名的标签或注解会被拒绝，因为身份标签不能被规则标签或注解覆盖。
</Note>

#### 查询预览

条件 PromQL 和恢复 PromQL 输入框旁的 **查询预览** 按钮可以打开预览对话框（需要当前实体类别绑定至少一个 Prometheus 数据源）。对话框先替换参数与标签变量，再把**最终执行的 PromQL** 发送到所选数据源，执行即时查询：

* 条件查询会为每个启用的告警级别生成一个变体，可以在对话框中选择 **告警级别**，用该级别填写的参数值替换 `${参数名}` 占位符
* 恢复查询会读取当前规则的活跃告警，可以从 **预览告警** 中选择一条，用该告警的实体标签和告警维度替换 `${labels.<名称>}` 占位符；规则尚未保存或当前没有活跃告警时，只能退回使用实体标签，告警维度需等规则保存并产生告警后才能解析
* 打开对话框后会自动执行一次查询，切换数据源或级别后也会重新执行，还可以点击 **重新查询** 手动重跑

查询成功后展示以下诊断信息：

| 诊断项 | 说明 |
| - | - |
| 查询耗时 | 本次查询的耗时，单位毫秒 |
| 返回记录 | 查询返回的记录数 |
| 有效实体 | 结果中包含完整身份标签的不同实体数；告警查询在实体快照可用时还会统计落在当前分组范围内的实体 |
| 告警 / 发现诊断 | 告警查询统计告警实例数，并提示缺失身份、重复告警；发现查询提示缺失身份、单值冲突实体，以及多条记录按身份合并的情况 |

尚未选择身份标签时，对话框只展示返回记录，并提示选择身份标签后才能计算有效实体和诊断。查询没有返回记录不代表规则配置无效，可以换个时间再试。

条件 PromQL 使用 `${参数名}` 占位符复用查询。完整输入参数名并离开编辑器后，页面会为每个告警级别自动创建对应参数项。预览替换失败时会给出具体错误：**参数占位符缺少结束符**（占位符未闭合）、`参数占位符“{{name}}”没有可用值`（未填写参数值）、`参数“{{name}}”未在 PromQL 中引用`（填写了参数但查询中没有使用）。

恢复 PromQL 同样支持 `${参数名}`（例如 `${threshold}`）；此外还可以引用实体单值标签和当前告警的标量维度，写法为 `${labels.instance}`、`${labels.path}`、`${labels.busigroup}`，且只能写在 PromQL 双引号字符串内。离开编辑器后会自动创建普通参数项，实体标签不会创建参数项。

### 5. 导入告警规则

除了逐条创建，您还可以在分组的 **规则** 标签页点击 **导入规则**，上传 YAML 文件批量导入到当前分组。系统会自动识别三种来源格式：

| 来源格式 | 说明 |
| - | - |
| **Entity Alert 规则包** | 从其他分组或租户导出的规则包，保留完整规则配置。规则包记录的身份标签必须与目标实体类别一致，否则无法导入 |
| **Prometheus Rules** | 标准 Prometheus 告警规则文件（`groups` 列表、`rules` 列表或单条规则），导入时按下文的转换规则处理 |
| **Prometheus Operator** | PrometheusRule CRD（`spec.groups`），转换方式与 Prometheus Rules 相同 |

限制与要求：

* 一次只能上传一个不超过 1 MB 的 `.yaml` 或 `.yml` 文件，单次最多导入 100 条规则
* 不支持 recording rule（只定义 `record` 的规则会被忽略）；同一条规则不能同时配置 `alert` 和 `record`
* 规则标签的值不能包含 `{{ }}` 动态模板；PromQL 必须返回瞬时向量，比较表达式不能使用 `bool` 修饰符
* 从 Prometheus 格式导入时，PromQL 的每条结果都必须包含目标实体的身份标签，否则告警无法关联到实体

上传后系统会先执行 **预检**，逐条展示转换结果和名称冲突，不会立即写入。每条规则会被标记为以下状态之一：

| 预检状态 | 含义 |
| - | - |
| **可导入** | 校验通过，可以写入 |
| **创建副本** | 与当前分组已有规则同名，将使用带序号的新名称创建 |
| **跳过** | 与当前分组已有规则同名，按所选策略保留现有规则 |
| **已忽略** | recording rule 等不支持的规则，不会导入 |
| **校验失败** | 缺少 `alert` 或 `expr`、PromQL 不合法等问题，无法导入 |

上传文件后可以选择 **同名规则处理方式**：**跳过同名规则**（默认，保留目标分组中的现有规则）或 **创建副本**（自动使用带序号的新名称），切换后预检会自动重新执行。Entity Alert 规则包采用严格校验，只要存在校验失败的规则就无法提交导入；Prometheus 格式允许略过失败条目，仅导入可导入的规则。

从 Prometheus 格式导入时，系统按以下规则转换，并在预检结果中标注降级项：

* `labels.severity` 映射告警级别：`page`、`p1`、`error`、`critical` 转为 Critical，`info` 转为 Info，其余取值转为 Warning；使用 `{{ }}` 动态取值的 severity 统一按 Warning 转换
* 未提供 `interval` 时执行周期默认 1 分钟；`for` 折算为连续命中次数，`keep_firing_for` 折算为连续恢复次数
* 与实体身份标签同名的规则标签会被忽略，避免干扰实体识别
* 无法识别或不支持的分组字段与规则字段会在导入时忽略，并在预检结果中标注（例如 `分组字段 {{field}} 暂不支持`、`无法识别分组字段 {{field}}`、`无法识别规则字段 {{field}}`），不会阻断其余规则的导入

<Warning>
  为避免导入后立即产生告警，所有导入规则都会保持 **停用**，并自动在规则列表中选中。请检查转换结果后，再通过批量启用让规则生效。
</Warning>

### 6. 覆盖继承规则

如果子分组需要不同阈值，在子分组的 **继承规则** 列表中选择 **覆盖继承规则**。您可以调整：

* 告警级别是否继承、启用或停用
* 各告警级别的参数和连续命中次数
* 恢复查询参数和连续恢复次数

查询文本、执行周期、恢复方式和重复通知继续继承上级规则。如果这些执行方式也需要不同，请在当前分组新建一条规则。

保存覆盖配置前，页面会展示最终生效配置和查询预览。清除覆盖后，当前分组会恢复使用上级配置。

### 7. 批量管理规则

在本组的 **规则** 标签页勾选本组规则后，可以执行批量操作，单次最多选择 100 条：

* **批量启用 / 批量停用**：确认后统一变更启用状态。批量停用会异步关闭相关活跃告警，重新启用不会恢复已关闭的告警
* **导出规则**：将选中的规则导出为 Entity Alert 规则包（`entity-alert-rules.yaml`），单次最多导出 100 条。导出的规则包可以在其他分组或租户通过 **导入规则** 重新导入，形成完整的迁移路径

规则列表中的 **启用状态** 开关可以单独启用或停用一条规则；停用前需要确认，相关活跃告警会异步关闭。

<Note>
  勾选、批量启停、导入和导出都需要实体树管理权限和当前分组的管理权限。没有管理权限的规则不能参与批量启停，但仍可随选中规则一起导出。
</Note>

## 查看运行状态

工作区右上角的 **查看运行状态** 按钮会打开运行状态抽屉，展示当前实体类别在所选数据源上的可用性、负责的 Edge 实例、计划同步结果，以及运行分片与发现状态。抽屉内容每 15 秒自动刷新，也可以点击 **刷新** 手动更新。

### 可用状态

| 状态 | 含义 |
| - | - |
| **运行正常** | 实体类别在该数据源上正常运行 |
| **初始化中** | 实体快照或运行分片正在初始化 |
| **暂不可用** | 计划未生效、Edge 断开、运行分片缺失等原因导致暂时无法提供实体数据 |
| **版本不支持** | Edge 版本低于 Entity Alert 的最低要求，页面会显示最低支持的 Edge 版本 |
| **状态未知** | 暂时无法获取运行状态 |

状态不是 **运行正常** 时，页面会给出原因说明。常见原因包括：没有兼容的 Edge、正在下发、计划同步失败、负责该数据源的 Edge 已断开、运行分片尚未创建、实体快照正在初始化或尚未生成等。当没有兼容的 Edge 时，Entity Alert 需要页面提示的最低版本或更高版本才能运行，普通告警规则不受影响。

### 负责实例

展示负责该数据源的 Edge 实例信息：实例 ID 与 IP:端口、Edge 版本、最近心跳时间，以及当前实体类别要求的最低支持版本。

### 计划同步

展示最近一次计划下发的结果（成功或失败）、格式版本、配置修订、最近尝试与最近成功时间，以及失败时的错误类型和错误摘要。页面还会把 Edge 上报的模板摘要、计划摘要与中心编译出的预期值进行比对，给出 **中心与 Edge 一致**、**中心与 Edge 不一致** 或 **等待 Edge 应用计划** 等结论。完整下发计划仅对实体类别管理者开放：没有管理权限时，该区域只展示 Edge 状态和分配摘要。

### 运行分片与发现

展示当前数据源的运行分片信息：分片阶段（初始化中、已就绪、评估中）、快照修订、活跃实体数、失联保留实体数、快照生成时间，以及发现相关的最近成功时间、发现耗时、发现结果数、连续发现失败次数、最近发现尝试时间。发现失败或活动基线回灌出错时，还会展示对应的错误摘要。

### 被忽略的查询结果

规则评估时，告警条件查询返回的每条序列都会先与当前实体快照核对：

* 缺少任一身份标签的序列会被静默忽略——不产生告警，也不会使规则评估失败
* 序列对应的实体不在当前实体快照（发现范围与分组范围）内时，同样会被静默忽略

这类忽略属于正常的评估行为，不计入执行错误。遇到“查询有数据、规则执行成功、但始终不触发告警”的情况时，可以沿两个方向排查：查询结果是否包含全部身份标签，以及查询覆盖的实体是否都在当前分组的发现范围内。

Edge 会把忽略数量导出为自监控指标 `monit_edge_entity_alert_condition_results_ignored_total`（labels：`definition_id`、`datasource_id`、`reason`）。`reason` 的取值：

| reason | 含义 |
| - | - |
| `missing_identity` | 序列缺少身份标签 |
| `out_of_scope` | 序列对应的实体超出当前实体快照范围 |

## 查看下发计划（调试）

拥有实体类别管理权限的账号，可以在工作区点击 **查看下发计划（调试）**，打开只读抽屉，查看由当前**已保存配置**编译出的完整执行计划。尚未保存的表单修改不会体现在计划中。

抽屉顶部的汇总卡片展示数据源、分组、规则和执行策略的数量，下面按四个部分展开：

| 部分 | 内容 |
| - | - |
| **实体类别参数** | 实体类别 ID、格式版本、同步周期、失联保留时间、身份标签、多值标签、模板摘要（可复制），可展开查看发现 PromQL |
| **数据源绑定** | 每个数据源的计划摘要（可复制），用于核对数据源维度的计划版本 |
| **分组与匹配器** | 分组树及每个分组的匹配表达式 |
| **规则执行摘要** | 每条启用规则的执行周期、时区、执行延迟、重复通知、规则标签、规则摘要（可复制），并按策略范围展开各执行策略 |

执行策略按 **策略范围**（实际生效的分组）展示：各告警级别是否启用、连续命中次数、参数值，恢复方式与连续恢复次数，以及告警 PromQL、恢复 PromQL 和配置标识（可复制）。同一规则经继承或覆盖后可能形成多个策略范围，会分别列出。

模板摘要、计划摘要、规则摘要和配置标识都可以一键复制，便于在工单中向技术支持描述当前配置的版本。

## 通过链接直达规则

实体树支持通过 URL 参数从外部链接直达某条实体告警规则。例如在告警详情等页面看到某条实体告警时，可以携带链接跳转到实体树，直接调整产生告警的规则。在实体树页面 URL 后附加以下参数：

```text theme={null}
?tab=rules&account_id=<租户 ID>&definition_id=<实体类别 ID>&datasource_id=<数据源 ID>&group_id=<分组 ID>&rule_id=<规则 ID>&open=edit
```

跳转成功后，页面会自动：

* 切换到 **规则** 标签页，自动选中链接指定的实体类别、分组和数据源，并展开对应分组
* 自动打开目标规则的抽屉：规则属于当前分组的打开**编辑**抽屉，规则继承自上级分组的打开**覆盖**抽屉

如果链接无法生效，页面会给出对应错误提示：

* 链接中的租户 ID 与当前登录组织不一致：提示切换组织后重试
* 实体类别、分组、数据源或规则不存在（例如规则已被删除）：提示无法定位告警规则
* 当前账号没有实体树管理权限或对应分组的规则管理权限：不打开抽屉，提示没有规则管理权限

<Note>
  URL 中的各 ID 均为正整数。参数缺失、非法或未携带 `open=edit` 时，链接不会生效，页面按普通方式打开。
</Note>

## 规则名称与注解模板变量

规则名称和注解支持 Go `text/template` 语法。模板在告警引擎侧、每次产生告警事件时渲染，可以引用当次评估的标签、数值和实体上下文。渲染失败时，对应字段会显示 `<error expanding template: ...>`，您可以在规则的执行错误摘要中查看原因。

### 内置变量

| 变量 | 类型 | 说明 |
| - | - | - |
| `$labels` | `map[string]string` | 告警标签。用 `$labels.<name>` 或 `index $labels "<name>"` 读取单个标签，标签不存在时返回空字符串 |
| `$value` | `float64` | 当次评估的告警值 |
| `.Labels` | `map[string]any` | 与 `$labels` 相同 |
| `.Value` | `float64` | 与 `$value` 相同 |
| `.EntityAlert` | `map[string]any` | 实体告警上下文，可用字段见下表 |
| `$__entity_alert` | `map[string]any` | 与 `.EntityAlert` 相同，字段见下表。规则编辑器的 **可用变量** 面板中展示为 `$__entity_alert.*` 写法，其中 `$__entity_alert.name` 仅注解模板可用 |

### `.EntityAlert` 字段

| 字段 | 说明 |
| - | - |
| `.EntityAlert.entity_key` | 实体标识 |
| `.EntityAlert.entity_definition_id` / `.EntityAlert.entity_definition_name` | 实体类别 ID 和名称 |
| `.EntityAlert.rule_id` | 规则 ID |
| `.EntityAlert.name` | 渲染后的规则名称，仅注解模板可用，规则名称不能引用自身 |
| `.EntityAlert.event_kind` | 事件类型：`firing`、`severity_changed`、`repeat`、`recovery` 或 `closed` |
| `.EntityAlert.value` | 当次评估的告警值，与 `$value` 相同 |
| `.EntityAlert.promql` | 实际生效的告警 PromQL |
| `.EntityAlert.recovery_promql` | 实际生效的恢复 PromQL；未配置独立恢复查询时为空 |
| `.EntityAlert.query_at_ms` | 查询时间，Unix 毫秒时间戳 |
| `.EntityAlert.policy_scope_group_id` | 实际生效策略所在的分组 ID |
| `.EntityAlert.account_id` | 租户 ID |
| `.EntityAlert.data_source_name` / `.EntityAlert.data_source_type` | 数据源名称和类型 |
| `.EntityAlert.entity_multi_value_fields` | 多值标签的取值集合 |

多值标签在 `.EntityAlert.entity_multi_value_fields` 中以集合形式提供，可配合 `len`、`range`、`join`、`has`、`first`、`last` 和 `toJSON` 函数读取：

```gotemplate theme={null}
{{ join "," (index .EntityAlert.entity_multi_value_fields "biz_group") }}
```

规则名称示例：

```gotemplate theme={null}
节点 {{ $labels.instance }} CPU 使用率 {{ printf "%.1f" $value }}%
```

注解示例（每个注解字段单独是一段模板）：

```gotemplate theme={null}
https://example.com/runbooks/node-cpu?entity={{ .EntityAlert.entity_key }}
```

### 查询与常用函数

除常用变量外，模板还支持在 Edge 上执行查询并对结果取值、排序和格式化。规则编辑器的 **可用变量** 面板中可以直接复制以下示例：

| 表达式 | 类型 | 说明 |
| - | - | - |
| `{{ query "up" }}` | vector | 在 Edge 按本次评估时间执行 PromQL 即时查询 |
| `{{ value (first (query "up")) }}` | float64 | 读取查询结果第一条样本的值 |
| `{{ label "instance" (first (query "up")) }}` | string | 读取查询结果样本的标签 |
| `{{ sortByLabel "instance" (query "up") }}` | vector | 按标签排序查询结果，可配合 `range` 使用 |
| `{{ humanize $value }}` | string | 使用常用 Prometheus 格式化函数（humanize 等）或 `printf` 格式化数值 |

## 查看实体和告警

选择实体类别、分组和数据源后，工作区提供三个标签页：

| 标签页 | 可以查看的内容 |
| - | - |
| **实体** | 当前分组中的实体标识、状态、标签、归属分组和最近发现时间。可按状态、实体标识前缀或标签筛选 |
| **规则** | 本组规则、继承规则、启用状态、最近评估时间、命中的实体和告警数量。可查看执行历史和错误摘要 |
| **活跃告警** | 告警级别、名称、实体标识、告警维度、实际生效的策略分组、当前值、通知次数和触发时间。可按级别、规则、精确实体标识和实际策略范围筛选 |

实体标签页最多展示前 200 条实体；匹配结果超过上限时，页面会提示仅显示前 200 条，请缩小筛选范围。

在 **规则** 标签页中，点击某条规则的名称可以直接打开对应抽屉：规则属于当前分组的打开**编辑**抽屉，规则继承自上级分组的打开**覆盖**抽屉，与[通过链接直达规则](#通过链接直达规则)的跳转行为一致；当前账号没有实体树管理权限或对应分组的规则管理权限时，会提示无权限，不打开抽屉。

点击活跃告警行（或行内的 **查看详情** 按钮），可以进一步确认实体来源、规则、告警维度、标签和通知情况。排障时先确认页面顶部的数据源和当前分组，再检查规则的来源分组与实际策略范围。

活跃告警标签页的筛选栏支持按 **级别** 和 **规则**（可搜索下拉）筛选；**更多筛选** 中还可以输入 **精确实体标识** 精确过滤（也可以直接点击表格中的实体标识）。选择规则后，还可以按 **实际策略范围** 筛选，定位同一规则经继承或覆盖后实际生效的策略范围。按多值标签筛选达到扫描上限时，页面会提示本页结果不完整，请缩小分组或其他筛选范围后重试。

### 规则执行历史

在 **规则** 标签页点击某条规则的 **查看执行历史**，抽屉展示该规则最近 24 小时内保留的实际执行记录。默认查询最近 15 分钟，也支持最近 5 分钟、30 分钟、1 小时、4 小时、1 天的预设和自定义范围；可查询范围的下界固定为当前时刻往前 24 小时。

每条记录展示执行结果（成功或失败）、查询时间、耗时、命中的实体数和告警数。展开后可以查看查询时间与日志入库时间、Edge 实例、执行 ID、规则摘要，失败时的错误类型与错误摘要，以及本次评估中告警查询和恢复查询**实际执行的 PromQL**（参数替换后的最终表达式）、结果、耗时和返回条数。

匹配记录超过 200 条时只展示最近 200 条，请缩小时间范围查看更早的记录。执行历史依赖服务端 VictoriaLogs：如果服务端尚未配置 VictoriaLogs 查询地址，抽屉会提示 **执行历史暂不可用**；日志查询服务不可用时，请稍后重试。

## 理解失联保留

实体可能因抓取抖动、短暂网络故障或滚动发布，从一次成功的发现结果中暂时消失。失联保留期间：

* 实体状态显示为 **失联保留**
* 系统暂停该实体的告警判断、恢复判断和重复通知
* 实体重新出现时会延续原有告警状态
* 超过保留时间仍未出现时，相关活跃告警会结束

失联保留时间至少为 3600 秒。请根据资源的正常重建周期设置，不要用过短时间放大瞬时抖动。

## 配置变更注意事项

以下操作会改变实体身份、分组范围或告警生命周期：

* **修改身份标签**：页面会先预览身份迁移对实体和恢复规则的影响，列出所有受影响的恢复规则并分为 **自动改写** 与 **需要人工处理**（附原因）。您可以编辑迁移后的恢复 PromQL；**需要人工处理**的规则必须勾选“我已检查并确认此恢复 PromQL”后才能提交。确认迁移后，旧身份关联的活跃告警会关闭，新身份会重新发现实体。该操作不能无损撤销
* **修改多值标签**：实体会重新分类，相关告警会按新配置重新评估
* **修改分组条件或规则覆盖**：实体的有效范围或策略可能变化，当前告警可能结束并按新配置重新评估
* **修改本组规则**：保存前页面会预览本次修改对后代节点覆盖配置的影响，并列出受影响的覆盖数量。如果修改导致部分级别覆盖或参数覆盖失效，对话框会要求您确认后永久清理；清理后的覆盖配置无法恢复
* **停用或删除规则**：相关活跃告警会异步结束；重新启用不会恢复已经结束的告警
* **删除实体类别或分组**：必须先清理页面提示的依赖项，受影响的活跃告警会异步结束

<Warning>
  在生产环境修改身份标签、分组条件或继承覆盖前，先使用页面提供的预览确认影响，并选择业务低峰期操作。
</Warning>

## 最佳实践

* 为实体类别选择稳定的身份标签，并在上线前用多个数据源预览
* 按“环境 → 区域 → 业务”等稳定维度设计分组，避免复制组织架构中的临时层级
* 把通用规则放在较高层级，只在确有差异的子分组覆盖阈值
* 需要不同查询或调度时新建规则，不要把一条继承规则改造成过多例外
* 定期查看规则最近评估、执行历史和活跃告警，及时处理数据源或告警引擎版本问题


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