PagerDuty 与 Grafana 告警集成指南

PagerDuty 与 Grafana 告警集成实测：Grafana 13.2.3 创建 PagerDuty 类型 contact point（Integration Key）、alert rule 触发、通知策略路由与本地 webhook 模拟端点的完整通知体复现

PagerDutyPagerDuty告警2026/10/09

PagerDuty 与 Grafana 告警集成指南

目标：实测 Grafana 13.2.3 通过 contact point（PagerDuty 类型） 对接 PagerDuty 的完整链路——contact point 配置、alert rule 触发、通知策略路由；因无真实 PagerDuty 账号，通知体经 Grafana 原生 webhook contact point + 本地模拟端点复现（字段与 PagerDuty 集成同源）。已在 Grafana 13.2.3（端口 3000）实测。

一、环境信息

信息项值
Grafana 版本13.2.3（appVersion 13.2.3）
管理员账号admin（演示环境）
PagerDuty 接入方式Alerting → Contact points → PagerDuty 类型（Integration Key）
模拟演示端点http://127.0.0.1:19090/grafana-pd-webhook
测试数据源grafana-testdata（predictable_pulse 场景）
测试告警规则PD 集成测试-脉冲波动（threshold 判定）

二、集成原理

Grafana Alerting（alert rule 求值）
   │
   ▼
Notification policy（按标签路由）
   │
   ▼
Contact point（PagerDuty 类型：Integration Key / severity / autoResolve）
   │
   ▼
PagerDuty Events API v2（真实接入）
或 本地 webhook 模拟端点（无账号复现，本指南实测）
  • Grafana 原生提供 PagerDuty contact point：填入 PagerDuty Events API v2 集成密钥（Integration Key）即可，触发/恢复自动映射为 trigger/resolve 事件。
  • 本文实测链路用 webhook 类型 contact point 指向本地模拟端点，完整复现 Grafana 发送给 PagerDuty 的通知体；接入真实 PagerDuty 只需把 contact point 换成 PagerDuty 类型并填真实密钥（⚠️ 前置）。

三、前置条件

  • 已部署 Grafana（任意版本 ≥ 11，本指南实测 13.2.3）
  • 启用 Grafana Alerting（默认开启）
  • ⚠️ 前置：真实 PagerDuty 账号中创建 Service 与 Events API v2 集成，取得 Integration Key（32 位）
  • 本机可访问模拟端点（本指南用 http://127.0.0.1:19090 回显服务）

四、创建 PagerDuty contact point

4.1 UI 方式

  1. Alerting → Contact points → Add contact point。
  2. 名称填 PagerDuty-生产，集成类型选 PagerDuty。
  3. 必填字段 Integration Key：填入 PagerDuty Events API v2 集成密钥。
  4. 可选：Severity（默认 critical）、Auto Resolve（恢复自动 resolve，建议开启）、Message（通知模板，如 {{ template "default.message" . }}）。
  5. 保存。

4.2 API 方式（本指南实测）

curl -s -u admin:q1w2e3r4 -H "Content-Type: application/json" \
  -X POST http://127.0.0.1:3000/api/v1/provisioning/contact-points \
  -d '{
    "name": "PagerDuty-Sim",
    "type": "pagerduty",
    "settings": {
      "integrationKey": "11111111111111111111111111111111",
      "severity": "critical",
      "autoResolve": true,
      "message": "{{ template \"default.message\" . }}"
    }
  }'

实测回显：

{"uid":"bg0n7e3gbgj5se","name":"PagerDuty-Sim","type":"pagerduty","settings":{"autoResolve":true,"integrationKey":"[REDACTED]","message":"{{ template \"default.message\" . }}","severity":"critical"},"disableResolveMessage":false}

💡 说明：integrationKey 在返回中被脱敏（[REDACTED]）；Test 按钮会向官方端点发真实请求，无合法 key 会失败——这是正常预期。

4.3 Webhook 模拟 contact point（本地复现用，可选）

无真实 PagerDuty 账号时，用 webhook 类型 contact point 指向本地模拟端点，原样接收 Grafana 推送的通知体（本指南 七、的实测通知体即来自它）。接入真实 PagerDuty 时无需创建此项，直接用 4.2 的 PagerDuty 类型即可：

