Prometheus 告警规则富化 Entity 信息-云监控(CMS)-阿里云帮助中心

Prometheus 原生告警的 labels 通常只有 instance、pod、namespace、job 等维度字符串，只能表达“某条曲线越过了阈值”，无法关联到云监控 UModel 中的具体实体。云监控 2.0 支持在 Prometheus 告警规则的 annotations 中以自定义键的形式声明实体标签，把告警绑定到应用、接口、Pod、前端监控对象或自建业务对象等实体。本文介绍如何声明实体标签，并验证实体关联是否生效。

业务场景与目标效果

云监控 2.0 的下游能力依赖一个稳定的实体身份，该身份由三个要素构成：

实体域（domain）
实体类型（entity_type）
实体 ID（entity_id）

完成本文配置后，告警事件中会带上 _cms_domain、_cms_entity_type、_cms_entity_id 三个字段。

富化实体前后的能力差异如下：

能力	未富化实体	已富化实体
告警聚合	只能按告警规则维度聚合。	同一实体在收敛窗口内的重复告警可以按实体聚合。
根因分析	无法沿实体关系上下钻取。	可沿实体关系链路做上下游钻取。
静默与屏蔽	只能按 label 组合匹配。	可按单个实体精确控制。
事件中心	事件缺少稳定的实体身份。	事件挂载到实体节点，可按实体维度检索与治理。

前提条件

已开通云监控 2.0，并已创建工作空间。
已在工作空间中接入 Prometheus 数据源，且已创建或准备创建 Prometheus 类型的告警规则。
已确认目标实体类型在云监控 UModel 元数据表中存在。标准的 ACS 云产品、APM 应用、K8s 容器洞察类型由云监控预置，无需登记；自建业务实体需先登记 entity_type 及其 primaryKeys。

步骤一：确认实体域与实体类型

明确本条告警规则的告警对象，即告警最终应该落到哪一类实体上。

按下表确定 custom_cms_domain 与 custom_cms_entity_type 的取值。

实体域（domain）	适用对象	entity_type 示例
`apm`	应用监控接入的应用与接口	`apm.service`、`apm.operation`
`acs`	阿里云云产品实例	`acs.vpc.peerconnection`
`k8s`	容器服务集群内的工作负载	`k8s.pod`
`rum`	前端用户体验监控对象	`rum.service`
自定义域名，如 `mybiz`	自建业务实体	`mybiz.channel`

确认告警指标的 series 中包含该 entity_type 的 primaryKey 对应的 label。例如 apm.service 的 primaryKeys 为 service_id，对应的指标 label 为 acs_arms_service_id；若指标中缺少该 label，后端将无法自动生成 entity_id。

说明

一条告警规则只能声明一个实体维度。如果同一指标既需要按服务告警又需要按接口告警，请拆分为两条规则，不要在一条规则中声明多个 entity_type。

步骤二：在告警规则中添加实体标签

实体标签以自定义键的形式声明在 Prometheus 告警规则的 annotations 中。

在云监控 2.0 控制台打开 Prometheus 告警规则的编辑页面。
在告警规则的 annotations 中声明下表所列的自定义键，其余富化工作由后端通过 SPL 自动完成。
保存并发布告警规则。

下表说明需要声明的参数。

参数	是否必填	说明
`custom_cms_domain`	是	实体所属域，取值如 `apm`、`acs`、`k8s`、`rum`，或自定义域名。
`custom_cms_entity_type`	是	具体的实体类型，取值如 `apm.service`、`acs.vpc.peerconnection`、`rum.service`。支持 Go Template 语法。
`custom_cms_entity_id`	否	直接指定实体 ID，支持 Go Template 语法，写法参见示例二与示例三。不填时，后端根据 `domain` 与 `entity_type` 查询预置元数据表，用 `primaryKeys` 和 `fieldMapping` 自动生成。
`custom_cms_entity_id_fields`	否	当 entity_id 需要额外的变量赋值时，以 `a=b,c=d` 形式提供键值对。一般无需配置。

示例一：标准云产品与 APM 应用

告警指标本身属于阿里云产品（ACS）或 APM 服务时，只需声明两个必填参数，entity_id 由后端按元数据表自动计算。

以 APM 应用为例：

annotations:
  custom_cms_domain: apm
  custom_cms_entity_type: apm.service

以 VPC 对等连接为例：

annotations:
  custom_cms_domain: acs
  custom_cms_entity_type: acs.vpc.peerconnection

后端从 label instanceId 中取值生成 entity_id，字段映射规则（instance_id 到 instanceId）已内置，无需在告警规则中声明。

示例二：按接口或 RPC 维度告警

需要在同一 APM 应用下按接口维度拆分告警时，实体应细化到“服务 + 接口”。此时用 Go Template 组合两个 label：

annotations:
  custom_cms_domain: apm
  custom_cms_entity_type: "{{ if $labels.rpc }}apm.operation{{ else }}apm.service{{ end }}"
  custom_cms_entity_id: "{{ if $labels.rpc }}{{ printf \"%s-%s\" $labels.acs_arms_service_id $labels.rpc | md5 }}{{ else }}{{ printf \"%s\" $labels.acs_arms_service_id | md5 }}{{ end }}"

示例三：自建或自定义业务实体

自建业务实体需声明自定义的域名与 entity_type，并用 Go Template 从业务 label 构造 entity_id：

annotations:
  custom_cms_domain: mybiz
  custom_cms_entity_type: mybiz.channel
  custom_cms_entity_id: "{{ printf \"%s-%s\" $labels.tenant_id $labels.channel_id | md5 }}"

步骤三：验证实体关联是否生效

发布规则后，通过以下任一方式确认实体富化已生效。

在事件中心查看事件详情：登录云监控 2.0 控制台，选择目标工作空间，进入事件中心，找到该规则触发的事件详情，确认 resource.entity 下的 domain、entityType、entityId 三项均非空。
在告警规则详情页预览：在告警规则详情页触发一次预览查询，若返回的 series 中携带 _cms_entity_id 字段（长度为 32 的十六进制字符串），说明实体富化已生效。
在实体拓扑视图查看落点：在事件中心的实体拓扑视图中，告警对应的实体应能高亮显示，颜色随告警等级变化。