PagerDuty 与 Prometheus-Alertmanager 集成指南

PagerDuty 与 Prometheus-Alertmanager 集成实测：Alertmanager pagerduty_configs 配置（routing_key/send_resolved）、trigger/resolve 事件格式、本地模拟端点复现完整事件体、Web UI 确认

PagerDutyPagerDutyAlertmanager告警2026/10/09

PagerDuty 与 Prometheus-Alertmanager 集成指南

目标：实测 Alertmanager 0.34.1 通过内置 pagerduty_configs 对接 PagerDuty Events API v2 的完整链路——配置、触发（trigger）与解决（resolve）事件格式、Web UI 确认；因无真实 PagerDuty 账号，事件体经本地模拟端点复现（与官方端点协议一致）。已在 Alertmanager 0.34.1 服务器实测。

一、环境信息

信息项值
Alertmanager 版本0.34.1
PagerDuty 接入方式Events API v2（pagerduty_configs）
官方事件端点https://events.pagerduty.com/v2/enqueue
模拟演示端点http://127.0.0.1:19090/pd-events-v2（本地回显）
测试告警alertname=DatabaseDown, severity=critical, instance=pg-01

💡 说明：本文所有事件体由 Alertmanager 真实推送、模拟端点原样接收（HTTP POST JSON），字段与官方 Events API v2 完全一致；仅把官方 URL 替换为本地端点以便无账号复现。

二、集成原理

Prometheus ──push──> Alertmanager ──pagerduty_configs──> PagerDuty Events API v2
                              │
                              └─ 本指南：指向本地模拟端点，复现完整事件体
  • Alertmanager 原生支持 PagerDuty：告警触发发 event_action=trigger，恢复（send_resolved: true）发 event_action=resolve，两者共用按告警指纹生成的 dedup_key，PagerDuty 据此将触发/解决关联为同一 incident。
  • 除 webhook 网关自建外，这是推荐程度最高的官方原生集成路径（无需自研转发脚本）。

三、前置条件

  • 已部署 Alertmanager 0.34.1（见《Ubuntu 22.04 安装 Alertmanager 指南》）
  • ⚠️ 前置：真实 PagerDuty 账号中创建 Service 与 Events API v2 集成，取得 32 位 routing key，写入本机环境变量供注入：export PD_ROUTING_KEY=$(cat /etc/alertmanager/pd_routing_key)（无账号时可先把事件端点指向本地模拟端点走通全链路）
  • 已安装 curl / amtool

四、配置 Alertmanager

在 alertmanager.yml 的 global 覆盖事件端点（真实接入时删除此行使用官方默认端点），并新增 PagerDuty receiver：

global:
  pagerduty_url: "http://127.0.0.1:19090/pd-events-v2"   # 演示用；真实接入删除此行

route:
  group_by: ["alertname"]
  group_wait: 1s
  group_interval: 5s
  repeat_interval: 1m
  receiver: "pd"

receivers:
  - name: "pd"
    pagerduty_configs:
      - routing_key: "${PD_ROUTING_KEY}"   # 真实 routing key 经环境变量注入
        severity: "critical"
        send_resolved: true

配置校验：

amtool check-config /etc/alertmanager/alertmanager.yml

实测回显：

Checking '/etc/alertmanager/alertmanager.yml'  SUCCESS
Found:
 - global config
 - route
 - 0 inhibit rules
 - 1 receivers
 - 0 templates

⚠️ 注意：v2 协议必须用 routing_key（v1 的 service_key 已废弃）；severity 会覆盖告警自身级别（可选 inherited/critical/error/warning/info）；send_resolved: true 才会在恢复时发 resolve 事件。

启动（或热加载）后验证：

systemctl restart alertmanager
curl -s http://127.0.0.1:9093/-/ready

OK

五、触发事件（trigger）实测

注入测试告警：

amtool --alertmanager.url=http://127.0.0.1:9093 alert add alertname=DatabaseDown severity=critical instance=pg-01
amtool --alertmanager.url=http://127.0.0.1:9093 alert query

模拟端点原样接收的 trigger 事件体（实测回显）：

