附加信息与附加查询

从用户视角讲清夜莺告警规则「事件处理」区块中附加信息（Annotations）与附加查询（Enrich Queries）的区别与用法：一个是预先写好的静态说明，一个是告警时刻对数据源的实时查询。

概述

告警规则编辑页第 6 步「事件处理」区块的底部，有两个名字很像的配置项：附加信息和附加查询。它们都用于给告警事件"补充内容"，让通知消息携带更多上下文，但内容的来源完全不同：

	附加信息（Annotations）	附加查询（Enrich Queries）
内容从哪来	配置规则时预先写好的 Key:Value 说明（可含模板变量）	告警触发时实时查询数据源得到的数据
内容什么时候确定	事件生成时渲染变量，其余内容固定不变	每次告警触发时现查，随现场数据变化
典型用途	预案链接、仪表盘链接、摘要说明	把命中告警的原始日志样本带进通知
适用范围	所有数据源类型	仅日志类数据源（Elasticsearch、Doris、阿里云 SLS、腾讯云 CLS），商业版功能
通知模板引用	`{{$event.AnnotationsJSON.xxx}}`	`{{$event.ExtraInfo}}` / `{{$event.ExtraInfoMap}}`

一句话选择：想给告警带上固定的说明或链接，用附加信息；想让通知里直接出现告警那一刻查到的现场数据（比如报错日志原文），用附加查询。两者互不冲突，可以同时配置。

附加信息：给事件带上"说明书"

附加信息是若干条 Key:Value，会附加到该规则产生的每条告警事件上，展示在事件详情页；以 http 开头的 Value 会渲染成可点击的链接。

常用 Key

Key 可以任意自定义，下面几个是产品约定的常用 Key：

Key	用途
`runbook_url`	预案 / 处理手册链接，事件详情里可直接点击
`dashboard_url`	相关仪表盘链接，方便一键跳转看图
`summary`	摘要说明，补充告警的背景和影响
`recovery_promql`	特殊 Key：恢复事件产生时，系统会执行这条 PromQL，把查到的当前值写入事件的 `recovery_value` 注解，用于在恢复通知里回答"恢复之后当前值是多少"；查询失败时会写入 `recovery_promql_error`

Value 支持模板变量

Value 在事件生成时渲染，可以引用 $labels（事件标签）和 $value（触发时值），语法与规则名称、备注一致。比如给仪表盘链接带上机器参数：

https://grafana.example.com/d/host-overview?var-ident={{$labels.ident}}

这样一条覆盖几十台机器的规则，每台机器的告警事件里都是指向它自己的仪表盘链接。

在通知模板中引用

事件详情页会自动逐项展示附加信息；如果想在通知消息里引用某一项，用 $event.AnnotationsJSON.<key>：

处理手册：{{$event.AnnotationsJSON.runbook_url}}

附加查询：把"现场日志"带进通知

本功能为商业版功能。

日志类告警通常长这样：“5 分钟内 ERROR 日志超过 100 条”。收到通知后，值班同学第一件事往往是打开日志系统，把触发告警的那些日志捞出来看。附加查询就是把这一步自动化：告警触发的同时，系统对当前数据源再执行一次你配置的查询，把查到的原始记录（默认最多 5 条）附加到告警事件里，通知消息中可以直接展示。

只有当规则的数据源类型是日志类（Elasticsearch、Doris、阿里云 SLS、腾讯云 CLS）时，表单里才会出现「附加查询」——如果你在别的规则里找不到它，多半是因为数据源类型不支持。

怎么配

点击「附加查询」旁的 + 号：如果查询统计里只有一条查询，会直接以它为模板克隆一条附加查询；有多条时可以选择以哪条为起点，也可以留空从头新建。

然后按需修改查询条件。查询条件里同样可以引用事件变量，把范围缩小到触发告警的对象。比如 Doris（SQL 必须带 LIMIT 子句）：

SELECT * FROM log_db.error_log WHERE host = '{{$labels.ident}}' ORDER BY ts DESC LIMIT 5

Elasticsearch 则是在过滤条件里引用，比如 host:{{$labels.ident}} AND level:ERROR。

结果去了哪里

查询结果写入告警事件的两个字段：

extra_info：每条记录格式化成 字段名:值 的多行文本，适合直接展示；
extra_info_map：原始键值对数组，适合在模板里按字段取值。

在通知模板中引用：

{{range $event.ExtraInfo}}{{.}}
{{end}}

这样值班同学在 IM 里收到的告警，正文下面就直接跟着几条命中的日志原文，不用登录日志系统就能做初步判断。

常见问题

为什么我的规则里看不到「附加查询」？ 数据源类型不是日志类（Elasticsearch、Doris、阿里云 SLS、腾讯云 CLS）时不会显示；另外它是商业版功能，开源版后端不会执行。

配了附加查询，通知里却没有内容？ 先确认通知模板里引用了 $event.ExtraInfo（或 $event.ExtraInfoMap）；再确认告警触发那一刻查询确实能查到数据——查询结果为空时不会附加任何内容，告警本身照常发送。

附加信息里的变量没有渲染出来？ 引用的标签在事件中不存在时会渲染为空字符串；模板语法本身写错（如花括号不配对）时，对应 Value 会显示 failed to parse annotations，规则照常触发，但要尽快修正。