事件字段（$event）详解

夜莺 v9 消息模板中 $event（告警事件 AlertCurEvent）的全部字段说明：身份、规则、级别、触发值、时间、标签、注解、通知配置、目标主机等，附模板写法与常用片段。

概述

写消息模板时，你引用的 $event 就是夜莺内部的告警事件结构体 AlertCurEvent（源码 models/alert_cur_event.go）。一条告警从触发、聚合到发送，都带着这个对象，模板里能拿到它的所有字段。

本文把这些字段按用途分组列出，方便你写模板时按需取用。

两种字段写法，别搞混

同一个字段有两个名字，用在不同地方：

场景	写法	例子
消息模板 / Go template（本文重点）	Go 字段名（驼峰）	`{{$event.RuleName}}`
Callback / Webhook 转发的原始事件 JSON	JSON 字段名（下划线）	`rule_name`

⚠️ 模板里必须用 Go 字段名 $event.RuleName，写成 $event.rule_name 取不到值。下面每个表格都同时给出两个名字。

另外，带 json:"-" 标记的字段（如 Tags、Annotations）不会出现在 Webhook 的 JSON 里，但在模板中仍可用 Go 字段名访问。

模板里可用的顶层变量

消息模板渲染时，平台预置了几个快捷变量（见源码 models/message_tpl.go 的 getDefs）：

变量	等价于	说明
`$events`	`.events`	本次通知包含的所有事件（聚合通知时是多条），可 `range` 遍历
`$event`	`index $events 0`	第一条事件（绝大多数模板只用这个）
`$labels`	`$event.TagsMap`	标签 map 的别名
`$value`	`$event.TriggerValue`	触发值的别名
`.domain`	站点地址	平台注入的访问地址，用于拼详情/屏蔽链接

聚合通知（一条消息里带多条告警）请用 {{range $events}}...{{end}}；$event 只是其中第一条。

一、身份与数据源

模板写法	JSON 字段	类型	说明
`$event.Id`	`id`	int64	事件 ID，拼详情链接用：`{{.domain}}/alert-his-events/{{$event.Id}}`
`$event.Cate`	`cate`	string	数据源类型：`prometheus` / `host` / `mysql` / `elasticsearch` / `loki` 等。内置模板靠它判断要不要显示"查看曲线"链接（`{{if eq $event.Cate "prometheus"}}`）
`$event.Cluster`	`cluster`	string	数据源名称
`$event.DatasourceId`	`datasource_id`	int64	数据源 ID
`$event.GroupId`	`group_id`	int64	业务组 ID
`$event.GroupName`	`group_name`	string	业务组名称
`$event.Hash`	`hash`	string	事件唯一标识（`rule_id` + 标签向量），同一规则同一组标签的事件 hash 相同，用于去重/聚合
`$event.RuleHash`	`rule_hash`	string	规则 hash

二、规则信息

模板写法	JSON 字段	类型	说明
`$event.RuleName`	`rule_name`	string	规则名称（最常用）
`$event.RuleNote`	`rule_note`	string	规则备注
`$event.RuleId`	`rule_id`	int64	规则 ID
`$event.RuleProd`	`rule_prod`	string	监控类型：`metric` / `host` / `anomaly` / `loki` 等
`$event.RuleAlgo`	`rule_algo`	string	算法（智能检测时有值，阈值告警为空）
`$event.PromQl`	`prom_ql`	string	触发该事件的查询语句
`$event.PromForDuration`	`prom_for_duration`	int	持续时长 `for`（秒）
`$event.PromEvalInterval`	`prom_eval_interval`	int	执行频率（秒）
`$event.RunbookUrl`	`runbook_url`	string	预案 / 排障手册链接
`$event.RuleConfigJson`	`rule_config`	object	解析后的规则完整配置对象
`$event.RuleConfig`	（不输出，`json:"-"`）	string	规则配置的原始 JSON 串

三、级别与状态

