集成

GitLab 可以通过 webhook 接收器接受来自任何来源的告警。告警通知 可以触发轮班呼叫或用于创建事件。

集成列表

拥有至少 Maintainer 角色的用户，可以通过在项目侧边栏菜单中导航到 Settings > Monitor， 并展开 Alerts 部分来查看配置的告警集成列表。该列表显示集成名称、类型和状态（启用或禁用）：

配置

GitLab 可以通过您配置的 HTTP 端点接收告警。

单个告警端点

在 GitLab 项目中启用告警端点后，该端点将激活以接收 JSON 格式的告警负载。 您可以随时自定义负载以满足您的需求。

1. 以具有项目 Maintainer 角色的用户身份登录 GitLab
2. 在您的项目中转到 Settings > Monitor
3. 展开 Alerts 部分，在 Select integration type 下拉列表中， 选择 Prometheus 用于来自 Prometheus 的告警，或选择 HTTP Endpoint 用于任何其他监控工具
4. 切换 Active 告警设置。保存集成后，View credentials 标签页中会显示 webhook 配置的 URL 和 Authorization Key。 您还必须在您的外部服务中输入 URL 和 Authorization Key

告警端点

在 GitLab Premium 中，您可以创建多个 唯一的告警端点来接收来自任何外部源的 JSON 格式告警，并且您可以自定义负载。

1. 以具有项目 Maintainer 角色的用户身份登录 GitLab

2. 在您的项目中转到 Settings > Monitor

3. 展开 Alerts 部分

4. 对于您要创建的每个端点：

   1. 选择 Add new integration

   2. 在 Select integration type 下拉列表中，选择 Prometheus 用于来自 Prometheus 的告警，或选择 HTTP Endpoint 用于任何其他监控工具。查看详情

   3. 为集成命名

   4. 切换 Active 告警设置。保存集成后，View credentials 标签页中会显示 webhook 配置的 URL 和 Authorization Key。 您还必须在您的外部服务中输入 URL 和 Authorization Key

   5. 可选。要将监控工具告警中的字段映射到 GitLab 字段，请输入示例负载并选择 Parse payload for custom mapping。 需要有效的 JSON。如果您更新示例负载，还必须重新映射字段。对于 Prometheus 集成，请输入来自负载 alerts 键的单个告警，而不是整个负载

   6. 可选。如果您提供了有效的示例负载，请选择 Payload alert key 中的每个值以映射到 GitLab alert key

   7. 要保存您的集成，请选择 Save Integration。如果需要，您可以在集成创建后，从集成页面的 Send test alert 标签页发送测试告警

新的 HTTP 端点将显示在集成列表中。 您可以通过选择集成列表右侧的 设置图标来编辑集成。

自定义告警中的字段映射

您可以将监控工具的告警格式与 GitLab 告警集成。要在告警列表和 告警详情页面中显示正确的信息，请在创建 HTTP 端点时， 将告警的字段映射到 GitLab 字段：

将集成凭据添加到 Alertmanager（仅限 Prometheus 集成）

要将 Prometheus 告警通知发送到 GitLab，请将 URL 和授权密钥从您的 Prometheus 集成复制到 Prometheus Alertmanager 配置的 webhook_configs 部分：

receivers:
  - name: gitlab
    webhook_configs:
      - http_config:
          authorization:
            type: Bearer
            credentials: 1234567890abdcdefg
        send_resolved: true
        url: http://IP_ADDRESS:PORT/root/manual_prometheus/prometheus/alerts/notify.json
        # Rest of configuration omitted
        # ...

在 GitLab 外部自定义告警负载

预期的 HTTP 请求属性

对于没有自定义映射的 HTTP 端点，您可以通过发送以下参数来自定义负载。 所有字段都是可选的。如果传入的告警不包含 Title 字段的值，则应用默认值 New: Alert。

您还可以向告警负载添加自定义字段。额外参数的值不仅限于基本类型（如字符串或数字）， 还可以是嵌套的 JSON 对象。例如：

{ "foo": { "bar": { "baz": 42 } } }

示例请求体

示例负载：

{
  "title": "事件标题",
  "description": "事件的简短描述",
  "start_time": "2019-09-12T06:00:55Z",
  "service": "受影响的服务",
  "monitoring_tool": "值",
  "hosts": "值",
  "severity": "high",
  "fingerprint": "d19381d4e8ebca87b55cda6e8eee7385",
  "foo": {
    "bar": {
      "baz": 42
    }
  }
}

预期的 Prometheus 请求属性

告警应格式化为 Prometheus webhook 接收器。

顶级必需属性：

• alerts
• commonAnnotations
• commonLabels
• externalURL
• groupKey
• groupLabels
• receiver
• status
• version

从 Prometheus 负载中的 alerts，为数组中的每个项目创建一个 GitLab 告警。 您可以更改下面列出的嵌套参数来配置 GitLab 告警。

annotations 下包含的其他属性在告警详情页面上可用。 任何其他属性都将被忽略。

