4. PagerDuty 集成配置：监控系统与 Webhook/API 对接

将监控系统（Prometheus、Datadog、Zabbix）与 PagerDuty 集成，是构建可观测性事件响应链路的核心环节。本章聚焦三种主流监控工具的集成配置方法，涵盖 Webhook 推送、API 驱动、以及事件去重与路由策略。

4.1 集成架构总览

PagerDuty 通过 Event API（v2）接收外部监控系统的事件。监控系统作为事件源，将告警封装为 JSON 负载，通过 Webhook 或直接 API 调用发送至 PagerDuty 的集成端点。PagerDuty 根据集成密钥（Integration Key）将事件路由到对应的服务，触发通知、升级策略和响应流程。

4.2 Prometheus + Alertmanager → PagerDuty

Prometheus 通过 Alertmanager 的 Webhook Receiver 将告警转发至 PagerDuty。推荐使用 PagerDuty 官方提供的 pagerduty-receiver 或直接配置 webhook_configs。

4.2.1 配置步骤

1. 在 PagerDuty 创建服务：进入 Services → New Service，输入服务名称，选择 "Prometheus" 作为集成类型，复制生成的 Integration Key。
2. 配置 Alertmanager：编辑 alertmanager.yml，添加 PagerDuty 接收器。

# alertmanager.yml 示例
route:
  receiver: 'pagerduty-critical'
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h

receivers:
- name: 'pagerduty-critical'
  webhook_configs:
  - url: 'https://events.pagerduty.com/v2/enqueue'
    send_resolved: true
    http_config:
      headers:
        Content-Type: application/json
    # 使用模板生成事件负载
    body: |
      {
        "routing_key": "YOUR_INTEGRATION_KEY",
        "event_action": "trigger",
        "payload": {
          "summary": "{{ .GroupLabels.alertname }}",
          "severity": "critical",
          "source": "{{ .GroupLabels.instance }}",
          "custom_details": {
            "description": "{{ .CommonAnnotations.description }}",
            "runbook_url": "{{ .CommonAnnotations.runbook_url }}"
          }
        }
      }

4.3 Datadog → PagerDuty 集成

Datadog 提供原生 PagerDuty 集成，支持自动创建/更新/关闭事件。集成方式分为 OAuth 应用集成 和 Webhook 手动集成 两种。

4.3.1 OAuth 集成（推荐）

4.3.2 Webhook 手动集成

当 OAuth 不可用时，可使用 Datadog Webhook 集成直接调用 PagerDuty Event API。

# Datadog Webhook 配置示例
name: pagerduty-webhook
url: https://events.pagerduty.com/v2/enqueue
payload:
  routing_key: "YOUR_INTEGRATION_KEY"
  event_action: "trigger"
  payload:
    summary: "$EVENT_TITLE"
    severity: "$SEVERITY"
    source: "$HOSTNAME"
    custom_details:
      monitor_id: "$MONITOR_ID"
      monitor_url: "$MONITOR_URL"
      tags: "$TAGS"
headers:
  Content-Type: application/json

4.4 Zabbix → PagerDuty 集成

Zabbix 通过 Action + Script 或 Webhook 媒体类型（Zabbix 5.0+）与 PagerDuty 对接。推荐使用 Zabbix 内置的 Webhook 媒体类型，无需额外脚本。

4.4.1 使用 Zabbix Webhook 媒体类型

1. 导入媒体类型：Administration → Media types → Import，导入 PagerDuty 官方提供的 XML 模板。
2. 配置参数：设置 pagerduty_routing_key、pagerduty_event_source、pagerduty_severity。
3. 关联用户：将媒体类型分配给 Zabbix 用户，并填入用户的 PagerDuty 集成密钥。
4. 配置 Action：在 Action 中设置条件，触发时发送消息到 PagerDuty。

4.4.2 传统 Script 方式（Zabbix 4.x）

#!/bin/bash
# pagerduty_alert.sh - Zabbix AlertScript
INTEGRATION_KEY="$1"
EVENT_SUMMARY="$2"
SEVERITY="$3"
HOST="$4"

curl -X POST https://events.pagerduty.com/v2/enqueue \
  -H "Content-Type: application/json" \
  -d '{
    "routing_key": "'"$INTEGRATION_KEY"'",
    "event_action": "trigger",
    "payload": {
      "summary": "'"$EVENT_SUMMARY"'",
      "severity": "'"$SEVERITY"'",
      "source": "'"$HOST"'"
    }
  }'

4.5 事件去重与路由策略

PagerDuty 的 Deduplication Key（dedup_key）是控制事件去重和关联的核心字段。相同 dedup_key 的事件会被 PagerDuty 视为同一事件的不同状态更新，避免重复告警。

4.5.1 去重键生成策略

4.6 集成验证与故障排查

# 手动测试 PagerDuty Event API
curl -X POST https://events.pagerduty.com/v2/enqueue \
  -H "Content-Type: application/json" \
  -d '{
    "routing_key": "YOUR_INTEGRATION_KEY",
    "event_action": "trigger",
    "payload": {
      "summary": "Test alert from curl",
      "severity": "info",
      "source": "testing-tool"
    }
  }'
# 预期响应：{"status":"success","message":"Event processed","dedup_key":"..."}

4.7 安全与密钥管理

集成密钥（Integration Key）是敏感凭证，泄露后可能导致恶意告警或服务中断。建议遵循以下安全实践：

• 密钥轮换：每 90 天在 PagerDuty 服务设置中重新生成集成密钥。
• 最小权限：每个监控系统使用独立的集成密钥，避免跨服务复用。
• 加密存储：在配置管理工具（Ansible、Terraform）中使用加密变量或 Vault 存储密钥。
• 审计日志：启用 PagerDuty 审计日志，监控集成密钥的使用情况。