模板写法	JSON 字段	类型	说明
`$event.Severity`	`severity`	int	告警级别：1 = Emergency 紧急 / 2 = Warning 警告 / 3 = Notice 通知（数字越小越严重）
`$event.IsRecovered`	`is_recovered`	bool	是否恢复事件（`true`=恢复，`false`=触发）★最常用于条件分支、分颜色
`$event.NotifyRecovered`	`notify_recovered`	int	规则是否开启恢复通知（1=开）
`$event.NotifyCurNumber`	`notify_cur_number`	int	这是第几次通知（重复提醒计数）
`$event.Status`	`status`	int	事件状态
`$event.Claimant`	`claimant`	string	认领人

四、触发值与时间

时间字段都是 Unix 秒，模板里用 {{timeformat $event.XxxTime}} 转成可读时间。

模板写法	JSON 字段	类型	说明
`$event.TriggerValue`	`trigger_value`	string	触发时的值（`$value` 是它的别名）
`$event.TriggerValues`	`trigger_values`	string	多查询场景下的触发值串
`$event.TriggerValuesJson.ValuesWithUnit`	`trigger_values_json`	map	带单位的触发值：key 是查询 ref，value 含 `Value` / `Unit` / `Text` / `Stat`。取格式化文本用 `.Text`
`$event.TriggerTime`	`trigger_time`	int64	触发时间戳
`$event.FirstTriggerTime`	`first_trigger_time`	int64	连续告警的首次触发时间（算"已持续多久"用）
`$event.FirstEvalTime`	`first_eval_time`	int64	首次检测到异常的时间
`$event.LastEvalTime`	`last_eval_time`	int64	最近一次评估时间；恢复事件里即为恢复时间
`$event.LastSentTime`	`last_sent_time`	int64	上次通知发送时间
`$event.RecoverTime`	`recover_time`	int64	恢复时间（恢复事件）

五、标签与注解

模板写法	JSON 字段	类型	说明
`$event.TagsMap`	`tags_map`	map[string]string	标签 map ★最常用，如 `$event.TagsMap.instance`；`$labels` 是它的别名
`$event.TagsJSON`	`tags`	[]string	标签数组 `["k=v", ...]`，可 `range` 遍历
`$event.OriginalTagsJSON`	`original_tags`	[]string	relabel 之前的原始标签
`$event.AnnotationsJSON`	`annotations`	map[string]string	注解 map，如 `$event.AnnotationsJSON.summary`
`$event.Tags` / `$event.Annotations` / `$event.OriginalTags`	（`json:"-"`）	string	DB 存储形态，模板里一般不直接用

六、通知配置

这些来自规则配置，部分是旧版通知字段；新版（基于通知规则）的环境主要看 NotifyRuleId / NotifyRuleName。

模板写法	JSON 字段	类型	说明
`$event.NotifyRuleId`	`notify_rule_id`	int64	命中的通知规则 ID（新版）
`$event.NotifyRuleName`	`notify_rule_name`	string	命中的通知规则名（新版）
`$event.NotifyRuleIds`	`notify_rule_ids`	[]int64	关联的通知规则 ID 列表
`$event.NotifyVersion`	`notify_version`	int	0=旧版，1=新版通知
`$event.CallbacksJSON`	`callbacks`	[]string	回调地址
`$event.NotifyChannelsJSON`	`notify_channels`	[]string	通知媒介（旧版）
`$event.NotifyGroupsJSON`	`notify_groups`	[]string	通知组 ID（旧版）
`$event.NotifyGroupsObj`	`notify_groups_obj`	[]UserGroup	通知组对象
`$event.NotifyUsersObj`	`notify_users_obj`	[]User	通知用户对象

七、目标主机

