Prometheus Alertmanager 알림을 휴대폰으로: 심각도별 라우팅, 그룹화, 조용한 해결 알림

Prometheus는 무언가 잘못되었다는 것을 잘 알아챕니다. 그 소식을 사람에게 전하는 일은 Alertmanager의 몫인데, 많은 환경에서 그 소식은 아무도 새벽 3시에 읽지 않는 이메일 폴더나 Slack 채널에 머물러 있습니다.
Alertmanager에는 자체 푸시 앱이 없지만 범용 웹훅 리시버가 있고, 휴대폰으로 알림을 받는 데는 그것이면 충분합니다. 이 가이드에서는 심각도별 라우팅을 설정합니다. critical 알림은 크게, 경고는 일반 알림으로, "resolved"(해결됨) 알림은 조용하게 도착합니다. 여기의 모든 내용은 Docker에서 Alertmanager 0.34.2와 Prometheus 3.15.1로 테스트했습니다. 페이로드는 직접 캡처했고, Pocket Alert 자체 템플릿 코드로 실행해 보았습니다.
준비물
- 전체 설정을 하려면 Alertmanager 0.31 이상이 필요합니다. 이전 버전은 아래에서 다룹니다.
- iPhone 또는 Android에 Pocket Alert 앱을 설치하고, API 키 페이지에서 API 키를 발급받으세요.
- 웹훅 세 개를 쓰는 설정에는 유료 플랜이 필요합니다. 무료 플랜에는 웹훅이 하나만 포함되기 때문입니다. 웹훅 하나만 쓰는 버전은 글 끝부분에 있습니다.
Alertmanager가 보내는 것
Alertmanager는 알림 하나당 요청 하나를 보내지 않습니다. 알림을 group_by에 지정한 레이블 기준으로 묶어서, 그룹마다 알림 하나를 보냅니다. 고정된 JSON 본문과 함께 "version": "4"를 담은 POST 요청입니다. group_by: ['alertname'] 설정에서 호스트 두 대가 다운되면 요청은 한 번만 나갑니다. 아래는 조금 줄인 실제 페이로드입니다.
{
"receiver": "pocketalert-critical",
"status": "firing",
"alerts": [
{
"status": "firing",
"labels": {"alertname": "InstanceDown", "instance": "web-1:9100", "job": "node", "severity": "critical"},
"annotations": {"summary": "web-1:9100 is down"},
"startsAt": "2026-10-31T16:17:04.374Z",
"generatorURL": "http://prometheus.example.com:9090/graph?g0.expr=up%7Bjob%3D%22node%22%7D+%3D%3D+0&g0.tab=1"
},
{
"status": "firing",
"labels": {"alertname": "InstanceDown", "instance": "web-2:9100", "job": "node", "severity": "critical"},
"annotations": {"summary": "web-2:9100 is down"}
}
],
"notification_reason": "first notification",
"groupLabels": {"alertname": "InstanceDown"},
"commonLabels": {"alertname": "InstanceDown", "job": "node", "severity": "critical"},
"commonAnnotations": {},
"routeLabels": {},
"externalURL": "http://alertmanager.example.com:9093",
"version": "4",
"groupKey": "{}/{severity=\"critical\"}:{alertname=\"InstanceDown\"}",
"truncatedAlerts": 0
}
이 페이로드 구조에서 설정에 영향을 주는 점은 네 가지입니다.
- 그룹당 푸시 하나. 개별 알림은
alerts배열에 들어 있으므로, 메시지 템플릿은 배열을 다룰 수 있어야 합니다. commonAnnotations는 자주 비어 있습니다. 그룹 안의 모든 알림에 똑같이 적용되는 어노테이션만 담기 때문입니다. 인스턴스 이름이 들어간 요약은 알림마다 다르므로 여기에 나타나지 않습니다.status는 그룹의 상태입니다. 그룹 안의 모든 알림이 해결되었을 때만resolved가 됩니다. 한 호스트는 복구되었고 다른 호스트는 여전히 다운되어 있다면, 상태는firing으로 유지되고 복구된 알림은 내부에 자체"status": "resolved"와 함께 나열됩니다.- 최상위
level필드는 없습니다. Pocket Alert 웹훅은 우선순위를 그 자리에서 찾습니다. 그래서 우선순위는 웹훅의 기본 레벨에서 옵니다. 이 가이드가 알림 강도마다 웹훅을 하나씩 쓰는 이유가 여기에 있습니다.
1단계: Pocket Alert 웹훅 만들기
| 웹훅 | default_level | 받는 알림 |
|---|---|---|
| Prometheus critical | 2 (critical) | severity="critical"인 발생 중 그룹 |
| Prometheus warning | 0 (default) | 그 밖의 모든 발생 중 그룹 |
| Prometheus resolved | -1 (low) | 모든 알림이 해결된 그룹 |
버튼은 API로만 설정할 수 있으므로, 스크립트 하나로 웹훅 세 개를 모두 만드세요.
PA_KEY='your-api-key'
FIRING='%groupLabels.alertname%: %alerts.#(status=="firing")#|#% firing
%alerts.#(status=="firing").annotations.summary%
Firing: %alerts.#(status=="firing")#.labels.instance%'
RESOLVED='Resolved: %groupLabels.alertname% (%commonLabels.severity%)
%alerts.#.labels.instance%'
BUTTONS='[{"type":"view","label":"Alertmanager","value":"%externalURL%"}]'
create_webhook() {
jq -n --arg name "$1" --argjson level "$2" --arg message "$3" --arg actions "$4" \
'{name: $name, default_level: $level, message: $message, actions: $actions}' |
curl -sS https://api.pocketalert.app/v1/webhooks \
-H "Token: $PA_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- |
jq -r '"\(.name): https://p4a.me/wh/\(.url)"'
}
create_webhook 'Prometheus critical' 2 "$FIRING" "$BUTTONS"
create_webhook 'Prometheus warning' 0 "$FIRING" "$BUTTONS"
create_webhook 'Prometheus resolved' -1 "$RESOLVED" ''
스크립트는 수신 URL 세 개를 출력합니다. 각 URL 끝의 슬러그는 잘 보관하세요. 이 슬러그를 alertmanager.yml에 붙여 넣게 됩니다.
%...% 플레이스홀더는 GJSON 경로이고, GJSON은 배열을 조회할 수 있습니다.
alerts.#(status=="firing")#|#는 그룹에서 아직 발생 중인 알림의 개수를 셉니다.alerts.#(status=="firing").annotations.summary는 발생 중인 첫 번째 알림의 요약입니다.alerts.#(status=="firing")#.labels.instance는 발생 중인 모든 알림의 인스턴스를 나열합니다. 문자열을 이어 붙이는 함수가 없기 때문에["web-1:9100","web-2:9100"]처럼 JSON 배열로 렌더링됩니다.
존재하지 않는 경로는 빈 문자열로 렌더링됩니다. 그래서 잘못된 경로를 쓰면 알림이 사라지는 대신 빈 줄이 나옵니다. Pocket Alert는 웹훅 푸시의 제목을 항상 Webhook <name>으로 붙이므로, 제목은 "Webhook Prometheus critical"이 되고 알림 이름은 메시지의 첫 줄에 나옵니다. critical은 유료 플랜이 필요합니다. 어차피 웹훅 세 개를 쓰는 이 설정에도 유료 플랜이 필요합니다. iPhone에서는 무음 스위치와 방해 금지 모드를 뚫고 소리가 나고, Android에서는 화면을 전면으로 띄웁니다. 알림이 방해 금지 모드를 무시하길 원하지 않는다면 1(high)을 대신 쓰세요.
2단계: alertmanager.yml
*_SLUG 플레이스홀더 세 개를 실제 슬러그로 바꾸세요.
route:
receiver: pocketalert-warning
group_by: ['alertname']
group_wait: 30s
group_interval: 5m
repeat_interval: 4h
routes:
- matchers: ['severity="critical"']
receiver: pocketalert-critical
group_wait: 10s
repeat_interval: 1h
- matchers: ['severity="info"']
receiver: blackhole
receivers:
- name: pocketalert-critical
webhook_configs:
- url: 'https://p4a.me/wh/{{ if eq .Status "resolved" }}RESOLVED_SLUG{{ else }}CRITICAL_SLUG{{ end }}'
send_resolved: true
max_alerts: 20
- name: pocketalert-warning
webhook_configs:
- url: 'https://p4a.me/wh/{{ if eq .Status "resolved" }}RESOLVED_SLUG{{ else }}WARNING_SLUG{{ end }}'
send_resolved: true
max_alerts: 20
- name: blackhole
inhibit_rules:
- source_matchers: ['severity="critical"']
target_matchers: ['severity="warning"']
equal: ['alertname', 'instance', 'mountpoint']
각 부분의 동작은 다음과 같습니다.
- 심각도별 라우팅.
severity="critical"은 소리가 큰 리시버로 가고,info는 버려지며,severity레이블이 없는 알림을 포함한 나머지는 경고 리시버로 넘어갑니다. - URL이 웹훅을 고릅니다. 0.31.0부터 웹훅
url은 템플릿입니다. 상태가resolved인 그룹은 조용한 웹훅으로 가고, 그 밖의 그룹은 리시버 자신의 웹훅으로 갑니다. 웹훅의send_resolved는 기본값이 이미true이지만, 누군가 알아채지 못한 채 끄지 않도록 명시해 두었습니다. - **
max_alerts: 20**은 요청 하나에 들어갈 알림 수를 제한합니다. 테스트에서는 호스트 25대가 한꺼번에 다운되었습니다. 그 결과 "20 firing"이라고 적힌 푸시 하나가 왔고, 페이로드에는truncatedAlerts: 5가 들어 있었습니다. - 억제(inhibition). 파일시스템에 대해 critical
DiskSpaceLow가 발생하면, 같은alertname,instance,mountpoint의 경고는 음소거됩니다.amtool alert query --inhibited를 실행하면suppressed로 표시됩니다.
다시 불러오기 전에 설정과 라우팅을 확인하세요.
amtool check-config alertmanager.yml
amtool config routes test --config.file=alertmanager.yml severity=critical alertname=Test
두 번째 명령은 pocketalert-critical을 출력합니다.
Alertmanager를 시작할 때는 휴대폰에서 열 수 있는 주소를 --web.external-url로 지정하세요. 지정하지 않으면 externalURL에 호스트 이름만 들어갑니다. Docker에서는 http://de48ea5ffc29:9093처럼 나와서 버튼이 쓸모없게 됩니다.
먼저 버전을 확인하세요
템플릿 URL을 쓰려면 alertmanager --version이 0.31 이상이어야 합니다. 0.30.1은 이 설정을 그대로 받아들이고 amtool check-config도 SUCCESS를 보고하지만, 템플릿을 렌더링하지 않습니다. 요청을 /wh/%7B%7B%20if%20eq%20.Status...로 보냈고, 이는 어떤 웹훅과도 맞지 않습니다. 이전 버전에서는 각 리시버에 자기 웹훅의 일반 URL을 넣으세요. 그러면 해결 알림도 그 웹훅의 우선순위로 도착합니다.
3단계: 심각도 레이블이 있는 규칙
위의 라우팅은 규칙에 severity가 설정되어 있어야만 동작합니다. 예시 두 개를 아래에 실었습니다(무엇을 감시할지에 대한 더 많은 아이디어는 서버 모니터링 페이지에 있습니다). 억제 규칙이 할 일이 있도록 DiskSpaceLow는 임계값을 두 개로 나눴습니다.
groups:
- name: node
rules:
- alert: InstanceDown
expr: up{job="node"} == 0
for: 2m
labels:
severity: critical
annotations:
summary: '{{ $labels.instance }} is down'
- alert: DiskSpaceLow
expr: node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes * 100 < 15
for: 10m
labels:
severity: warning
annotations:
summary: '{{ $labels.instance }} {{ $labels.mountpoint }} has {{ printf "%.0f" $value }}% free'
- alert: DiskSpaceLow
expr: node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes * 100 < 5
for: 5m
labels:
severity: critical
annotations:
summary: '{{ $labels.instance }} {{ $labels.mountpoint }} has {{ printf "%.0f" $value }}% free'
promtool check rules rules.yml로 파일을 검증할 수 있습니다. prometheus.yml에서 Prometheus가 이 파일과 Alertmanager를 가리키도록 설정하세요.
rule_files: [rules.yml]
alerting:
alertmanagers:
- static_configs:
- targets: ['alertmanager:9093']
amtool로 테스트하기
테스트 알림을 발생시키고, group_wait(critical 라우트에서는 10초)를 기다린 뒤 해결하세요.
amtool --alertmanager.url=http://localhost:9093 alert add alertname=PocketAlertTest severity=critical instance=test:9100 \
--annotation='summary="Test alert from amtool"'
amtool --alertmanager.url=http://localhost:9093 alert add alertname=PocketAlertTest severity=critical instance=test:9100 \
--annotation='summary="Test alert from amtool"' --end="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
어노테이션의 안쪽 큰따옴표는 그대로 두세요. 그렇지 않으면 amtool이 예전 파서로 대체되었다고 경고합니다. 해결 알림 푸시는 다음 group_interval 주기에 도착하며, 이 설정에서는 최대 5분까지 걸릴 수 있습니다.
휴대폰에 도착하는 내용
아래는 테스트에서 Prometheus가 web-1과 web-2가 다운되었다가 복구되는 것을 확인했을 때의 실제 페이로드로 Pocket Alert가 렌더링한 메시지입니다.
Webhook Prometheus critical
InstanceDown: 2 firing
web-1:9100 is down
Firing: ["web-1:9100","web-2:9100"]
web-1이 복구되면 Alertmanager는 다음 group_interval에 업데이트를 보냅니다. 그룹은 여전히 발생 중이므로 critical 웹훅으로 갑니다.
Webhook Prometheus critical
InstanceDown: 1 firing
web-2:9100 is down
Firing: ["web-2:9100"]
둘 다 복구되면 낮은 우선순위의 푸시가 도착합니다.
Webhook Prometheus resolved
Resolved: InstanceDown (critical)
["web-1:9100","web-2:9100"]
타이머: 푸시 폭주 막기
| 설정 | 역할 | 이 설정에서 |
|---|---|---|
group_wait | 새 그룹이 첫 푸시 전에 추가 알림을 기다리는 시간 | 30s, critical은 10s |
group_interval | 알림이 바뀐 그룹에 대해 푸시 사이의 최소 간격 | 5m |
repeat_interval | 여전히 발생 중이고 변화가 없는 그룹에 대한 재알림 간격 | 4h, critical은 1h |
그룹은 group_interval마다 최대 한 번 푸시할 수 있으므로, 5m 설정에서 들락날락하는 알림은 시간당 최대 12개의 푸시를 만듭니다. 하루 종일 가는 장애는 repeat_interval 1h 설정에서 재알림 24개를 만듭니다. 그룹화가 대부분의 일을 합니다. 스위치 하나가 죽어서 호스트 40대가 다운되면 푸시는 40개가 아니라 하나입니다. group_by: ['...']는 쓰지 마세요. 모든 레이블 기준으로 묶기 때문에 알림마다 푸시 하나가 되어 버립니다. 요금제에는 일일 메시지 한도가 있으며(Starter는 하루 1,000건), 메시지를 만드는 웹훅으로 보낸 요청은 모두 이 한도에 포함됩니다.
버튼: Alertmanager와 Grafana
위의 BUTTONS 템플릿은 "Alertmanager" 버튼을 추가합니다. 액션 버튼은 최대 세 개까지 추가할 수 있습니다. 아래 예시의 버튼은 발생 중인 첫 번째 인스턴스의 Grafana 대시보드를 엽니다.
BUTTONS='[{"type":"view","label":"Alertmanager","value":"%externalURL%"},{"type":"view","label":"Grafana","value":"https://grafana.example.com/d/YOUR_DASHBOARD?var-instance=%alerts.#(status=="firing").labels.instance%"}]'
플레이스홀더 안의 이스케이프되지 않은 따옴표는 잘못 보이지만 제대로 동작합니다. Pocket Alert는 먼저 플레이스홀더를 치환한 뒤에 JSON을 파싱하기 때문입니다.
빈 값을 조심하세요. value가 빈 값으로 나온 버튼은 해당 푸시에서 빠지고, 나머지 버튼과 메시지는 그대로 도착합니다. %alerts.0.generatorURL%(Prometheus 그래프 링크)은 Prometheus에서 온 알림에 좋은 대상이지만, amtool로 보낸 알림에는 generator URL이 없으므로 그 버튼 없이 도착합니다. 액션 버튼은 유료 기능입니다.
Alertmanager 0.32 이상: API 직접 호출
예전 가이드에서는 Alertmanager가 웹훅 본문을 바꿀 수 없다고 말합니다. 0.32.0에서 바뀌었습니다. 이 버전에서 payload에 webhook_configs 옵션이 추가되었습니다. http_config.http_headers 헤더를 보낼 수 있는 Token와 함께 쓰면, Alertmanager가 자기 제목과 우선순위를 담아 https://api.pocketalert.app/v1/messages로 바로 POST할 수 있습니다.
함정이 하나 있습니다. Alertmanager는 렌더링된 모든 값을 YAML로 파싱합니다. 테스트에서 필드별로 작성한 페이로드의 message: '{{ range .Alerts }}{{ .Annotations.summary }}...'는 요약 web-1:9100: / has 12% free를 {"web-1:9100": "/ has 12% free"}라는 객체로 바꿔 버렸습니다. API는 이를 400으로 거부합니다. Alertmanager는 4xx를 즉시 재시도하지 않고, 깨진 본문을 group_interval마다 그대로 다시 보냅니다. 그래서 알림은 영원히 도착하지 않습니다.
dict와 toJson으로 본문 전체를 만들면 이 문제를 피할 수 있습니다.
receivers:
- name: pocketalert-api
webhook_configs:
- url: https://api.pocketalert.app/v1/messages
http_config:
http_headers:
Token:
files: [/etc/alertmanager/pocketalert.key]
payload: >-
{{ $msg := "" }}{{ range .Alerts }}{{ $msg = printf "%s%s: %s\n" $msg .Status .Annotations.summary }}{{ end }}
{{ $level := "default" }}{{ if eq .Status "resolved" }}{{ $level = "low" }}{{ else if eq .CommonLabels.severity "critical" }}{{ $level = "critical" }}{{ end }}
{{ dict "title" (printf "[%s] %s" (toUpper .Status) .GroupLabels.alertname) "message" $msg "level" $level | toJson }}
요약에 콜론과 따옴표가 들어 있을 때는 다음과 같이 전송되었습니다.
{"level":"critical","message":"firing: web-1:9100: / has 4% free, \"quoted\"\nfiring: web-2:9100 / has 3% free\n","title":"[FIRING] DiskSpaceLow"}
해결된 버전은 "level":"low"로 도착했습니다.
그렇다면 어느 쪽을 써야 할까요? 직접 API 방식은 리시버 하나로 웹훅 없이 알림마다 실제 제목과 우선순위를 줍니다. 웹훅 방식은 Alertmanager에 API 키가 필요 없고 모든 버전에서 동작합니다(일반 URL 변형). 잘못된 경로는 거부된 요청이 아니라 빈 줄로 렌더링되며, 모든 요청은 웹훅 기록에 남습니다. Alertmanager 공식 문서는 payload에 "사용은 자기 책임으로"라는 표시를 해 두었으니, 의존하기 전에 amtool로 테스트하세요.
무료 플랜에서
무료 플랜에는 웹훅이 하나 있고, 하루 메시지 50건, 버튼 없음이 있으며, critical은 high로 전달됩니다. default_level: 1로 웹훅 하나를 만들고 그 일반 URL을 리시버 하나에 넣은 뒤 심각도 라우트는 빼세요. 그러면 해결 알림도 high로 도착합니다. send_resolved: false로 설정하지 않는 한 그렇습니다. Alertmanager 0.32 이상이라면 위의 직접 API 설정이 무료 플랜에 더 잘 맞습니다. 웹훅이 필요 없고 알림마다 우선순위를 설정할 수 있기 때문입니다.
아무것도 도착하지 않을 때
- Alertmanager 로그를 확인하세요. 전송에 실패하면
Notify for alerts failed와 상태 코드가 기록됩니다.404는 잘못된 슬러그이거나, 0.31보다 오래된 버전에서 템플릿 URL을 쓴 경우입니다. - Pocket Alert에서 웹훅 기록을 여세요. 요청이 있다면 문제는 템플릿입니다. 요청이 없다면 Alertmanager가 아예 보내지 않은 것입니다.
- 빈 줄은 경로가 페이로드와 맞지 않는다는 뜻입니다. 필드 이름은 대소문자를 구분합니다.
- 플레이스홀더 바로 앞의
%는 두 번 써야 합니다.%뒤에 공백이 오면 일반 텍스트이므로CPU over 90% on %groupLabels.alertname%은 그대로 동작합니다. 하지만%%가 다른 텍스트와 붙어 있으면%로 써야 합니다. 예를 들면%commonLabels.usage%%%처럼요. - 템플릿을 쓰기 전에 실제 Alertmanager가 무엇을 보내는지 확인하려면 웹훅 테스터를 사용하세요.
FAQ
kube-prometheus-stack에서도 되나요?
네. 리시버는 일반적인 Alertmanager 설정이므로, 다른 리시버와 마찬가지로 차트의 Alertmanager 설정에 넣으면 됩니다. 템플릿 URL이나 payload를 쓰기 전에 차트가 배포하는 Alertmanager 버전을 확인하세요. 클러스터 쪽 설정은 Kubernetes 알림을 참고하세요.
Alertmanager가 아니라 Grafana 알림을 쓰고 있어요. 무엇이 달라지나요?
Grafana는 자체 웹훅 형식을 보냅니다. Grafana 가이드를 참고하세요.
무료 계정을 만들고 스크립트를 실행한 뒤, 슬러그 세 개를 alertmanager.yml에 붙여 넣으세요. 그러면 다음 InstanceDown이 휴대폰까지 도착합니다.