GitLab은 웹훅 리시버를 통해 모든 소스에서 알림을 받을 수 있습니다. 알림은 온콜 로테이션에 대한 페이징을 트리거하거나 인시던트를 생성하는 데 사용할 수 있습니다.

통합 목록#

Maintainer 또는 Owner 권한이 있으면 프로젝트 사이드바 메뉴에서 Settings > Monitor로 이동하고 Alerts 섹션을 확장하여 구성된 알림 통합 목록을 볼 수 있습니다. 목록에는 통합 이름, 유형, 상태(활성화 또는 비활성화)가 표시됩니다.

구성#

GitLab은 사용자가 구성하는 HTTP 엔드포인트를 통해 알림을 받을 수 있습니다.

단일 알림 엔드포인트#

GitLab 프로젝트에서 알림 엔드포인트를 활성화하면 JSON 형식의 알림 페이로드를 받을 수 있습니다. 원하는 대로 언제든지 페이로드를 커스터마이즈할 수 있습니다.

1. 프로젝트에서 Maintainer 권한이 있는 사용자로 GitLab에 로그인합니다.
2. 프로젝트에서 Settings > Monitor로 이동합니다.
3. Alerts 섹션을 확장하고 Select integration type 드롭다운 목록에서 Prometheus 알림이면 Prometheus를, 다른 모니터링 도구면 HTTP Endpoint를 선택합니다.
4. Active 알림 설정을 토글합니다. 통합을 저장하면 웹훅 구성에 필요한 URL과 Authorization Key를 View credentials 탭에서 확인할 수 있습니다. 외부 서비스에도 이 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 알림 설정을 토글합니다. 통합을 저장하면 웹훅 구성에 필요한 URL과 Authorization Key를 View credentials 탭에서 확인할 수 있습니다. 외부 서비스에도 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 Endpoint는 통합 목록에 표시됩니다. 통합 목록 오른쪽에 있는 ⚙️ 설정 아이콘을 선택하면 통합을 편집할 수 있습니다.

커스텀 알림에서 필드 매핑#

모니터링 도구의 알림 형식을 GitLab 알림과 통합할 수 있습니다. 알림 목록과 알림 상세 페이지에 올바른 정보를 표시하려면 HTTP 엔드포인트를 생성할 때 알림의 필드를 GitLab 필드에 매핑합니다.

Alertmanager에 통합 자격 증명 추가(Prometheus 통합 전용)#

Prometheus 알림을 GitLab으로 보내려면 Prometheus 통합의 URL과 authorization key를 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 Endpoint의 경우 다음 파라미터를 전송하여 페이로드를 커스터마이즈할 수 있습니다. 모든 필드는 선택 사항입니다. 수신된 알림에 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 요청 속성#

알림은 Prometheus 웹훅 리시버 형식으로 전달되어야 합니다.

최상위 필수 속성:

• 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: "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
        }
      }
    }
  }]
}

인증#

다음 인증 방식을 사용할 수 있습니다.

• Bearer 인증 헤더
• Basic 인증

<authorization_key>와 <url> 값은 알림 통합을 구성할 때 확인할 수 있습니다.

Bearer 인증 헤더#

authorization key를 Bearer 토큰으로 사용할 수 있습니다.

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

Basic 인증#

authorization key를 password로 사용할 수 있습니다. username은 비워 둡니다.

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

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

Basic 인증은 URL에 자격 증명을 직접 포함하는 방식으로도 사용할 수 있습니다.

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

응답 본문#

JSON 응답 본문에는 요청 내에서 생성된 알림 목록이 포함됩니다.

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

요청이 성공하면 200 응답 코드가 반환됩니다.

테스트 알림 트리거#

프로젝트 maintainer 또는 owner가 통합을 구성한 후, 테스트 알림을 트리거하여 통합이 올바르게 작동하는지 확인할 수 있습니다.

1. Developer, Maintainer, Owner 권한이 있는 사용자로 로그인합니다.
2. 프로젝트에서 Settings > Monitor로 이동합니다.
3. Alerts를 선택하여 섹션을 확장합니다.
4. 목록에서 해당 통합 오른쪽에 있는 ⚙️ 설정 아이콘을 선택합니다.
5. Send test alert 탭을 선택하여 엽니다.
6. 페이로드 필드에 테스트 페이로드를 입력합니다(유효한 JSON 이어야 합니다).
7. Send를 선택합니다.

테스트 결과에 따라 GitLab에 오류 또는 성공 메시지가 표시됩니다.

동일한 알림의 자동 그룹화#

GitLab은 페이로드를 기준으로 알림을 그룹화합니다. 수신된 알림이 다른 알림과 동일한 페이로드 (start_time 및 hosts 속성 제외)를 가지면 GitLab은 이 알림들을 함께 그룹화하고 알림 관리 목록 및 상세 페이지에 카운터를 표시합니다.

기존 알림이 이미 resolved 상태이면 GitLab은 새 알림을 대신 생성합니다.

복구 알림#

HTTP Endpoint가 알림 종료 시각이 설정된 페이로드를 받으면 GitLab의 알림이 자동으로 해결됩니다. 커스텀 매핑 이 없는 HTTP Endpoint의 경우 예상 필드는 end_time 입니다. 커스텀 매핑을 사용하면 예상 필드를 선택할 수 있습니다.

GitLab은 페이로드에 포함될 수 있는 fingerprint 값을 기준으로 해결할 알림을 결정합니다. 알림 속성 및 매핑에 대한 자세한 내용은 GitLab 외부에서 알림 페이로드 커스터마이즈를 참고합니다.

알림이 해결될 때 연결된 인시던트가 자동으로 닫히도록 구성할 수도 있습니다.

Opsgenie 알림 연동#

Opsgenie와의 GitLab 통합을 사용하여 알림을 모니터링할 수 있습니다.

Opsgenie 통합을 활성화하면 동시에 다른 GitLab 알림 서비스를 활성 상태로 둘 수 없습니다.

Opsgenie 통합을 활성화하려면 다음을 수행합니다.

1. Maintainer 또는 Owner 권한이 있는 사용자로 로그인합니다.
2. Monitor > Alerts로 이동합니다.
3. Integrations 선택 상자에서 Opsgenie를 선택합니다.
4. Active 토글을 선택합니다.
5. API URL 필드에 https://app.opsgenie.com/alert/list와 같은 Opsgenie 통합의 기본 URL을 입력합니다.
6. Save changes를 선택합니다.

통합을 활성화한 후 Monitor > Alerts에서 Alerts 페이지로 이동하고 View alerts in Opsgenie를 선택합니다.