实体树从数据源发现实体，并按动态分组继承告警策略
适用场景
实体树适合以下场景：- Kubernetes Pod、云主机、数据库实例等对象频繁创建、销毁或变化
- 多个环境或业务使用相同指标，但告警阈值不同
- 你希望按区域、环境、集群、团队或服务等标签自动管理告警范围
- 多个 Prometheus 数据源需要复用同一套实体定义和告警策略
实体树如何组织监控
同一组身份标签值在不同数据源中会形成不同实体。你可以在工作区切换数据源，分别查看实体、规则执行结果和活跃告警。
使用前准备
开始前，请确认：- 当前租户已启用 Monitors，并已部署告警引擎
- 已创建至少一个 Prometheus 数据源
- 你的账号拥有实体树查看权限；创建或修改配置还需要实体树管理权限、相应实体类别或分组的管理权限，以及对所选用数据源的查询权限
- 告警引擎版本满足实体树页面提示的要求
配置实体树
1. 申请开通
进入 Monitors > 实体树。如果当前租户尚未开通，点击 申请开通。申请提交后，页面会显示申请时间；审核通过后即可开始配置。2. 创建实体类别
实体类别决定系统如何发现并识别一类资源。点击 创建实体类别，完成以下配置：
精确匹配和名称通配可以同时使用，系统会使用两者匹配到的全部数据源。至少配置一种匹配方式。
保存实体类别时还会校验数据源权限：主体账号和租户管理员不受此限制，其他成员必须对本次选中的每个 Prometheus 数据源都拥有查询（只读）权限；名称通配按保存当下匹配到的数据源逐个校验，匹配到任一你无权查询的数据源即拒绝保存，并返回无权限引用该数据源的错误。缩小或移除数据源选择不受此限制——失去某个数据源的权限后，仍然可以把该数据源从实体类别中去掉。实体类别的数据源列表同样按查看者权限过滤，你无权查询的数据源不会出现在它的数据源配置和已解析数据源列表中。
{} 花括号语法；名称最多 128 个字符，发现 PromQL 最多 1024 个字符；编辑已有实体类别时，不能在同一次保存中同时修改身份标签和多值标签，需要分两次完成。
发现 PromQL 输入框的右上角提供 AI 帮我写 入口（鼠标悬停或光标聚焦到输入框时渐显），可以让 AI 查询助手生成或改写发现查询；助手在实体树中只回填查询语句，不会切换数据源。详见 AI 查询助手。
例如，以下查询可以发现带有 instance 标签的节点：
- 每条结果是否都包含身份标签
- 同一身份是否出现普通单值标签冲突
- 多条结果会如何按身份合并
3. 创建动态分组
创建实体类别后，页面左侧会显示实体类别和分组树。左侧面板顶部的搜索框可以按名称搜索实体类别和分组，匹配的节点会高亮并自动展开。在目标节点的操作菜单中选择 创建子分组，并使用标签条件定义实体范围。创建或编辑分组时，抽屉中还提供可选的 管理团队 配置：当前分组的团队权限会向子分组继承，同时保留实体类别和上级分组已有权限。
匹配条件的标签名必须符合
^[A-Za-z_][A-Za-z0-9_]*$ 格式，且 __name__ 为系统保留字段，不能使用。
选择实体类别和数据源后，标签名和匹配值输入框会针对当前实体类别、数据源和分组范围内的实体快照自动补全候选项，每个候选项会标注命中它的实体数量。使用 =~ 或 !~ 时，匹配值输入框进入正则候选模式，选中候选项会自动转义为正则字面量；候选项较多时页面会提示继续输入以缩小范围。部分实体缺失所选标签或值为空时，值候选顶部会出现 为空（缺失或没有值） 选项。当前 Edge 版本不支持运行时查询时，正则候选不可用，但仍可手动输入正则表达式并保存。
同一分组中的多个条件必须全部满足。子分组还会继承全部上级分组的条件。
例如，你可以先创建 env = prod 的“生产环境”分组，再在其下创建 service = payment 的“支付服务”分组。第二个分组最终只包含同时满足两个条件的实体。
实体可以同时命中多个同级分组。请让同级分组表达清晰、互不冲突的管理维度，并在配置不同规则覆盖时检查最终告警范围。
4. 创建实体告警规则
选择要承载规则的分组，打开 规则 标签页，然后点击 创建规则。
规则创建在当前分组，并自动作用于当前分组和所有匹配的后代实体。规则列表会分别展示 本组规则 和 继承规则，帮助你判断规则来自哪个层级。
告警条件 PromQL 输入框的右上角同样提供 AI 帮我写 入口，可以让 AI 查询助手生成或改写语句；实体树中助手只回填查询语句，不会切换数据源。详见 AI 查询助手。
规则标签与注解的名称必须匹配
^[A-Za-z_][A-Za-z0-9_]*$，且不能使用系统保留名称 check 或以 __entity_alert_、__flashduty_ 开头的名称；与实体身份标签同名的标签或注解会被拒绝，因为身份标签不能被规则标签或注解覆盖。查询预览
条件 PromQL 和恢复 PromQL 输入框旁的 查询预览 按钮可以打开预览对话框（需要当前实体类别绑定至少一个 Prometheus 数据源）。对话框会把参数与标签变量替换后的最终执行的 PromQL 发送到所选数据源执行即时查询：- 条件查询会为每个启用的告警级别生成一个变体，可以在对话框中选择 告警级别，用该级别填写的参数值替换
${参数名}占位符 - 恢复查询会读取当前规则的活跃告警，可以从 预览告警 中选择一条，用该告警的实体标签和告警维度替换
${labels.<名称>}占位符；规则尚未保存或当前没有活跃告警时，只能退回使用实体标签，告警维度需等规则保存并产生告警后才能解析 - 打开对话框后会自动执行一次查询，切换数据源或级别后也会重新执行，还可以点击 重新查询 手动重跑
尚未选择身份标签时，对话框只展示返回记录，并提示选择身份标签后才能计算有效实体和诊断。查询没有返回记录不代表规则配置无效，可以换个时间再试。
条件 PromQL 使用
${参数名} 占位符复用查询。完整输入参数名并离开编辑器后，页面会为每个告警级别自动创建对应参数项。预览替换失败时会给出具体错误：参数占位符缺少结束符（占位符未闭合）、参数占位符“{{name}}”没有可用值（未填写参数值）、参数“{{name}}”未在 PromQL 中引用（填写了参数但查询中没有使用）。
恢复 PromQL 同样支持 ${参数名}（例如 ${threshold}）；此外还可以引用实体单值标签和当前告警的标量维度，写法为 ${labels.instance}、${labels.path}、${labels.busigroup}，且只能写在 PromQL 双引号字符串内。离开编辑器后会自动创建普通参数项，实体标签不会创建参数项。
5. 导入告警规则
除了逐条创建，你还可以在分组的 规则 标签页点击 导入规则，上传 YAML 文件批量导入到当前分组。系统会自动识别三种来源格式：
限制与要求：
- 一次只能上传一个不超过 1 MB 的
.yaml或.yml文件，单次最多导入 100 条规则 - 不支持 recording rule（只定义
record的规则会被忽略）；同一条规则不能同时配置alert和record - 规则标签的值不能包含
{{ }}动态模板；PromQL 必须返回瞬时向量，比较表达式不能使用bool修饰符 - 从 Prometheus 格式导入时，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}}），不会阻断其余规则的导入
6. 覆盖继承规则
如果子分组需要不同阈值，在子分组的 继承规则 列表中选择 覆盖继承规则。你可以调整：- 告警级别是否继承、启用或停用
- 各告警级别的参数和连续命中次数
- 恢复查询参数和连续恢复次数
7. 批量管理规则
在本组的 规则 标签页勾选本组规则后，可以执行批量操作，单次最多选择 100 条：- 批量启用 / 批量停用：确认后统一变更启用状态。批量停用会异步关闭相关活跃告警，重新启用不会恢复已关闭的告警
- 导出规则：将选中的规则导出为 Entity Alert 规则包（
entity-alert-rules.yaml），单次最多导出 100 条。导出的规则包可以在其他分组或租户通过 导入规则 重新导入，形成完整的迁移路径
勾选、批量启停、导入和导出都需要实体树管理权限和当前分组的管理权限。没有管理权限的规则不能参与批量启停，但仍可随选中规则一起导出。
查看运行状态
工作区右上角的 查看运行状态 按钮会打开运行状态抽屉，展示当前实体类别在所选数据源上的可用性、负责的 Edge 实例、计划同步结果，以及运行分片与发现状态。抽屉内容每 15 秒自动刷新，也可以点击 刷新 手动更新。可用状态
状态不是 运行正常 时，页面会给出原因说明。常见原因包括：没有兼容的 Edge、正在下发、计划同步失败、负责该数据源的 Edge 已断开、运行分片尚未创建、实体快照正在初始化或尚未生成等。当没有兼容的 Edge 时，Entity Alert 需要页面提示的最低版本或更高版本才能运行，普通告警规则不受影响。
负责实例
展示负责该数据源的 Edge 实例信息：实例 ID 与 IP:端口、Edge 版本、最近心跳时间，以及当前实体类别要求的最低支持版本。计划同步
展示最近一次计划下发的结果（成功或失败）、格式版本、配置修订、最近尝试与最近成功时间，以及失败时的错误类型和错误摘要。页面还会把 Edge 上报的模板摘要、计划摘要与中心编译出的预期值进行比对，给出 中心与 Edge 一致、中心与 Edge 不一致 或 等待 Edge 应用计划 等结论。完整下发计划仅对实体类别管理者开放：没有管理权限时，该区域只展示 Edge 状态和分配摘要。运行分片与发现
展示当前数据源的运行分片信息：分片阶段（初始化中、已就绪、评估中）、快照修订、活跃实体数、失联保留实体数、快照生成时间，以及发现相关的最近成功时间、发现耗时、发现结果数、连续发现失败次数、最近发现尝试时间。发现失败或活动基线回灌出错时，还会展示对应的错误摘要。被忽略的查询结果
规则评估时，告警条件查询返回的每条序列都会先与当前实体快照核对：- 缺少任一身份标签的序列会被静默忽略——不产生告警，也不会使规则评估失败
- 序列对应的实体不在当前实体快照（发现范围与分组范围）内时，同样会被静默忽略
monit_edge_entity_alert_condition_results_ignored_total（labels：definition_id、datasource_id、reason）。reason 的取值：
查看下发计划（调试）
拥有实体类别管理权限的账号，可以在工作区点击 查看下发计划（调试），打开只读抽屉，查看由当前已保存配置编译出的完整执行计划。尚未保存的表单修改不会体现在计划中。 抽屉顶部的汇总卡片展示数据源、分组、规则和执行策略的数量，下面按四个部分展开：
执行策略按 策略范围（实际生效的分组）展示：各告警级别是否启用、连续命中次数、参数值，恢复方式与连续恢复次数，以及告警 PromQL、恢复 PromQL 和配置标识（可复制）。同一规则经继承或覆盖后可能形成多个策略范围，会分别列出。
模板摘要、计划摘要、规则摘要和配置标识都可以一键复制，便于在工单中向技术支持描述当前配置的版本。
通过链接直达规则
实体树支持通过 URL 参数从外部链接直达某条实体告警规则。例如在告警详情等页面看到某条实体告警时，可以携带链接跳转到实体树，直接调整产生告警的规则。在实体树页面 URL 后附加以下参数：- 切换到 规则 标签页，自动选中链接指定的实体类别、分组和数据源，并展开对应分组
- 自动打开目标规则的抽屉：规则属于当前分组的打开编辑抽屉，规则继承自上级分组的打开覆盖抽屉
- 链接中的租户 ID 与当前登录组织不一致：提示切换组织后重试
- 实体类别、分组、数据源或规则不存在（例如规则已被删除）：提示无法定位告警规则
- 当前账号没有实体树管理权限或对应分组的规则管理权限：不打开抽屉，提示没有规则管理权限
URL 中的各 ID 均为正整数。参数缺失、非法或未携带
open=edit 时，链接不会生效，页面按普通方式打开。规则名称与注解模板变量
规则名称和注解支持 Gotext/template 语法。模板在告警引擎侧、每次产生告警事件时渲染，可以引用当次评估的标签、数值和实体上下文。渲染失败时，对应字段会显示 <error expanding template: ...>，你可以在规则的执行错误摘要中查看原因。
内置变量
.EntityAlert 字段
多值标签在
.EntityAlert.entity_multi_value_fields 中以集合形式提供，可配合 len、range、join、has、first、last 和 toJSON 函数读取：
查询与常用函数
除常用变量外，模板还支持在 Edge 上执行查询并对结果取值、排序和格式化。规则编辑器的 可用变量 面板中可以直接复制以下示例：查看实体和告警
选择实体类别、分组和数据源后，工作区提供三个标签页：
实体标签页最多展示前 200 条实体；匹配结果超过上限时，页面会提示仅显示前 200 条，请缩小筛选范围。
在 规则 标签页中，点击某条规则的名称可以直接打开对应抽屉：规则属于当前分组的打开编辑抽屉，规则继承自上级分组的打开覆盖抽屉，与通过链接直达规则的跳转行为一致；当前账号没有实体树管理权限或对应分组的规则管理权限时，会提示无权限，不打开抽屉。
点击活跃告警行（或行内的 查看详情 按钮），可以进一步确认实体来源、规则、告警维度、标签和通知情况。排障时先确认页面顶部的数据源和当前分组，再检查规则的来源分组与实际策略范围。
活跃告警标签页的筛选栏支持按 级别 和 规则（可搜索下拉）筛选；更多筛选 中还可以输入 精确实体标识 精确过滤（也可以直接点击表格中的实体标识）。选择规则后，还可以按 实际策略范围 筛选，定位同一规则经继承或覆盖后实际生效的策略范围。按多值标签筛选达到扫描上限时，页面会提示本页结果不完整，请缩小分组或其他筛选范围后重试。
规则执行历史
在 规则 标签页点击某条规则的 查看执行历史，抽屉展示该规则最近 24 小时内保留的实际执行记录。默认查询最近 15 分钟，也支持最近 5 分钟、30 分钟、1 小时、4 小时、1 天的预设和自定义范围；可查询范围的下界固定为当前时刻往前 24 小时。 每条记录展示执行结果（成功或失败）、查询时间、耗时、命中的实体数和告警数。展开后可以查看查询时间与日志入库时间、Edge 实例、执行 ID、规则摘要，失败时的错误类型与错误摘要，以及本次评估中告警查询和恢复查询实际执行的 PromQL（参数替换后的最终表达式）、结果、耗时和返回条数。 匹配记录超过 200 条时只展示最近 200 条，请缩小时间范围查看更早的记录。执行历史依赖服务端 VictoriaLogs：如果服务端尚未配置 VictoriaLogs 查询地址，抽屉会提示 执行历史暂不可用；日志查询服务不可用时，请稍后重试。理解失联保留
实体可能因抓取抖动、短暂网络故障或滚动发布，从一次成功的发现结果中暂时消失。失联保留期间：- 实体状态显示为 失联保留
- 系统暂停该实体的告警判断、恢复判断和重复通知
- 实体重新出现时会延续原有告警状态
- 超过保留时间仍未出现时，相关活跃告警会结束
配置变更注意事项
以下操作会改变实体身份、分组范围或告警生命周期：- 修改身份标签：页面会先预览身份迁移对实体和恢复规则的影响，列出所有受影响的恢复规则并分为 自动改写 与 需要人工处理（附原因）。你可以编辑迁移后的恢复 PromQL；需要人工处理的规则必须勾选“我已检查并确认此恢复 PromQL”后才能提交。确认迁移后，旧身份关联的活跃告警会关闭，新身份会重新发现实体。该操作不能无损撤销
- 修改多值标签：实体会重新分类，相关告警会按新配置重新评估
- 修改分组条件或规则覆盖：实体的有效范围或策略可能变化，当前告警可能结束并按新配置重新评估
- 修改本组规则：保存前页面会预览本次修改对后代节点覆盖配置的影响，并列出受影响的覆盖数量。如果修改导致部分级别覆盖或参数覆盖失效，对话框会要求你确认后永久清理；清理后的覆盖配置无法恢复
- 停用或删除规则：相关活跃告警会异步结束；重新启用不会恢复已经结束的告警
- 删除实体类别或分组：必须先清理页面提示的依赖项，受影响的活跃告警会异步结束
最佳实践
- 为实体类别选择稳定的身份标签，并在上线前用多个数据源预览
- 按“环境 → 区域 → 业务”等稳定维度设计分组，避免复制组织架构中的临时层级
- 把通用规则放在较高层级，只在确有差异的子分组覆盖阈值
- 需要不同查询或调度时新建规则，不要把一条继承规则改造成过多例外
- 定期查看规则最近评估、执行历史和活跃告警，及时处理数据源或告警引擎版本问题