PagerDuty

通过 PagerDuty Events API v2 把告警推送到 PagerDuty 服务，进行排班、升级与响应管理。

概述

PagerDuty 是海外最流行的告警响应 / On-Call 管理平台。夜莺通过 Events API v2 把告警投递到 PagerDuty，后者负责排班、升级、手机 Push / 电话 / 短信通知以及事故全流程跟踪。

夜莺的 PagerDuty 通知媒介同时使用两类凭证：

API Key（REST API Access Key）——配置在通知媒介上，用途是"在创建通知规则时，夜莺能通过 PagerDuty REST API 列出账号下所有 Service"，方便你下拉勾选；
Integration Key（Routing Key）——属于某个具体的 Service → Integration，是真正把事件投递进 Events API 的鉴权凭证。

夜莺会在你创建通知规则时自动拿第一步的 API Key 去拉取 Integration Key，你只需要从下拉里勾一下目标 Service 即可，不需要手动粘贴 32 位的 routing key。

适用场景：海外团队使用 PagerDuty 做告警排班/升级；或者多云多监控系统希望统一出口到 PagerDuty 复盘统计。
你需要准备：
1. 一个 PagerDuty 账号，并已创建至少一个 Service，其下至少有一个 Events API v2 类型的 Integration；
2. 一个 PagerDuty REST API Key（用户级或账号级）。
整个配置分三步：①在 PagerDuty 创建 Service + Integration + API Key → ②在夜莺新建 PagerDuty 通知媒介 → ③在通知规则里勾选要投递的 Service。

登录 PagerDuty（https://<your-subdomain>.pagerduty.com）。
进入 Services → Service Directory → New Service，按引导填写：
- 名称（例如 Nightingale）；
- Escalation Policy：选一个值班策略；
- Integration：选 Events API v2；
创建完成后打开该 Service，在 Integrations 选项卡里能看到刚创建的 Integration，复制它的 Integration Key（Routing Key，32 位十六进制）——本身你不用贴到夜莺里，但留个截图可以方便排障。

点击右上角头像 → My Profile → User Settings → API Access → Create API User Token。
- 如果你是账号管理员，也可以去 Integrations → API Access Keys → Create New API Key，创建账号级的 Key；
- 权限：只读就够用（夜莺只需要调 /services / /integrations 列表接口）。
复制生成的 API Key（形如 y_NbAkKc66ryYTWUXYEu，20 位字符）。

⚠️ 这个 API Key ≠ Integration Key（Routing Key）。

API Key 的用途是让夜莺帮你拉取 Service 列表；

Routing Key 是每次投递事件时的"密钥"，夜莺会在通知规则里自动替你获取并使用。

填写表单：

PagerDuty 通知媒介表单

区块	字段	说明
基础配置	名称	例如 `PagerDuty`
PagerDuty 配置	API Key	粘贴第一步 1.2 拿到的 REST API Access Key
PagerDuty 配置	代理	夜莺部署在内网需走代理访问 `api.pagerduty.com` / `events.pagerduty.com` 时填 HTTP 代理地址
PagerDuty 配置	超时时间	默认 `5000` 毫秒
PagerDuty 配置	重试次数	默认 `3`，网络抖动会自动重试

PagerDuty 不需要配置 URL 和请求体——事件投递地址固定为 https://events.pagerduty.com/v2/enqueue，请求体结构由夜莺内部生成（不是用户自定义 HTTP 模板）。

夜莺把事件映射为 PagerDuty 字段的规则：

夜莺字段	PagerDuty 字段	说明
非恢复事件	`event_action: trigger`	触发新事故
恢复事件	`event_action: resolve`	解决匹配 `dedup_key` 的事故
`$event.Hash`	`dedup_key`	告警指纹；同指纹触发后再 resolve 即可关闭
`$event.RuleName`	`payload.summary`	事故标题
`$event.Cluster`	`payload.source`	来源
`$event.Severity`	`payload.severity`	`1→critical`、`2→error`、`3→warning`；`critical` 会触发电话升级
`$event.Target`	`payload.component`	组件，方便分派
`$event.TagsJSON` / `AnnotationsJSON` 等	`payload.custom_details`	所有标签、注解、rule_id、rule_note、prom_ql、数据源等原样透传
夜莺事件详情页链接	`links`	Incident 详情页可直接跳回夜莺

Q1：下拉 Services 一直为空？

A：

API Key 错了 / 被禁用：重新去 PagerDuty 生成一个；
网络不通：夜莺服务器要能访问 api.pagerduty.com（国内云主机常常被墙，需要代理）；
权限不够：API Key 对应的用户必须至少能访问 GET /services 与 GET /services/{id}/integrations，默认的 User API Token 就够用；
Service 太多触发分页：夜莺会自动翻页，如果仍然不全，去 PagerDuty 看下是不是部分 Service 设成了 Team 隔离，而 API Key 对应的用户不在该 Team。

Q2：告警触发了但 PagerDuty 里没 Incident？

A：

在夜莺的"通知记录"里看该事件的 Response，常见返回：
- status_code:202, response:{"status":"success",...} → 成功；
- status_code:400, response:{"errors":["Event object is invalid"],...} → 事件体不符（一般是夜莺 bug，报个 issue）；
- status_code:401/403 → routing key 错或 Integration 被禁用。
检查 PagerDuty 里该 Service 的 Integration is Active 是否勾选。

Q3：事件恢复了但 PagerDuty 事故没关？

A：Resolve 是靠 dedup_key 匹配的，夜莺用 $event.Hash 作为 dedup_key。如果：

恢复事件的 Hash 和触发事件的不一致（告警规则 ID 或维度标签发生变化），PagerDuty 找不到对应事故；
触发事件还没被 PagerDuty 处理完，立刻又发 resolve——偶尔会出现"先 resolve 再 trigger"的乱序，夜莺已经按事件时间排序尽量避免。

Q4：严重告警没有走电话升级？

A：PagerDuty 默认只对 severity: critical 做电话/短信升级。夜莺的映射：

夜莺 Severity 1 → critical ✅；
夜莺 Severity 2 → error（邮件/App push）；
夜莺 Severity 3 → warning。如果希望 2 级也升级，可在 PagerDuty 的 Event Rules 里手动把 error 级别的事件 severity 改写为 critical。

Q5：一条通知规则可以同时往多个 Service 送吗？

A：可以。Services 下拉是多选，每个被选中的 Service 都会各自收到一份事件（不同的 routing_key 触发各自 Service 的升级策略）。但注意 PagerDuty 按事件数计费。

Q6：计费？

A：PagerDuty 按许可用户数（Seats）+ 事件用量计费，免费档每月 600 事件。详见 PagerDuty 定价。告警量大时优先在夜莺侧开收敛，再出口。

Q7：国内账号访问 PagerDuty 慢？

A：PagerDuty 服务节点主要在美国/欧洲。国内云主机直连延时高或丢包，建议：