알림 API

알림 API (Alerts API)

Alertmanager에 알림을 보내는 API 계약을 설명하는 문서예요. Prometheus가 자체적으로 알림을 처리하므로 보통은 직접 쓸 일이 없지만, Prometheus 없이 다른 시스템이 Alertmanager로 알림을 보내는 고급 사용 사례에서 이 계약을 알아두면 도움이 됩니다.

특히 APIv2의 POST 방식과 labels, annotations, startsAt, endsAt 필드의 의미, 그리고 클라이언트가 알림을 재전송해야 하는 규칙을 정확히 이해하는 게 핵심이에요.

출처: 문서

본문

중요: Prometheus는 Alertmanager로 알림을 보내는 작업을 자체적으로 처리해요. Alerts API로 직접 알림을 보내기보다는, Prometheus에서 타임시리즈 데이터를 기반으로 알림 규칙(alerting rules)을 구성하는 것이 권장됩니다. Prometheus는 Alertmanager가 크래시하거나 재시작되어도 알림이 전달되도록 여러 특수한 경우를 지원하기 때문이에요.

Alertmanager로 알림을 보내려면 APIv2를 사용합니다. APIv2는 여기에서 찾을 수 있는 OpenAPI 사양으로 정의되어 있어요.

APIv1은 Alertmanager 버전 0.16.0에서 더 이상 사용되지 않았고(deprecated), 버전 0.27.0에서 제거되었습니다.

APIv2로 알림을 보내려면 api/v2/alerts로 POST 요청을 보내면 됩니다. Content-Type 헤더를 application/json으로 설정해야 하고, 알림 배열(JSON array)을 포함한 JSON 데이터를 전송해야 해요.

다음은 예시입니다:

[
  {
    "labels": {
      "alertname": "",
      "": "",
      ...
    },
    "annotations": {
      "": "",
    },
    "startsAt": "",
    "endsAt": "",
    "generatorURL": ""
  },
  ...
]

모든 알림은 labels, annotations, 선택적인 startsAt 타임스탬프, 선택적인 endsAt 타임스탬프를 가져요. 모든 타임스탬프는 RFC3339 형식이어야 합니다.

labels는 동일한 알림의 동일한 인스턴스를 중복 제거하는 데 사용되고, annotations는 요약(summary), 설명(description), 런북(runbook) URL 같은 알림에 대한 다른 정보를 담는 데 사용됩니다.

startsAt 타임스탬프는 알림이 발생한 시각이에요. 생략하면 Alertmanager는 startsAt를 현재 시각으로 설정합니다.

endsAt 타임스탬프는 알림이 해결(resolved)되어야 하는 시각이에요. 생략하면 Alertmanager는 endsAt를 현재 시각 + resolve_timeout으로 설정합니다.

generatorURL은 알림의 출처로 연결되는 고유 URL이에요. 예를 들어 Prometheus의 발생 중인(firing) 규칙에 연결될 수 있습니다.

클라이언트가 기대하는 것 (Expectations from clients)

클라이언트는 알림이 해결될 때까지 정기적인 간격으로 발생 중인 알림을 Alertmanager에 재전송해야 합니다.

정확한 간격은 endsAt 타임스탬프 같은 여러 변수에 따라 달라지며, 생략된 경우에는 resolve_timeout 값에 따라 달라져요. endsAt 타임스탬프가 생략되면, Alertmanager는 해당 알림의 기존 endsAt 타임스탬프를 현재 시각 + resolve_timeout으로 갱신합니다.

발생 중인 알림은 endsAt 타임스탬프가 지나면 해결됩니다.

해결된 알림에 대해 해결 알림(notification)이 전송되도록 보장하기 위해, 클라이언트는 알림이 해결된 후 최대 5분 동안 해결된 알림을 Alertmanager에 재전송해야 합니다. Alertmanager는 무상태(stateless)이므로, 이렇게 해야 Alertmanager가 크래시하거나 재시작되어도 해결 알림이 전송됩니다.

더 알아보기 (Learn more)