• 集成列表
• 配置
  • 单个 HTTP 端点
  • HTTP 端点 (PREMIUM ALL)
    • 在自定义警报中映射字段
• 在极狐GitLab 之外自定义警报有效负载
  • 示例请求体
  • Prometheus 端点
    • 将集成凭据添加到 Prometheus Alertmanager
    • 预期的请求属性
    • Prometheus 严重性选项
    • Prometheus 警报示例
• 授权
  • 承载授权 header
  • 基本认证
• 返回体
• 触发测试警报
• 相同警报的自动分组 (PREMIUM ALL)
• 恢复警报
• 关联到您的 Opsgenie 警报 (PREMIUM ALL)

集成 (BASIC ALL)

极狐GitLab 可以通过 Webhook 接收器接收来自任何来源的警报。警报通知可以对 on-call 触发呼叫，或用于创建事件。

集成列表

引入于 13.5 版本。

您需要至少拥有维护者角色，可以通过导航到项目侧边栏菜单中的 设置 > 监控，并展开 警报 部分来查看配置的警报集成列表。该列表显示集成名称、类型和状态（启用或禁用）：

配置

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

单个 HTTP 端点

在极狐GitLab 项目中，启用 HTTP 端点会激活接收 JSON 格式的警报负载。您始终可以根据需要自定义有效负载。

1. 以具有项目维护者角色的用户身份登录极狐GitLab。
2. 在您的项目中导航到 设置 > 监控。
3. 展开 警报 部分，然后在 选择集成类型 下拉菜单中，选择 HTTP 端点。
4. 切换 启用 警报设置。保存集成后，查看凭据选项卡中提供了 Webhook 配置的 URL 和授权密钥。您还必须在外部服务中输入 URL 和授权密钥。

HTTP 端点 (PREMIUM ALL)

引入于 13.6 版本。

在专业版中，您可以创建多个唯一的 HTTP 端点，接收来自任何外部源的 JSON 格式的警报，并且您可以自定义有效负载。

1. 以具有项目维护者角色的用户身份登录极狐GitLab。
2. 在您的项目中导航到 设置 > 监控。
3. 展开 警报 部分。

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

   1. 选择添加新集成。
   2. 在 选择集成类型 下拉菜单中，选择 HTTP 端点。
   3. 命名集成。
   4. 切换 启用 警报设置。保存集成后，用于 Webhook 配置的 URL 和 授权密钥 在 查看凭据 选项卡中可用。您还必须在外部服务中输入 URL 和授权密钥。

   5. 可选。要将监控工具警报中的字段映射到极狐GitLab 字段，请输入示例有效负载并选择 解析有效负载并进行自定义映射。需要有效的 JSON。如果您更新示例负载，您还必须重新映射字段。

   6. 可选。如果您提供了有效的示例负载，请选择 负载警报键 中的每个值，映射到极狐GitLab 警报键。
   7. 要保存集成，请选择 保存集成。如果需要，您可以在创建集成后，从集成的 发送测试警报 选项卡发送测试警报。

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

在自定义警报中映射字段

引入于 13.10 版本。

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

在极狐GitLab 之外自定义警报有效负载

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

您还可以将自定义字段添加到警报的有效负载中。额外参数的值不仅限于原始类型（如字符串或数字），还可以是嵌套的 JSON 对象。例如：

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

示例请求体

示例负载：

{
  "title": "Incident title",
  "description": "Short description of the incident",
  "start_time": "2019-09-12T06:00:55Z",
  "service": "service affected",
  "monitoring_tool": "value",
  "hosts": "value",
  "severity": "high",
  "fingerprint": "d19381d4e8ebca87b55cda6e8eee7385",
  "foo": {
    "bar": {
      "baz": 42
    }
  }
}

Prometheus 端点

先决条件：

• 您必须至少具有该项目的维护者角色。

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目。
2. 在左侧边栏中，选择 设置 > 监控。
3. 展开 警报 部分，然后选择 添加新的集成。
4. 从 选择集成类型 下拉列表中，选择 Prometheus。
5. 打开 启用 开关。
6. 输入 Prometheus API 基本 URL。 您应该输入一个占位 URL。使用此字段的功能废弃并计划删除于 16.0 版本。
7. 选择 保存集成。

