통합

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed형, GitLab Dedicated

GitLab은 웹훅 수신기를 통해 모든 소스에서 경보를 수락할 수 있습니다. 경보 알림은 교대근무 또는 페이지 트리거를 사용하여 호출 로테이션을 트리거하거나 사건을 생성하는 데 사용할 수 있습니다.

통합 디렉터리

최소한 Maintainer 역할로, 프로젝트의 사이드바 메뉴에서 Settings > Monitor로 이동하여 Alerts 섹션을 확장하여 구성된 경보 통합 디렉터리을 볼 수 있습니다. 이 디렉터리에는 통합 이름, 유형 및 상태(활성화 또는 비활성화)이 표시됩니다:

현재 통합

구성

GitLab은 구성한 HTTP 엔드포인트를 통해 경보를 받을 수 있습니다.

개별 HTTP 엔드포인트

GitLab 프로젝트에서 HTTP 엔드포인트를 활성화하면 JSON 형식의 경보 페이로드를 수신할 수 있습니다. 언제든지 페이로드를 원하는 대로 사용자 지정할 수 있습니다.

  1. 프로젝트의 Maintainer 역할이 있는 사용자로 GitLab에 로그인합니다.
  2. 프로젝트에서 Settings > Monitor로 이동합니다.
  3. Alerts 섹션을 확장하고 Select integration type 드롭다운 디렉터리에서 HTTP Endpoint를 선택합니다.
  4. Active 경보 설정을 토글합니다. 웹훅 구성의 URL 및 인증 키는 통합을 저장한 후 View credentials 탭에서 사용할 수 있습니다. 외부 서비스에서도 URL과 인증 키를 입력해야 합니다.

HTTP 엔드포인트

Tier: Premium, Ultimate Offering: GitLab.com, Self-Managed형, GitLab Dedicated

GitLab Premium에서는 JSON 형식의 외부 소스에서 경보를 받기 위해 여러 고유한 HTTP 엔드포인트를 생성할 수 있으며, 페이로드를 원하는 대로 사용자 지정할 수 있습니다.

  1. 프로젝트의 Maintainer 역할을 하는 사용자로 GitLab에 로그인합니다.
  2. 프로젝트에서 Settings > Monitor로 이동합니다.
  3. Alerts 섹션을 확장합니다.
  4. 생성하려는 각 엔드포인트에 대해:

    1. Add new integration을 선택합니다.
    2. Select integration type 드롭다운 디렉터리에서 HTTP Endpoint를 선택합니다.
    3. 통합의 이름을 지정합니다.
    4. Active 경보 설정을 토글합니다. 웹훅 구성의 URLAuthorization Key는 통합을 저장한 후 View credentials 탭에서 사용할 수 있습니다. 외부 서비스에서도 URL과 인증 키를 입력해야 합니다.
    5. 선택 사항. 모니터링 도구의 경보를 GitLab 필드로 매핑하려면 샘플 페이로드를 입력하고 Parse payload for custom mapping을 선택합니다. 유효한 JSON이 필요합니다. 샘플 페이로드를 업데이트하면 필드도 다시 매핑해야 합니다.

    6. 선택 사항. 유효한 샘플 페이로드를 제공했다면 Payload alert key의 각 값을 GitLab alert key매핑할 수 있습니다.
    7. 통합을 저장하려면 Save Integration을 선택합니다. 원하는 경우 통합을 만든 후 Send test alert 탭에서 통합의 테스트 경보를 보낼 수 있습니다.

새로운 HTTP 엔드포인트는 통합 디렉터리에 표시됩니다. 통합을 수정하려면 통합 디렉터리의 오른쪽에 있는 설정 아이콘을 선택할 수 있습니다.

사용자 정의 경보 페이로드 매핑

모니터링 도구의 경보 형식을 GitLab 경보와 통합할 수 있습니다. HTTP endpoint를 생성할 때 경보 필드를 GitLab 필드에 매핑하여 경보 디렉터리경보 상세 페이지에 올바른 정보를 표시할 수 있습니다:

경보 관리 디렉터리

GitLab 외부에서 경보 페이로드 사용자 지정

사용자 지정 된 매핑 없는 HTTP 엔드포인트의 경우 다음 매개변수를 보내어 페이로드를 사용자 지정할 수 있습니다. 모든 필드는 선택 사항입니다. 들어오는 경보에 Title 필드의 값이 포함되어 있지 않으면 기본값인 New: Alert가 적용됩니다.

