nathandeamer/prometheus-alerts-to-statuspage

Prometheus Alerts to StatusPage.io

镜像概述和主要用途

Prometheus Alerts to StatusPage.io 是一个Webhook接收器，用于解决Prometheus Alertmanager同时触发多个相关警报时，仅在StatusPage.io上创建单个事件的问题。它能够聚合多个关联警报，避免重复报告，确保状态页面信息简洁准确。

核心功能和特性

• 警报聚合：按StatusPage页面ID和组件ID分组，将多个相关警报合并为单个事件
• 状态自动更新：根据警报状态自动创建、更新或解决StatusPage事件
• 优先级处理：对事件状态、影响级别和组件状态按预设优先级进行更新
• 自定义模板：支持通过Handlebars模板自定义事件标题和正文内容
• 灵活配置：通过Prometheus警报标签和注释控制StatusPage事件属性

使用场景和适用范围

适用于多团队监控同一系统组件的场景。例如：

• 电商平台的结账功能可能触发多个团队的警报（UI测试失败、API测试失败、订单量下降等），但根本原因相同
• 微服务架构中，单个服务故障可能导致依赖其的多个服务触发警报
• 需要向用户展示统一、简洁系统状态的场景

前提条件

1. 拥有https://www.atlassian.com/software/statuspage%E8%B4%A6%E6%88%B7
2. 在statuspage.io中已配置页面和组件，并获取页面ID和组件ID
3. 拥有statuspage.io API密钥

使用方法和配置说明

1. 环境变量

必填环境变量

• STATUSPAGE_APIKEY：StatusPage API密钥

可选环境变量（用于自定义模板）

• STATUSPAGE_INCIDENT_TITLE_TEMPLATE：事件标题模板
• STATUSPAGE_INCIDENT_CREATED_BODY_TEMPLATE：事件创建时的正文模板
• STATUSPAGE_INCIDENT_UPDATED_BODY_TEMPLATE：事件更新时的正文模板
• STATUSPAGE_INCIDENT_RESOLVED_BODY_TEMPLATE：事件解决时的正文模板

2. Prometheus警报配置

在Prometheus警报规则中添加特定标签和注释，用于控制StatusPage事件：

yaml
- alert: P1-Team1-Checkout-Customer-Alert1
  expr: vector(0) > 0
  labels:
    statusPageIO: true # 标记该警报需要发送到StatusPage
    statusPageIOPageId: abcd1234 # StatusPage页面ID
    statusPageIOComponentId: efgh9876 # StatusPage组件ID
  annotations:
    statusPageIOComponentName: Checkout (Customer) # 用于事件标题的组件名称
    statusPageIOStatus: identified # 事件状态：identified|investigating|monitoring|resolved
    statusPageIOImpactOverride: minor  # 事件影响级别：none|maintenance|minor|major|critical
    statusPageIOComponentStatus: partial_outage # 组件状态：none|operational|under_maintenance|degraded_performance|partial_outage|major_outage
    statusPageIOSummary: Customers are currently unable to checkout # 状态页面显示的摘要文本

3. AlertManager配置

配置AlertManager路由，将符合条件的警报发送到本工具，并按页面ID和组件ID分组：

yaml
- receiver: statuspage-webhook
  groupBy: ['statusPageIOPageId', 'statusPageIOComponentId']  
  groupWait: 30s # 初始等待时间，用于聚合同一组的其他警报（默认：30s）
  groupInterval: 1m # 同一组新警报的发送间隔（默认：5m）
  repeatInterval: 4h # 重复发送间隔（默认：4h）
  matchers:
    - name: statusPageIO
      value: "true"
...
- name: statuspage-webhook
  webhookConfigs:
    - url: "http://prometheus-alerts-to-statuspage.default.svc.cluster.local:8080/alert"

4. 事件标题和正文模板配置

项目使用https://github.com/jknack/handlebars.java%E8%BF%9B%E8%A1%8C%E6%A8%A1%E6%9D%BF%E6%B8%B2%E6%9F%93%EF%BC%8C%E6%A8%A1%E6%9D%BF%E5%8F%AF%E8%AE%BF%E9%97%AEAlertWrapper%E7%B1%BB%E7%9A%84%E5%B1%9E%E6%80%A7%E3%80%82

默认事件标题模板示例：

handlebars
{{#if (lookup this.commonAnnotations 'statusPageIOComponentName')}}
    {{lookup this.commonAnnotations 'statusPageIOComponentName'}} -
{{/if}}Uh oh, something has gone wrong

输出示例：Checkout (Customer) - uh oh, something has gone wrong

5. 多警报分组处理逻辑

当多个警报被分组时，系统会按以下规则更新事件：

1. 事件状态：取所有警报中的最高状态

   • 优先级：investigating -> identified -> monitoring（默认：identified）

2. 事件影响级别：取所有警报中的最高影响级别

   • 优先级：none -> maintenance -> minor -> major -> critical（默认：none）

3. 组件状态：取所有触发警报中的最高组件状态

   • 优先级：none -> operational -> under_maintenance -> degraded_performance -> partial_outage -> major_outage（默认：none）

工作原理

当警报触发时，工具会根据页面ID和组件ID检查是否存在未解决的事件：

• 若无，创建新事件
• 若有，更新现有事件

只有当分组中的所有警报都停止触发时，事件才会被标记为已解决。

工作流程示例

1. 团队1的警报触发（P1-Team1-Checkout-Customer-Alert1），创建新事件
2. 3分钟后，团队2的相关警报触发（P1-Team2-Checkout-Customer-Alert1），更新现有事件
3. 3分钟后，团队2的警报解决，更新事件以反映该警报已解决（事件仍保持打开状态）
4. 3分钟后，团队1的警报解决，事件被标记为已解决
5. 团队进行事后分析

!https://raw.githubusercontent.com/nathandeamer/prometheus-alerts-to-statuspage/main/example.png