# 标签、注解与身份

标签决定一个事件「是谁」，注解决定通知里能看到什么，两者不能混用。

最后校对于 2026-10-10

标签和注解看起来都是「挂在事件上的键值对」，但作用完全不同，混用会直接把降噪搞坏。

|              | 标签（labels）                      | 注解（annotations）                |
| ------------ | ----------------------------------- | ---------------------------------- |
| 作用         | 决定事件的**身份**                  | 给人看的**上下文**                 |
| 参与匹配吗   | 参与。屏蔽、订阅、路由都按它匹配    | 不参与                             |
| 值变了会怎样 | **变成另一个事件**                  | 只是消息内容变了                   |
| 典型内容     | `ident`、`env`、`service`、`region` | 当前值、影响面、处理建议、跳转链接 |

## 标签决定「是不是同一个告警」[​](#标签决定是不是同一个告警 "标签决定「是不是同一个告警」的直接链接")

事件的身份 = 规则 + 标签集。这条规则直接决定了三件事：

* 同一条规则跑在 5 台机器上，因为 `ident` 不同，产生 **5 个独立事件**， 各自触发、各自恢复；
* 屏蔽规则写 `ident=n9e-web-01`，只屏蔽那一台，其余照常；
* 标签集**每次判定都在变**的话，每次都会被当成新告警——这是「告警刷屏」最常见的成因。

所以标签里**不要放会变的东西**。当前 CPU 使用率是数值，属于注解； `pod` 名字如果每次重建都变，也不该单独当身份标签。

## 标签从哪来[​](#标签从哪来 "标签从哪来的直接链接")

三个来源，按优先级叠加：

1. **查询结果自带的**——PromQL 返回的 series 上原本就有的标签，比如 `ident`、`instance`；
2. **规则上追加的**——规则表单里的「附加标签」，比如 `service=trade`、`team=infra`， 用来给这条规则产生的所有事件统一打标；
3. **Pipeline 加的**——事件产生后，用标签富化处理器从 CMDB 查负责人、机房再补上去。

第 2 类最常用：路由和订阅都靠它。**规划标签的时候先想「后面要按什么分流」**， 那些维度就是该放进标签的。

## 注解写给收到消息的人[​](#注解写给收到消息的人 "注解写给收到消息的人的直接链接")

注解会渲染进通知消息。写的时候设想一个凌晨三点被叫醒、什么上下文都没有的人， 他需要什么：

```
summary:     n9e-web-01 内存使用率 87%

impact:      订单入口，影响下单

runbook_url: https://wiki.internal/runbook/host-memory
```

注解里可以用模板变量引用事件字段和查询结果，所以能把当前值直接写进去。

**别把该当身份的东西写进注解**：写在注解里的 `env`，屏蔽规则是匹配不到的。

## 一个常见错误[​](#一个常见错误 "一个常见错误的直接链接")

把机器 IP 放进注解、把当前值放进标签，正好反了。结果是：

* 想屏蔽某台机器，匹配不上（IP 在注解里）；
* 每次判定值都不一样，事件不断被当成新的（值在标签里）。

判断方法很简单：**这个字段将来会不会被用来「筛选」？** 会，就是标签；只是给人读的，就是注解。

## 相关[​](#相关 "相关的直接链接")

* [标签、注解与级别](https://n9e.github.io/zh/docs/alerting/labels-severity.md)
* [改写标签与富化上下文](https://n9e.github.io/zh/docs/events/relabel-enrich.md)
* [通知模板变量](https://n9e.github.io/zh/docs/reference/notification-variables.md)