curl -s -u admin:q1w2e3r4 -H "Content-Type: application/json" \
  -X POST http://127.0.0.1:3000/api/v1/provisioning/contact-points \
  -d '{
    "name": "Webhook-Echo-PD",
    "type": "webhook",
    "settings": {
      "url": "http://127.0.0.1:19090/grafana-pd-webhook",
      "httpMethod": "POST"
    }
  }'

💡 说明：返回被创建的 webhook contact point（含 uid）；本指南 六、通知策略的 receiver 即名为 Webhook-Echo-PD 的此 contact point。

五、创建触发用告警规则（本指南实测）

用内置 testdata 数据源构造一个周期性触发的规则（便于复现）：

💡 说明：下方命令中 folderUID 取第 2 步 POST /api/folders 返回 JSON 的 uid，datasourceUid 取第 1 步 POST /api/datasources 返回 JSON 的 uid，替换两处 <...> 占位符；二者均为本机 Grafana 动态分配的 UID，无法硬编码。

# 1. 创建 testdata 数据源
curl -s -u admin:q1w2e3r4 -H "Content-Type: application/json" -X POST http://127.0.0.1:3000/api/datasources \
  -d '{"name":"TestData-DS","type":"testdata","access":"proxy","isDefault":false}'
# 2. 创建文件夹
curl -s -u admin:q1w2e3r4 -H "Content-Type: application/json" -X POST http://127.0.0.1:3000/api/folders \
  -d '{"title":"告警测试文件夹"}'
# 3. 创建告警规则（predictable_pulse 方波：值为 1 时超过阈值 0 → firing）
curl -s -u admin:q1w2e3r4 -H "Content-Type: application/json" -X POST http://127.0.0.1:3000/api/v1/provisioning/alert-rules \
  -d '{
    "title": "PD 集成测试-脉冲波动",
    "folderUID": "<上一步返回的 folder uid>",
    "ruleGroup": "pd-test-group",
    "condition": "C",
    "data": [
      {"refId": "A", "relativeTimeRange": {"from": 600, "to": 0}, "datasourceUid": "<testdata uid>",
       "model": {"refId": "A", "scenario": "predictable_pulse", "startValue": 1, "step": 60, "timeStep": 60, "pulseCount": 0,
         "pulseWave": {"fill": false, "initial": 0, "step": 1, "timeStep": 60, "unit": 1, "onCount": 2, "offCount": 2}}},
      {"refId": "B", "relativeTimeRange": {"from": 600, "to": 0}, "datasourceUid": "__expr__",
       "model": {"refId": "B", "type": "reduce", "expression": "A", "reducer": "last"}},
      {"refId": "C", "relativeTimeRange": {"from": 600, "to": 0}, "datasourceUid": "__expr__",
       "model": {"refId": "C", "type": "threshold", "expression": "B", "conditions": [{"evaluator": {"type": "gt", "params": [0]}}]}}
    ],
    "noDataState": "NoData", "execErrState": "Error", "for": "0s", "isPaused": false
  }'

💡 说明：规则三步骤结构固定为 查询（A）→ 归约（B，reduce）→ 阈值（C，threshold），condition 指向 C。实测中若省略 reduce 步骤，求值报 looks like time series data, only reduced data can be alerted on——这是高频踩坑点。

六、通知策略路由

把默认通知策略的 receiver 指向目标 contact point（webhook 模拟版，本指南实测）：

curl -s -u admin:q1w2e3r4 -H "Content-Type: application/json" -X PUT http://127.0.0.1:3000/api/v1/provisioning/policies \
  -d '{
    "receiver": "Webhook-Echo-PD",
    "group_by": ["alertname"],
    "group_wait": "1s",
    "group_interval": "10s",
    "repeat_interval": "30s"
  }'

实测回显：

{"message":"policies updated"}

⚠️ 注意：真实接入时把 receiver 换成上一步创建的 PagerDuty contact point 名（如 PagerDuty-生产）。策略支持按标签（如 severity=critical）路由到不同 contact point。

七、告警触发与通知体（实测）

