measurementlab/alertmanager-github-receiver

alertmanager-github-receiver

镜像概述和主要用途

并非所有告警都是紧急情况，但所有告警都需要被跟踪，因为它们通常反映实际问题：监控系统的问题、监控相关流程的问题或告警本身的问题。alertmanager-github-receiver通过https://github.com/prometheus/alertmanager%E7%9A%84webhook%E9%80%9A%E7%9F%A5%E5%88%9B%E5%BB%BAGitHub%E8%AE%AE%E9%A2%98%EF%BC%8C%E5%AE%9E%E7%8E%B0%E5%91%8A%E8%AD%A6%E7%9A%84%E6%9C%89%E6%95%88%E8%B7%9F%E8%B8%AA%E5%92%8C%E7%AE%A1%E7%90%86%E3%80%82

核心功能和特性

• 接收Alertmanager的webhook通知并转换为GitHub议题
• 支持通过配置实现议题的自动关闭
• 可根据告警标签动态选择目标仓库
• 支持自定义议题标题模板

使用场景和适用范围

适用于使用Prometheus Alertmanager进行告警管理的团队，需要将告警集中记录到GitHub进行跟踪处理的场景，尤其适合需要系统化管理告警生命周期的开发和运维团队。

详细使用方法和配置说明

构建镜像

bash
make docker DOCKER_TAG=repo/imageName

该命令会构建二进制文件并将镜像推送到指定仓库（repo/imageName）。

环境设置

创建GitHub访问令牌

github-receiver使用用户访问令牌在现有仓库中创建议题，生成步骤如下：

1. 登录GitHub并访问 https://github.com/settings/tokens
2. 点击"Generate new token"按钮
3. 选择"repo"范围及其所有子范围

此访问令牌具有创建议题和操作仓库的权限，需像保护密码一样保护该令牌。

启动GitHub接收器

本地启动命令：

bash
docker run -it -p 9393:9393 measurementlab/alertmanager-github-receiver:latest \
    -authtoken=$(GITHUB_AUTH_TOKEN) -org=<组织名> -repo=<仓库名>

注意：指定的组织（org）和仓库（repo）必须已存在。

配置Alertmanager Webhook插件

Prometheus Alertmanager支持通过Alertmanager Webhook API集成第三方通知机制。

在Alertmanager配置中添加接收器定义：

yaml
- name: 'github-receiver-issues'
  webhook_configs:
  - url: 'http://localhost:9393/v1/receiver'

手动测试通知发布：

bash
msg='{
  "version": "4",
  "groupKey": "fakegroupkey",
  "status": "firing",
  "receiver": "http://localhost:9393/v1/receiver",
  "groupLabels": {"alertname": "FoobarIsBroken"},
  "externalURL": "http://localhost:9093",
  "alerts": [
    {
      "labels": {"thing": "value"},
      "annotations": {"hint": "how to fix foobar"},
      "status": "firing",
      "startsAt": "2018-06-12T01:00:00Z",
      "endsAt": "2018-06-14T01:00:00Z"
    }
  ]
}'
curl -XPOST --data-binary "${msg}" http://localhost:9393/v1/receiver

配置参数说明

Alertmanager与Github接收器兼容性

Alertmanager配置控制传递给github-receiver的告警标签，github-receiver的配置必须与此兼容才能有效工作。

例如，Alertmanager通常使用group_by: ['alertname']的告警路由（参见：https://github.com/prometheus/alertmanager#example%EF%BC%89%E3%80%82github-receiver%E7%9A%84%E9%BB%98%E8%AE%A4%22%E6%A0%87%E9%A2%98%E6%A8%A1%E6%9D%BF%22%E4%B8%BA%60%7B%7B .Data.GroupLabels.alertname }}`，依赖alertname分组标签。

如果告警不包含此标签，模板将计算为<no value>。为避免这种情况，确保github-receiver的标题模板使用Alertmanager Message中可用的标签。

自动关闭功能

如果指定-enable-auto-close，程序会在对应告警解决时关闭议题。它通过-alertlabel的值过滤开放议题，然后匹配议题标题来查找匹配的议题。可使用-title-template-file覆盖议题标题模板以获得更高（或更低）的特异性。默认模板为{{ .Data.GroupLabels.alertname }}，将议题标题设置为告警名称。模板接收Message作为参数。

仓库选择

如果告警包含repo标签，议题将在-org指定的GitHub组织下的该仓库中创建。如果没有repo标签，议题将在-repo选项指定的仓库中创建。