- 快猫星云Flashcat

夜鶯 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 語法

概述