概述

PagerDuty 是海外最熱門的告警回應 / On-Call 管理平台。夜鶯透過 Events API v2 把告警投遞到 PagerDuty，由後者負責排班、升級、手機 Push / 電話 / 簡訊通知，以及事故全流程追蹤。

夜鶯的 PagerDuty 通知媒介同時使用兩類憑證：

1. API Key（REST API Access Key）——設定在通知媒介上，用途是「在建立通知規則時，夜鶯能透過 PagerDuty REST API 列出帳號下所有 Service」，方便你下拉勾選；
2. 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 端準備

1.1 建立 Service 與 Integration

1. 登入 PagerDuty（https://<your-subdomain>.pagerduty.com）。
2. 進入 Services → Service Directory → New Service，依精靈填寫：
   • 名稱（例如 Nightingale）；
   • Escalation Policy：選一個值班策略；
   • Integration：選 Events API v2；
3. 建立完成後開啟該 Service，在 Integrations 分頁裡可以看到剛建立的 Integration，複製它的 Integration Key（Routing Key，32 位十六進位字串）——你不用親自貼到夜鶯裡，但留個截圖可方便排障。

1.2 建立 REST API Access Key

1. 點擊右上角頭像 → My Profile → User Settings → API Access → Create API User Token。
   • 如果你是帳號管理員，也可以前往 Integrations → API Access Keys → Create New API Key，建立帳號層級的 Key；
   • 權限：唯讀就足夠（夜鶯只需要呼叫 /services / /integrations 列表介面）。
2. 複製產生的 API Key（格式如 y_NbAkKc66ryYTWUXYEu，20 位字元）。

⚠️ 這個 API Key ≠ Integration Key（Routing Key）。

• API Key 的用途是讓夜鶯協助你拉取 Service 清單；
• Routing Key 是每次投遞事件時的「金鑰」，夜鶯會在通知規則裡自動取得並使用。

第二步：在夜鶯新建 PagerDuty 通知媒介

1. 登入夜鶯 → 左側選單 通知 → 通知媒介。

2. 在左側類型面板點擊 PagerDuty（對應 URL /notification-channels/add?ident=pagerduty）。

3. 填寫表單：

   

   區塊	欄位	說明
   基礎設定	名稱	例如 PagerDuty
   PagerDuty 設定	API Key	貼上第一步 1.2 取得的 REST API Access Key
   PagerDuty 設定	代理	夜鶯部署在內網需走代理連線 api.pagerduty.com / events.pagerduty.com 時，請填入 HTTP 代理位址
   PagerDuty 設定	逾時時間	預設 5000 毫秒
   PagerDuty 設定	重試次數	預設 3，網路抖動時會自動重試

4. 點擊 儲存。

PagerDuty 不需要設定 URL 與請求內容——事件投遞位址固定為 https://events.pagerduty.com/v2/enqueue，請求內容結構由夜鶯內部產生（並非使用者自訂的 HTTP 範本）。

第三步：在通知規則裡勾選 Service

1. 左側選單 通知 → 通知規則 → 新增（或編輯既有規則）。

2. 在「通知設定」區塊：

   • 通知媒介：選擇剛才建立的 PagerDuty 媒介；
   • Services：這是一個多選下拉，格式為 服務名稱 / 整合名稱。夜鶯會以媒介裡的 API Key 向 PagerDuty 拉取目前帳號可見的所有 Service + Integration，供你直接勾選；
     • 勾選後，夜鶯會再呼叫一次介面自動取得對應的 Integration Key，後續發送事件時使用；
     • 如果下拉清單是空的：請檢查 API Key 是否有效、網路是否能連線到 api.pagerduty.com（見 Q1）。
   • 適用級別 / 適用時段 / 適用標籤：依需求過濾。

3. 儲存後點擊「通知測試」——PagerDuty 控制台應立刻看到一條 incident，事件恢復後會自動 Resolve。

事件在 PagerDuty 裡的樣貌

夜鶯把事件對應到 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。 若希望第二級也升級，可以在 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 服務節點主要在美國／歐洲。國內雲主機直連延遲高或會丟包，建議：

• 在媒介表單裡設定對外代理（例如公司出海 HTTP 代理）；
• 或在海外部署一個轉發節點。

參考資料

• PagerDuty Events API v2 文件
• PagerDuty · REST API Access Keys
• PagerDuty · Services 與 Integrations 管理