文案要说清三件事
一条合格的告警文案在第一时间回答三个问题：什么对象出问题、具体是什么现象、下一步去哪里。落地方式是把结论放进 summary，把数据与影响范围放进 description，把看板与 runbook 链接放进注释字段，收件人不需要再去翻资料就能开始处置。
三要素分工
| summary | 对象 + 现象 + 关键数值，一句话给结论 |
|---|---|
| description | 影响范围、涉及实例数与持续时间 |
| dashboard_url | 直达相关看板，省去搜索 |
| runbook_url | 处置步骤与联系路径 |
annotations 示例
annotations 示例
annotations:
summary: "order-svc 支付错误率 12%（阈值 5%），用户支付失败"
description: "近 10 分钟 5xx 占比 12%，影响下单支付环节，涉及 3/12 实例"
dashboard_url: "https://grafana.example.com/d/order-svc"
runbook_url: "https://wiki.example.com/runbook/order-svc-error"
value: "{{ $value | humanizePercentage }}"常见写法对比
| 写法 | 问题 | 改进 |
|---|---|---|
| HighErrorRate exceeded | 只说规则名，接收者要自己翻译 | 写清服务、指标与当前值 |
| 只给一个数字 | 缺少影响范围与判断依据 | 补充实例数、时间窗与阈值 |
| 没有链接 | 处置需要先找资料 | 附看板与 runbook 地址 |
| 阈值写死在描述里 | 调参后文案与实际不符 | 引用规则中的阈值变量 |
撰写要点
- 把最重要的结论放在标题，接收者在通知栏里就能判断优先级
- 描述里写清时间窗口与统计范围，避免“多久内多少”含糊不清
- 模板中引用的标签必须保证存在，缺失时渲染成空值会让消息只剩一半
- 同一类告警沿用统一句式，值班扫一眼就能比较不同服务的量级
避免只发“HighErrorRate exceeded”这样的标题：接收者需要自行翻译、自行找资料，处置时间被白白拖长。
句式模板
- 服务类故障：服务名 + 现象 + 当前值 + 影响范围 + 涉及实例数
- 资源类告警：节点或目录 + 使用率 + 剩余空间 + 预计耗尽时间
- 数据类告警：数据源或任务名 + 延迟时长 + 最近一次成功时间
- 每条文案都能独立读懂，不依赖上下文或前一条消息
- 数值带单位与口径，避免只给裸数字让接收者自行猜测量级