{
  "routing_key": "${PD_ROUTING_KEY}",
  "dedup_key": "3821961fee9ba99325d36ab961f8d3d09611051672e0d48ae0196730938bfd49",
  "event_action": "trigger",
  "payload": {
    "summary": "[FIRING:1] DatabaseDown (pg-01 critical)",
    "source": "Alertmanager",
    "severity": "critical",
    "custom_details": {
      "firing": [
        {
          "annotations": {},
          "endsAt": "0001-01-01T00:00:00Z",
          "fingerprint": "b4cc091508cdf523",
          "generatorURL": "",
          "labels": {"alertname": "DatabaseDown", "instance": "pg-01", "severity": "critical"},
          "startsAt": "2026-10-08T21:09:20.518757106Z",
          "status": "firing"
        }
      ],
      "num_firing": 1,
      "num_resolved": 0,
      "resolved": []
    }
  },
  "client": "Alertmanager",
  "client_url": "http://alertmanager-srv:9095/#/alerts?receiver=pd"
}

💡 说明：dedup_key 是告警指纹的哈希，同一告警恢复时保持不变；payload.summary 默认格式 [FIRING:1] <alertname> (<labels>)，custom_details.firing 携带完整告警明细。真实接入时把 URL 指回官方端点（删除 global 覆盖行），返回 {"status":"success","message":"Event processed"}。

六、解决事件（resolve）实测

告警恢复（此处以告警过期为例，生产为 Prometheus 推送 resolved 状态）后，模拟端点收到 resolve 事件体（实测回显）：

{
  "routing_key": "${PD_ROUTING_KEY}",
  "dedup_key": "3821961fee9ba99325d36ab961f8d3d09611051672e0d48ae0196730938bfd49",
  "event_action": "resolve",
  "payload": {
    "summary": "[RESOLVED] DatabaseDown (pg-01 critical)",
    "source": "Alertmanager",
    "severity": "critical",
    "custom_details": {
      "firing": [],
      "num_firing": 0,
      "num_resolved": 1,
      "resolved": [
        {
          "annotations": {},
          "endsAt": "2026-10-08T21:14:34.972148459Z",
          "fingerprint": "b4cc091508cdf523",
          "generatorURL": "",
          "labels": {"alertname": "DatabaseDown", "instance": "pg-01", "severity": "critical"},
          "startsAt": "2026-10-08T21:09:34.972148459Z",
          "status": "resolved"
        }
      ]
    }
  },
  "client": "Alertmanager",
  "client_url": "http://alertmanager-srv:9095/#/alerts?receiver=pd"
}

💡 说明：trigger 与 resolve 的 dedup_key 完全一致，PagerDuty 会自动关闭对应 incident，无需人工确认；若未开 send_resolved，恢复事件不会发出，incident 将一直打开直到人工解决。

七、Web UI 与事件确认

  • Alertmanager Web UI（http://<IP>:9093）→ Status → Configuration 可确认 receiver 生效；Alerts 页查看告警状态。
  • 事件是否发出：查看 Alertmanager 日志（level=INFO msg="Notify success" 或错误行），或模拟端点统计 POST 次数：
grep -c "pd-events-v2" /tmp/webhook_echo.log

💡 说明：若模拟端点返回非 2xx，Alertmanager 会按退避重试（见 FAQ）。

八、常见问题

Q1：事件发出但 PagerDuty 侧无 incident？

routing_key 错误或集成类型不是 Events API v2；官方端点返回 Invalid routing key 即 key 无效。

Q2：告警恢复后 incident 不自动关闭？

send_resolved: true 未开，或恢复事件与触发事件的 dedup_key 不一致（同告警同节点应一致；跨节点集群需先确认通知状态已同步，见《高可用-集群部署 专项篇》）。

Q3：官方端点请求失败，日志报超时/5xx？

检查出网策略（events.pagerduty.com:443）；global.http_config 可配置代理：http_config: proxy_url: "http://proxy:3128"。

Q4：想自定义事件摘要/字段？

用通知模板覆盖 summary：pagerduty_configs: - summary: '{{ template "pd.summary" . }}'，模板文件注册到 templates:（见《告警消息模板与最佳实践》）。

九、参考链接