规则进入 firing 后，Grafana 向接收方推送完整通知。模拟端点原样接收的 firing 通知体（实测回显，webhook 类型 contact point 的 v1 协议）：

{
  "receiver": "Webhook-Echo-PD",
  "status": "firing",
  "alerts": [
    {
      "status": "firing",
      "labels": {"alertname": "PD 集成测试-脉冲波动", "grafana_folder": "告警测试文件夹"},
      "annotations": {},
      "startsAt": "2026-10-08T21:15:00Z",
      "endsAt": "0001-01-01T00:00:00Z",
      "generatorURL": "http://localhost:3000/alerting/grafana/ag0n7imlc82rkc/view?orgId=1",
      "fingerprint": "4d1693999e44c007",
      "silenceURL": "http://localhost:3000/alerting/silence/new?alertmanager=grafana&matcher=__alert_rule_uid__%3Dag0n7imlc82rkc&orgId=1",
      "ruleUID": "ag0n7imlc82rkc",
      "values": {"B": 7.597229904894781, "C": 1},
      "valueString": "[ var='B' ... value=7.597229904894781 ], [ var='C' ... value=1 ]",
      "orgId": 1
    }
  ],
  "groupLabels": {"alertname": "PD 集成测试-脉冲波动"},
  "commonLabels": {"alertname": "PD 集成测试-脉冲波动", "grafana_folder": "告警测试文件夹"},
  "commonAnnotations": {},
  "externalURL": "http://localhost:3000/",
  "appVersion": "13.2.3",
  "version": "1",
  "groupKey": "{}:{alertname=\"PD 集成测试-脉冲波动\"}",
  "truncatedAlerts": 0,
  "title": "[FIRING:1] PD 集成测试-脉冲波动 (告警测试文件夹)",
  "state": "alerting",
  "message": "**Firing**\n\nValue: B=7.597229904894781, C=1\nLabels:\n - alertname = PD 集成测试-脉冲波动\n - grafana_folder = 告警测试文件夹\nAnnotations:\nSource: http://localhost:3000/alerting/grafana/ag0n7imlc82rkc/view?orgId=1\nSilence: http://localhost:3000/alerting/silence/new?alertmanager=grafana&matcher=__alert_rule_uid__%3Dag0n7imlc82rkc&orgId=1\n"
}

💡 说明：PagerDuty 类型 contact point 发送的是 Events API v2 事件（event_action=trigger，与 Alertmanager 推送格式一致，见《PagerDuty 与 Prometheus-Alertmanager 集成指南》）；本 webhook 演示展示了 Grafana 告警的全部上下文（labels/values/URL），真实接入时这些字段映射进 PagerDuty 的 payload.custom_details。

八、验证

# 1. 规则状态（应为 firing / Alerting 实例）
curl -s -u admin:q1w2e3r4 "http://127.0.0.1:3000/api/prometheus/grafana/api/v1/rules" | grep -E '"state"|"name"' | head -6

# 2. contact point 列表
curl -s -u admin:q1w2e3r4 http://127.0.0.1:3000/api/v1/provisioning/contact-points | python3 -m json.tool | head -20

实测规则状态回显：

"state": "firing"

💡 说明：告警在 Grafana Alerting → Alert rules 页可见 Alerting 状态；通知发出后可在 PagerDuty 侧看到新 incident（真实账号）。

九、常见问题

Q1：contact point 测试（Test）报错？

PagerDuty 类型会真实调用官方端点，无合法 Integration Key 必然失败（实测为官方契约拒绝）。联调阶段改用 webhook 类型 + 本地端点复现通知体（见 四、4.3）。

Q2：规则求值报 looks like time series data？

数据流缺少归约步骤：查询后必须先 reduce 再 threshold（见 五、 创建告警规则说明）。

Q3：通知没有发到 PagerDuty？

检查 notification policy 的 receiver 是否指向该 contact point；contact point 名与策略 receiver 必须完全一致。

Q4：恢复事件未自动关闭 incident？

contact point 需开启 Auto Resolve（autoResolve: true），且规则结束（firing→正常/NoData）后 Grafana 才会发 resolve。

十、参考链接