속성 유형 설명
title 문자열 경보 제목.
description 문자열 문제의 개요.
start_time 날짜시간 경보 시간. 제공되지 않으면 현재 시간이 사용됩니다.
end_time 날짜시간 경보의 해결 시간. 제공된 경우 경보가 해결됩니다.
service 문자열 영향받는 서비스.
monitoring_tool 문자열 연관된 모니터링 도구의 이름.
hosts 문자열 또는 배열 발생한 이슈가 발생한 하나 이상의 호스트.
severity 문자열 경보의 심각성. 대소문자를 구분하지 않습니다. critical, high, medium, low, info, unknown 중 하나일 수 있습니다. 누락되었거나 이 디렉터리에 값이 없는 경우 기본값은 critical입니다.
fingerprint 문자열 또는 배열 경보의 고유 식별자. 동일한 경보의 발생을 그룹화하는 데 사용할 수 있습니다. generic_alert_fingerprinting 기능이 활성화된 경우 페이로드를 기반으로 자동으로 fingerprint가 생성됩니다(start_time, end_time, hosts 매개변수는 제외됨).
gitlab_environment_name 문자열 연관된 GitLab environment의 이름. 대시보드에 경보를 표시하려면 필요합니다.

경보 페이로드에 사용자 지정 필드를 추가할 수 있습니다. 추가 매개변수의 값은 기본 유형(문자열 또는 숫자 등)에 제한되지 않으며 중첩된 JSON 객체일 수도 있습니다. 예를 들어:

{ "foo": { "bar": { "baz": 42 } } }
note
요청은 페이로드 애플리케이션 제한보다 작아야 합니다.

예시 요청 본문

예시 페이로드:

{
  "title": "사건 제목",
  "description": "사건 간단한 개요",
  "start_time": "2019-09-12T06:00:55Z",
  "service": "영향 받는 서비스",
  "monitoring_tool": "값",
  "hosts": "값",
  "severity": "높음",
  "fingerprint": "d19381d4e8ebca87b55cda6e8eee7385",
  "foo": {
    "bar": {
      "baz": 42
    }
  }
}

Prometheus 엔드포인트

전제 조건:

  • 프로젝트의 Maintainer 역할이 최소한 필요합니다.
  1. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
  2. Settings > Monitor를 선택합니다.
  3. Alerts 섹션을 확장하고 Add new integration을 선택합니다.
  4. Select integration type 드롭다운 디렉터리에서 Prometheus를 선택합니다.
  5. Active 토글을 켭니다.
  6. Prometheus API base URL을 입력합니다. 이 필드를 사용하는 기능은 GitLab 16.0에서 지원 중단되고 있으며 제거 예정입니다.
  7. Save integration을 선택합니다.

웹훅 구성을 위한 URL 및 인증 키는 View credentials 탭에서 사용할 수 있습니다.

URL 및 인증 키를 외부 서비스에 입력합니다. 또한, 통합의 Send test alert 탭에서 테스트 경보를 보낼 수도 있습니다.

Prometheus Alertmanager에 통합 자격 증명 추가

Prometheus 경고 알림을 GitLab에 보내려면, Prometheus Alertmanager 구성의 webhook_configs 섹션으로부터 당신의 Prometheus 통합에서 URL과 인증 키를 복사하세요.

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
        # 구성의 나머지 부분 생략
        # ...

예상되는 요청 속성

경고는 Prometheus webhook receiver에 대한 형식에 맞게 예상됩니다.

최상위 필수 속성:

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

Prometheus 페이로드의 alerts에서, 각 항목에 대해 GitLab 경고가 생성됩니다. GitLab 경고를 구성하려면 아래에 나열된 중첩 매개변수를 변경할 수 있습니다.

속성 타입 필수 설명
annotations/title, annotations/summary, 또는 labels/alertname 중 하나 String Yes 경고 제목.
startsAt DateTime Yes 경고 시작 시간.
annotations/description String No 문제의 고수준 요약.
annotations/gitlab_incident_markdown String No 경고에서 생성된 이벤트에 추가 할 GitLab Flavored Markdown.
annotations/runbook String No 이 경고를 관리하는 방법에 대한 문서 또는 지침 링크.
endsAt DateTime No 경고의 해결 시간.
g0.expr generatorUrl의 쿼리 매개변수 String No 관련 지표의 쿼리.
labels/gitlab_environment_name String No 연관된 GitLab 환경의 이름. 대시보드에 경고를 표시하려면 필수.
labels/severity String No 경고의 심각도. Prometheus 심각도 옵션 중 하나여야 함. 누락되었거나 이 디렉터리에 없는 경우 critical로 기본값 설정됩니다.
status String No Prometheus에서의 경고 상태. 값이 ‘resolved’이면 경고가 해결됩니다.
annotations/gitlab_y_label, annotations/title, annotations/summary, 또는 labels/alertname 중 하나 String No GitLab Flavored Markdown에 이 경고의 메트릭을 포함시킬 때 사용할 Y-축 레이블.

