告警消息模板与最佳实践

目标：给出告警消息从生成到触达的统一模板与最佳实践——Alertmanager 通知模板（语法/常用字段/amtool template render 实测）、钉钉/企微 markdown 消息模板、Grafana 通知策略消息模板（实测回显）、告警分级路由与抑制静默配置建议。文中模板均基于 Alertmanager 0.34.1、Grafana 13.2.3 实测。

一、环境信息

二、告警消息统一规范

无论投递到钉钉、企微还是邮件，消息都应包含以下信息（推荐顺序）：

1. 标题：状态 + 告警名，如 【告警】DiskFull / 【恢复】DiskFull（firing/resolved 必须区分，恢复通知与告警同等重要）；
2. 摘要：一句话说明影响，来自 annotations.summary；
3. 详情：级别、实例、当前值、开始时间（来自 labels/annotations）；
4. 分组信息：groupKey 或 commonLabels，说明与哪些告警聚合；
5. 跳转链接：externalURL（Alertmanager UI）/ generatorURL（Prometheus 表达式）。

风格建议：正文用 markdown（钉钉/企微均支持标题/加粗/引用/列表）；时间统一显示服务器本地时区；值统一单位（如磁盘用 %、内存用 GB）。

三、Alertmanager 通知模板

3.1 模板定义与引用

模板文件（如 /etc/alertmanager/notify.tmpl）：

{{ define "notify.text" }}
[{{ .Status | toUpper }}] {{ .CommonLabels.alertname }}
摘要: {{ range .Alerts }}{{ .Annotations.summary }}{{ end }}
实例: {{ range .Alerts }}{{ .Labels.instance }} {{ end }}
{{ end }}

receiver 中引用（text/markdown/webhook 消息体均可）：

receivers:
  - name: "dingtalk-proxy"
    webhook_configs:
      - url: "http://127.0.0.1:19091/convert"
        send_resolved: true
        headers:
          X-Template: '{{ template "notify.text" . }}'

常用字段（v4 payload 对应）：

3.2 amtool template render 实测（离线渲染验证模板）

amtool --alertmanager.url=http://127.0.0.1:9093 template render \
  --template.glob=/etc/alertmanager/notify.tmpl \
  --template.text='{{ template "notify.text" . }}'

实测回显（amtool 用内置测试数据渲染，含 2 条测试告警；.Status 在测试数据中固定为 alertstatus）：

[ALERTSTATUS]  (2 alerts)

💡 说明：--template.glob 与 --template.text 必须同时指定（缺一报 required flag 错误）。render 不连接真实 Alertmanager 数据，适合 CI 里校验模板语法；真实数据可用 --data 传入 v4 payload JSON 复现（v4 payload 结构见本专栏《Alertmanager 对接钉钉-企微 webhook 告警指南》）。

四、钉钉/企微 markdown 消息模板

钉钉消息体（title 为会话列表标题，text 为正文）：

{
  "msgtype": "markdown",
  "markdown": {
    "title": "【告警】DiskFull",
    "text": "### 【告警】DiskFull\n> 磁盘使用率 92%，请及时处理\n\n- 级别: **critical**\n- 实例: db-01\n- 状态: firing\n- 开始时间: 2026-10-08 21:35:00\n- 分组: {}:{alertname=\"DiskFull\"}"
  }
}

企微消息体（无独立 title，正文首行即会话列表摘要）：

{
  "msgtype": "markdown",
  "markdown": {
    "content": "### 【告警】DiskFull\n> 磁盘使用率 92%，请及时处理\n\n- 级别: **critical**\n- 实例: db-01\n- 状态: firing\n- 开始时间: 2026-10-08 21:35:00"
  }
}

💡 消息由 Alertmanager v4 payload 经转换层生成（字段映射见《Alertmanager 对接钉钉-企微 webhook 告警指南》§六），转换层内用 §三 的模板语法渲染即可，无需在 Alertmanager 端重复配置模板。

五、Grafana 通知策略消息模板（实测回显）

Grafana 13.2.3 的通知策略可自定义 message（Go 模板）。实测一条 firing 通知（webhook 接收端原样收到）：

title:   [FIRING:1] PD 集成测试-脉冲波动 (告警测试文件夹)
message: **Firing**