模板写法	JSON 字段	类型	说明
`$event.TargetIdent`	`target_ident`	string	监控对象标识（主机 ident）
`$event.TargetNote`	`target_note`	string	对象备注
`$event.Target`	`target`	object	完整对象信息，含 `HostIp` / `OS` / `CpuNum` / `MemUtil` / `GroupNames` 等，如 `$event.Target.HostIp`

八、高级 / 扩展字段

模板写法	JSON 字段	类型	说明
`$event.RecoverConfig`	`recover_config`	object	恢复判定配置，含 `JudgeType` / `RecoverExp`
`$event.SubRuleId`	`sub_rule_id`	int64	子规则 ID
`$event.ExtraInfo`	`extra_info`	[]string	附加信息
`$event.ExtraInfoMap`	`extra_info_map`	[]map[string]string	结构化附加信息
`$event.ExtraConfig`	`extra_config`	object	附加配置
`$event.ShotImageBase64`	`shot_image_base64`	map[string]string	灭火图 / 曲线快照 base64（卡片配图用）

常用片段

标题：恢复/触发 + 级别 + 规则名

{{if $event.IsRecovered}}💚 已恢复{{else}}💔 S{{$event.Severity}} 告警{{end}}: {{$event.RuleName}}

正文：按级别分颜色（钉钉 markdown）

#### {{if $event.IsRecovered}}<font color="#008800">💚 {{$event.RuleName}}</font>{{else}}<font color="#FF0000">💔 {{$event.RuleName}}</font>{{end}}
- **级别**: {{if eq $event.Severity 1}}一级(紧急){{else if eq $event.Severity 2}}二级(警告){{else}}三级(通知){{end}}
- **业务组**: {{$event.GroupName}}
{{- if $event.RuleNote}}
- **备注**: {{$event.RuleNote}}
{{- end}}
{{- if not $event.IsRecovered}}
- **触发值**: {{$event.TriggerValue}}
- **触发时间**: {{timeformat $event.TriggerTime}}
{{- else}}
- **恢复时间**: {{timeformat $event.LastEvalTime}}
{{- end}}

已持续时长

{{$duration := sub now.Unix $event.FirstTriggerTime}}{{if $event.IsRecovered}}{{$duration = sub $event.LastEvalTime $event.FirstTriggerTime}}{{end}}已持续: {{$duration}} 秒

遍历标签

{{- range $key, $val := $event.TagsMap}}
- {{$key}}: {{$val}}
{{- end}}

取单个标签（带判空，避免 `<no value>`）

机器: {{if $event.TagsMap.instance}}{{$event.TagsMap.instance}}{{else}}未知{{end}}

详情 / 屏蔽 / 看图链接

[事件详情]({{.domain}}/share/alert-his-events/{{$event.Id}}) | [屏蔽1小时]({{.domain}}/alert-mutes/add?__event_id={{$event.Id}}){{if eq $event.Cate "prometheus"}} | [查看曲线]({{.domain}}/metric/explorer?__event_id={{$event.Id}}&mode=graph){{end}}

聚合通知：遍历多条事件

本次共 {{len $events}} 条告警：
{{range $i, $e := $events}}{{add $i 1}}. {{$e.RuleName}} | {{$e.TagsMap.instance}} | {{$e.TriggerValue}}
{{end}}

注意事项

写错名字会取空：模板里用 Go 字段名（$event.RuleName），不是 JSON 名（rule_name）。
缺失字段渲染成 <no value>：取标签/注解时建议加 {{if ...}} 判空，或用标签词表注入默认值。
时间要格式化：所有 *Time 字段是 Unix 秒，直接输出是一串数字，用 {{timeformat ...}} 转可读时间。
$event 只是第一条：聚合通知场景请用 $events 遍历。
字段缓存：改完模板后等 10~30 秒再触发，模板有几秒缓存。

参考资料

消息模板 — 模板的创建、字段标识、克隆改造
模板函数介绍 — timeformat / sub / formatDecimal 等可用函数
models/alert_cur_event.go — 事件结构体源码（字段以此为准）
Go template 语法

概述