annotations 아래 포함된 추가 속성은 경고 세부 정보 페이지에서 사용할 수 있습니다. 다른 어떤 속성도 무시됩니다.

속성은 원시 유형(문자열 또는 숫자와 같은)에만 한정되지 않으며, 중첩된 JSON 객체가 될 수 있습니다. 예를 들어:

{
    "target": {
        "user": {
            "id": 42
        }
    }
}
note
요청이 페이로드 응용 프로그램 한도보다 작아야 합니다.

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 인증 헤더
  • 기본 인증

<authorization_key><url> 값은 경고 통합을 구성할 때 찾을 수 있습니다.

Bearer 인증 헤더

인증 키는 Bearer 토큰으로 사용될 수 있습니다:

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

기본 인증

인증 키는 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>

기본 인증은 직접 자격 증명을 URL에 사용할 수도 있습니다:

curl --request POST \
  --data '{"title": "Incident title"}' \
  --header "Content-Type: application/json" \
  <username:password@url>
caution
URL에 인가 키를 사용하는 것은 보안상 취약합니다. 서버 로그에 키가 표시됩니다. 툴이 지원하는 경우, 위의 헤더 옵션 중 하나를 사용하는 것이 좋습니다.

응답 본문

JSON 응답 본문은 요청 내에서 생성된 경고의 디렉터리을 포함합니다:

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

성공적인 응답은 200 응답 코드를 반환합니다.

테스트 경고 트리거

프로젝트 유지 관리자 또는 소유자 가 통합을 구성한 후, 통합이 올바르게 작동하는지 확인하기 위해 테스트 알림을 트리거할 수 있습니다.

  1. 적어도 개발자 역할을 가진 사용자로서 로그인합니다.
  2. 프로젝트에서 설정 > 모니터로 이동합니다.
  3. 섹션을 확장하려면 알림을 선택합니다.
  4. 디렉터리에서 통합 오른쪽에 있는 설정 아이콘을 선택합니다.
  5. 보내기 테스트 알림 탭을 열려면 선택합니다.
  6. 페이로드 필드에 테스트 데이터를 입력합니다(유효한 JSON이 필요합니다).
  7. 보내기를 선택합니다.

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

동일한 경고의 자동 그룹화

Tier: Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

GitLab은 페이로드를 기준으로 경고를 그룹화합니다. 들어오는 경고가 다른 경고와 동일한 페이로드를 포함하는 경우(start_timehosts 속성은 제외), GitLab은 이러한 경고를 함께 그룹화하고 알림 관리 디렉터리 및 상세 페이지에 카운터를 표시합니다.

기존 경고가 이미 해결됨 상태인 경우, GitLab은 대신 새로운 경고를 생성합니다.

알림 관리 디렉터리

복구 알림

GitLab의 경고는 표시된 종료 시간이 있는 페이로드를 HTTP 엔드포인트에서 자동으로 해결합니다. HTTP 엔드포인트의 경우 사용자 정의 매핑이 없으면 예상 필드는 end_time입니다. 사용자 정의 매핑으로 예상 필드를 선택할 수 있습니다.

GitLab은 페이로드의 일부로 제공할 수 있는 fingerprint 값에 따라 해결해야 할 경고를 결정합니다. 경고 속성 및 매핑에 대한 자세한 정보는 GitLab 외부에서 경고 페이로드를 사용자 정의하는 방법을 참조하세요.

또한 경고가 해결되면 연관된 사건이 자동으로 닫히도록 구성할 수 있습니다.

Opsgenie 알림에 대한 링크

Tier: Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

경고 도구와의 깊은 통합을 구축하고 있으며 단일 HTTP 엔드포인트를 통해 GitLab 인터페이스에서 알림을 확인할 수 있습니다.

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

Opsgenie 통합을 활성화하면 동시에 다른 GitLab 경고 서비스를 활성화할 수 없습니다.

Opsgenie 통합을 활성화하려면:

  1. 소유자 또는 유지 관리자 역할을 가진 사용자로서 로그인합니다.
  2. 모니터 > 알림로 이동합니다.
  3. 통합 선택 상자에서 Opsgenie를 선택합니다.
  4. 활성화 토글을 선택합니다.
  5. API URL 필드에 Opsgenie 통합의 기본 URL을 입력합니다. 예: https://app.opsgenie.com/alert/list.
  6. 변경 사항 저장을 선택합니다.

통합을 활성화한 후, 모니터 > 알림 페이지로 이동한 다음 Opsgenie에서 알림 보기를 선택합니다.