Value: B=9.627660850250736, C=1
Labels:
 - alertname = PD 集成测试-脉冲波动
 - grafana_folder = 告警测试文件夹
Annotations:
Source: http://localhost:3000/alerting/grafana/ag0n7imlc82rkc/view?orgId=1
Silence: http://localhost:3000/alerting/silence/new?alertmanager=grafana&matcher=__alert_rule_uid__%3Dag0n7imlc82rkc&orgId=1

Grafana 通知策略 message 模板示例（与 Alertmanager 语法同源）：

{{ define "grafana.message" -}}
**{{ .Status | title }}**

{{ range .Alerts -}}
Value: {{ range .Values }}{{ . }}{{ end }}
Labels:
{{ range .Labels.SortedPairs }} - {{ .Name }} = {{ .Value }}
{{ end }}
{{ end -}}
{{ end }}

💡 说明：Grafana 通知体字段与 Alertmanager v4 不同（Values/Labels.SortedPairs/Values 等），且恢复事件标题为 [RESOLVED:1]、正文 **Resolved**（本环境已实测）。

六、告警分级与路由最佳实践

6.1 级别定义（建议）

6.2 路由配置建议

route:
  group_by: ["alertname", "instance"]   # 同告警多实例聚合
  group_wait: 30s        # 首批等待（收拢抖动）
  group_interval: 5m     # 组内新告警合并间隔
  repeat_interval: 4h    # 重复提醒频率（配合静默使用）
  receiver: "default"
  routes:
    - matchers: ["severity=critical"]
      receiver: "dingtalk-proxy"
      continue: true
    - matchers: ["severity=warning"]
      receiver: "wecom-proxy"

💡 实测建议值：group_wait 30s 左右（避免瞬时抖动刷屏）、repeat_interval 不小于 1h（否则值班群被重复消息淹没）；continue: true 让 critical 同时走多通道。

七、抑制与静默最佳实践

7.1 抑制（inhibit_rules，实测：critical 抑制同组 warning）

inhibit_rules:
  - source_matchers: ["severity=critical"]   # 有 critical 时
    target_matchers: ["severity=warning"]    # 抑制 warning
    equal: ["alertname"]                     # 同告警名下

实测回显：同一 DiskFull 的 critical 与 warning 同时 firing 时，webhook 只收到 critical 1 条（warning 被抑制）；critical 恢复后 warning 自动解除抑制并发出。

7.2 静默（silence，维护窗口）

# 添加 1 小时静默（返回 UUID）
amtool silence add alertname=DiskFull --duration=1h --comment="维护窗口"

实测回显：

29426024-8011-45fc-b060-cc40e04a52bd

# 查询 / 提前解除（expire 只接受 UUID，不接受 matcher）
amtool silence query
amtool silence expire 29426024-8011-45fc-b060-cc40e04a52bd

💡 最佳实践：发布/维护前用 silence（自动过期，不会忘解除）；紧急抑制用 inhibit（按规则永久生效）；两者结合避免值班群里出现"已知维护"噪音。

八、常见问题

1. 模板语法错误怎么快速发现？

amtool template render 离线校验（§3.2），或 amtool check-config 校验配置整体；Grafana 侧在通知策略页有模板实时预览。

2. 恢复通知要不要发？

要。send_resolved: true（webhook）/ 通知策略勾选恢复，否则值班员无法确认故障闭环；恢复消息标题统一 【恢复】/[RESOLVED]。

3. 告警刷屏怎么治？

三层手段：路由分组聚合（group_by + group_interval）→ 抑制（inhibit_rules）→ 静默（silence 维护窗口）；仍刷屏再检查是否 repeat_interval 过短。

4. 消息里的值/单位不统一？

在模板层统一格式化：数值用 printf "%.1f"，单位拼进模板（如 %/GB）；级别映射中文（critical→严重、warning→警告）。

九、参考链接

• Alertmanager 模板文档：https://prometheus.io/docs/alerting/latest/notification_examples/
• amtool 命令参考：https://prometheus.io/docs/alerting/latest/amtool/
• Grafana 通知策略模板：https://grafana.com/docs/alerting/configure-notifications/template-notifications/
• 对接链路见《Alertmanager 对接钉钉-企微 webhook 告警指南》，机器人接入见《钉钉机器人 webhook 告警接入指南》《企业微信机器人 webhook 告警接入指南》