Prometheus 如何编写自定义告警表达式模板

Prometheus 自定义告警模板通过 PromQL 表达式变量化与 labels/annotations 的 Go 模板语法实现逻辑复用，支持阈值、服务名、标签等参数动态注入，结合 recording rule 预计算和 PrometheusRule CRD 达成声明式、可维护的告警管理。

编写 Prometheus 自定义告警表达式模板，核心是把重复、可复用的告警逻辑抽离成带变量的 PromQL 表达式，并配合 labels 和 annotations 中的模板语法（Go text/template）实现动态渲染。它不是写一个“通用函数”，而是构建一套可参数化、易复用、便于维护的规则结构。

明确模板要解决什么问题

直接硬编码如 node_memory_MemFree_bytes / node_memory_MemTotal_bytes < 0.1 虽然能用，但换一台机器、换一个服务、换一个阈值就得改一遍。模板的目标是：一次定义，多处引用，只改参数不改逻辑。

1. 避免相同逻辑在多个 alert 规则里重复写 PromQL
2. 让阈值、持续时间、服务名、实例标签等变成可配置项
3. 使告警信息（summary、description）自动适配当前触发的指标上下文

用 labels + annotations 实现轻量级“模板化”

Prometheus 原生不支持参数化函数式模板，但可通过 标签继承 + 模板变量 达到类似效果。关键在于善用：

{{ $labels. }}（取当前时间序列的标签值）

{{ $value }}（取 expr 计算出的当前样本值）

{{ printf "%.2f" $value }}（格式化数值）

1. 在 labels 中添加业务维度标签，例如：service: "api-gateway"、threshold: "90"，后续可在 Alertmanager 路由或抑制中使用
2. 在 annotations 中用模板动态生成描述，例如：

   description: "{{$labels.instance}} 的 {{$labels.job}} 服务 CPU 使用率达 {{ printf "%.1f" $value }}%，超过阈值 {{$labels.threshold}}%"

3. 注意：labels 和 annotations 中的模板只在告警触发时渲染，不影响 expr 计算

用 recording rule 预计算，简化 expr 复杂度

真正需要“模板化”的 PromQL 逻辑（比如复杂分位数、同比、多指标比值），建议先定义为 Recording Rule（预计算规则），再在告警中直接引用新指标名——这相当于把模板编译成了可复用指标。

1. 在 recording_rules.yml 中定义：

   groups:

   - name: cpu_usage

   rules:

   - record: job:cpu_usage_percent:avg5m

   expr: 100 * (1 - avg by(job, instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])))

2. 告警规则中直接引用：

   expr: job:cpu_usage_percent:avg5m{job="auth-service"} > 85

   这样既解耦了计算与告警，又天然支持按 job、instance 等标签批量应用

结合 PrometheusRule CRD 实现声明式模板管理（K8s 环境）

在 kube-prometheus 或 Prometheus Operator 环境下，推荐用 PrometheusRule 自定义资源统一管理告警模板：

1. 将一类服务（如 Kafka、Redis、MySQL）的通用告警规则封装进一个 PrometheusRule 对象
2. 利用 Jsonnet 或 Kustomize 注入环境变量（如 env: prod、severity: warning），生成不同集群的规则 YAML
3. 示例片段：

   spec:

   groups:

   - name: redis-alerts

   rules:

   - alert: RedisConnectedClientsHigh

   expr: redis_connected_clients{job="redis-exporter"} > {{ .Values.redis.maxConnectedClients | default 10000 }}

   for: 3m