属性不仅限于基本类型（如字符串或数字），还可以是嵌套的 JSON 对象。例如：

{
    "target": {
        "user": {
            "id": 42
        }
    }
}

Prometheus 严重性选项

来自 Prometheus 的告警可以为 告警严重性 提供以下任何不区分大小写的值：

• Critical: critical、s1、p1、emergency、fatal
• High: high、s2、p2、major、page
• Medium: medium、s3、p3、error、alert
• Low: low、s4、p4、warn、warning
• Info: info、s5、p5、debug、information、notice

如果值缺失或不在列表中，严重性默认为 critical。

示例 Prometheus 告警

示例告警规则：

groups:
- name: example
  rules:
  - alert: ServiceDown
    expr: up == 0
    for: 5m
    labels:
      severity: high
    annotations:
      title: "示例标题"
      runbook: "http://example.com/my-alert-runbook"
      description: "服务已停机超过 5 分钟。"
      gitlab_y_label: "y 轴标签"
      foo:
        bar:
          baz: 42

示例请求负载：

{
  "version" : "4",
  "groupKey": null,
  "status": "firing",
  "receiver": "",
  "groupLabels": {},
  "commonLabels": {},
  "commonAnnotations": {},
  "externalURL": "",
  "alerts": [{
    "startsAt": "2022-010-30T11:22:40Z",
    "generatorURL": "http://host?g0.expr=up",
    "endsAt": null,
    "status": "firing",
    "labels": {
      "gitlab_environment_name": "production",
      "severity": "high"
    },
    "annotations": {
      "title": "示例标题",
      "runbook": "http://example.com/my-alert-runbook",
      "description": "服务已停机超过 5 分钟。",
      "gitlab_y_label": "y 轴标签",
      "foo": {
        "bar": {
          "baz": 42
        }
      }
    }
  }]
}

授权

接受以下授权方法：

• Bearer 授权头
• 基本身份验证

<authorization_key> 和 <url> 值可以在配置告警集成时找到。

Bearer 授权头

授权密钥可以用作 Bearer 令牌：

curl --request POST \
  --data '{"title": "事件标题"}' \
  --header "Authorization: Bearer <authorization_key>" \
  --header "Content-Type: application/json" \
  <url>

基本身份验证

授权密钥可以用作 password。username 留空：

• username: <blank>
• password: <authorization_key>

curl --request POST \
  --data '{"title": "事件标题"}' \
  --header "Authorization: Basic <base_64_encoded_credentials>" \
  --header "Content-Type: application/json" \
  <url>

基本身份验证也可以直接在 URL 中使用凭据：

curl --request POST \
  --data '{"title": "事件标题"}' \
  --header "Content-Type: application/json" \
  <username:password@url>

响应体

JSON 响应体包含请求中创建的任何告警列表：

[
  {
    "iid": 1,
    "title": "事件标题"
  },
  {
    "iid": 2,
    "title": "第二个事件标题"
  }
]

成功响应返回 200 响应代码。

触发测试告警

在项目维护者或所有者配置集成后， 您可以触发测试告警以确认您的集成正常工作。

1. 以至少具有 Developer 角色的用户身份登录
2. 在您的项目中转到 Settings > Monitor
3. 选择 Alerts 展开该部分
4. 选择列表中集成右侧的 设置图标
5. 选择 Send test alert 标签页打开它
6. 在负载字段中输入测试负载（需要有效的 JSON）
7. 选择 Send

GitLab 会根据测试结果显示错误或成功消息。

相同告警的自动分组

GitLab 根据负载对告警进行分组。当传入的告警包含与另一个告警相同的负载 （不包括 start_time 和 hosts 属性）时，GitLab 将这些告警分组在一起， 并在告警管理列表和详情页面上显示计数器。

如果现有告警已经是 resolved 状态，GitLab 将创建一个新告警。

恢复告警

当 HTTP 端点接收到设置了告警结束时间的负载时，GitLab 中的告警会自动解决。 对于没有自定义映射的 HTTP 端点，预期字段是 end_time。 使用自定义映射时，您可以选择预期字段。

GitLab 根据可以作为负载一部分提供的 fingerprint 值来确定要解决哪个告警。 有关告警属性和映射的更多信息，请参阅 在 GitLab 外部自定义告警负载。

您还可以配置在告警解决时自动关闭关联的事件。

链接到您的 Opsgenie 告警

您可以使用 GitLab 与 Opsgenie 的集成来监控告警。

如果您启用 Opsgenie 集成，则不能同时激活其他 GitLab 告警服务。

要启用 Opsgenie 集成：

1. 以至少具有 Maintainer 角色的用户身份登录
2. 转到 Monitor > Alerts
3. 在 Integrations 选择框中，选择 Opsgenie
4. 选择 Active 切换
5. 在 API URL 字段中，输入您的 Opsgenie 集成的 URL，例如 https://app.opsgenie.com/alert/list
6. 选择 Save changes

启用集成后，转到 Monitor > Alerts 的 Alerts 页面，然后选择 View alerts in Opsgenie。