Webhook 配置的 URL 和授权密钥在 查看凭据 页签中可用。

在您的外部服务中输入 URL 和授权密钥。 您还可以从集成的 发送测试警报 页签发送测试警报。

将集成凭据添加到 Prometheus Alertmanager

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

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
        # ...

预期的请求属性

警报应针对 Prometheus Webhook 接收器进行格式化。

必需的顶级属性：

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

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

警报详细信息页面上提供了 annotations 下包含的其他属性。忽略任何其他属性。

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

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

Prometheus 严重性选项

引入于 13.9 版本。

来自 Prometheus 的警报，可以为警报严重性提供任何不区分大小写的后续值：

• 严重：critical、s1、p1、emergency、fatal
• 高：high、s2、p2、major、page
• 中：medium、s3、p3、error、alert
• 低：low、s4、p4、warn、warning
• 消息：info、s5、p5、debug、information、notice

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

Prometheus 警报示例

警报规则示例：

groups:
- name: example
  rules:
  - alert: ServiceDown
    expr: up == 0
    for: 5m
    labels:
      severity: high
    annotations:
      title: "Example title"
      runbook: "http://example.com/my-alert-runbook"
      description: "Service has been down for more than 5 minutes."
      gitlab_y_label: "y-axis label"
      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": "Example title",
      "runbook": "http://example.com/my-alert-runbook",
      "description": "Service has been down for more than 5 minutes.",
      "gitlab_y_label": "y-axis label",
      "foo": {
        "bar": {
          "baz": 42
        }
      }
    }
  }]
}

授权

接受以下授权方式：

• 承载授权 header（Bearer authorization header）
• 基本认证（Basic authentication）

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

承载授权 header

授权密钥可用作 Bearer 令牌：

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

基本认证

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

• 用户名：<blank>
• 密码：<authorization_key>

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

基本认证也可以直接在 URL 中与凭据一起使用：

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

返回体

引入于 14.5 版本。

JSON 响应正文包含在请求中创建的任何警报的列表：

[
  {
    "iid": 1,
    "title": "Incident title"
  },
  {
    "iid": 2,
    "title": "Second Incident title"
  }
]

成功的响应返回一个 200 响应码。

触发测试警报

引入于 13.2 版本。

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

1. 以至少具有开发者角色的用户身份登录。
2. 在您的项目中导航到 设置 > 监控。
3. 选择 警报，展开该部分。
4. 在列表中选择集成右侧的 设置图标。
5. 选择 发送测试警报 选项卡将其打开。
6. 在有效负载字段中输入测试有效负载（需要有效的 JSON）。
7. 选择 发送。

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

相同警报的自动分组 (PREMIUM ALL)

引入于 13.2 版本。

在 13.2 及更高版本中，极狐GitLab 根据其有效负载对警报进行分组。当传入警报包含与另一个警报相同的有效负载（不包括 start_time 和 hosts 属性）时，系统将这些警报组合在一起，并在警报管理列表和详细信息页面上显示一个计数器。

如果现有警报已经处于 resolved，系统会创建一个新警报。

恢复警报

引入于 13.4 版本。

当 HTTP 端点接收到带有警报集结束时间的有效负载时，系统中的警报将自动解决。对于没有自定义映射的 HTTP 端点，预期的字段是 end_time。使用自定义映射，您可以选择预期的字段。

当警报解决时，您还可以配置关联的事件自动关闭。

关联到您的 Opsgenie 警报 (PREMIUM ALL)

引入于 13.2 版本。

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

如果启用 Opsgenie 集成，则不能同时激活其它极狐GitLab 警报服务。

要启用 Opsgenie 集成：

1. 以具有维护者或所有者角色的用户身份登录。
2. 导航到 监控 > 警报。
3. 在 集成 选择框中，选择 Opsgenie。
4. 选择 启用 切换。
5. 在 API URL 字段中，输入 Opsgenie 集成的基本 URL，例如 https://app.opsgenie.com/alert/list。
6. 选择 保存修改。

启用集成后，导航到 监控 > 警报 处的警报列表页面，然后选择 查看 Opsgenie 中的警报。