Copy & Run

Prometheus 알림 규칙 promtool 단위 시험

Prometheus 2.51 컨테이너의 promtool로 알림 규칙의 문법 오류와 논리 오류를 나눠 잡고, 가짜 시계열을 넣어 몇 분 뒤에 알림이 울리는지 단위 시험으로 확인합니다. Alertmanager 0.27의 amtool로 라벨별 수신처가 맞는지, 수신처를 빠뜨린 설정이 막히는지도 서버 없이 시험하고 종료 코드로 판정합니다.

알림 규칙은 평소에는 아무 일도 하지 않다가 장애가 났을 때 처음 동작합니다. 그래서 규칙에 오타나 논리 오류가 있어도 장애가 나기 전에는 모르고, 장애가 난 뒤에는 "알림이 안 왔다"가 가장 비싼 실수가 됩니다. Prometheus는 규칙을 서버 없이 시험할 수 있는 도구를 함께 제공합니다. promtool은 규칙 파일의 문법을 검사하고, 만든 시계열을 넣어 "몇 분에 어떤 알림이 울려야 한다"를 단위 시험으로 확인합니다. Alertmanager의 amtool은 라벨이 이러하면 어느 수신처로 가는지를 시험합니다. 이 글은 일부러 틀린 규칙과 설정, 고친 규칙과 설정을 같은 시험으로 돌려 결과를 비교하고, 도구가 어디까지 잡아 주는지 확인합니다.

준비물

항목 확인한 값
Docker 29.5.3 (Windows 11, Git Bash에서 실행)
promtool 2.51.0 (prom/prometheus:v2.51.0 이미지, 진입점을 promtool로 지정)
amtool 0.27.0 (prom/alertmanager:v0.27.0 이미지, 진입점을 amtool로 지정)

Prometheus와 Alertmanager 서버는 띄우지 않았습니다. 규칙과 설정 파일을 컨테이너에 마운트해 명령 하나씩만 실행하고 컨테이너는 바로 지워집니다. 작업 파일은 코드 폴더 밖의 osk-fb-prom-out에 두었습니다.

1. 시험할 규칙 두 개

알림 조건 기대
InstanceDown up == 0이 2분 이상 severity: critical
HighErrorRate 5xx 비율이 5%를 넘는 상태가 5분 이상 severity: warning

고친 규칙(rules_good.yml)과, 오타와 논리 오류를 넣은 규칙(rules_bad.yml)을 만들었습니다. 틀린 규칙에 넣은 결함은 셋입니다.

  • InstanceDown의 조건이 up == 1로 뒤집혀 있고 for가 없습니다.
  • severity가 critcal로 오타가 났습니다.
  • HighErrorRate의 임계값이 0.5로 10배 큽니다(5%가 아니라 50%).
이 단계의 파일 내려받기:rules_bad.ymlrules_good.yml

2. check rules: 문법은 잡고 논리는 못 잡습니다

문법 오류는 promtool check rules가 잡았습니다. 좋은 규칙에서 > 0.05를 > 로 잘라 낸 파일을 검사하자 could not parse expression: 1:87: parse error: unexpected end of input으로 오류 위치가 표시되고 종료 코드 1이 나왔습니다.

반면 틀린 규칙(rules_bad.yml)은 SUCCESS: 2 rules found로 통과했습니다. 뒤집힌 조건, 오타 난 라벨, 큰 임계값은 모두 문법상으로는 올바른 규칙이기 때문입니다. check rules가 통과했다는 사실은 규칙이 의도대로 동작한다는 뜻이 아니라 읽을 수 있다는 뜻입니다.

이 단계의 파일 내려받기:rules_bad.yml

3. test rules: 가짜 시계열로 동작을 시험합니다

단위 시험 파일(rules_test.yml)에는 네 가지 상황을 적었습니다.

시험 입력 기대
인스턴스가 죽으면 2분 뒤에 알림 up 값이 1 1 0 0 0 0 0(1분 간격) 1분과 3분에는 알림 없음, 5분에 critical 알림
살아 있으면 알림 없음 up 값이 계속 1 5분에 알림 없음
5xx 비율 9%는 5분 뒤 경고 200은 분당 100씩, 500은 분당 10씩 증가 12분에 warning 알림
5xx 비율 1% 미만은 알림 없음 500은 분당 1씩 증가 12분에 알림 없음

기대는 "알림이 있어야 한다"뿐 아니라 "없어야 한다"도 포함합니다. 1분과 3분 시점의 빈 기대값이 2분 조건의 for를 확인합니다.

같은 시험 파일로 두 규칙을 돌린 결과입니다.

규칙 어긋난 판정 종료 코드
rules_bad.yml 4건 1
rules_good.yml 0건 0

틀린 규칙에서는 1분 시점에 살아 있는 인스턴스의 알림이 울렸고(조건이 뒤집혀서), 5분 시점에는 죽은 인스턴스의 알림이 울리지 않았으며, 살아 있는 쪽 시험에서도 알림이 울렸고, 9% 오류에도 경고가 울리지 않았습니다. 라벨 오타(critcal)는 첫 시험의 기대 라벨과 달라 같은 줄에서 드러났습니다. 시험 4(1% 미만)는 틀린 규칙에서도 통과했는데, 임계값이 큰 규칙은 "울리지 말아야 할 때"의 시험으로는 잡히지 않는다는 것을 보여 줍니다. 시험은 결함이 있는 쪽의 경계를 건드려야 의미가 있습니다.

promtool check rules가 잘린 식에서 종료 코드 1을 내고, rules_bad.yml은 check를 통과하지만 test rules에서 어긋난 판정 4건과 종료 코드 1, rules_good.yml은 어긋난 판정 0건과 종료 코드 0인 것을 확인합니다.
promtool check rules가 잘린 식에서 종료 코드 1을 내고, rules_bad.yml은 check를 통과하지만 test rules에서 어긋난 판정 4건과 종료 코드 1, rules_good.yml은 어긋난 판정 0건과 종료 코드 0인 것을 확인합니다.

이 단계의 파일 내려받기:rules_bad.ymlrules_good.ymlrules_test.yml

4. amtool: 설정 검사와 라우팅 시험

Alertmanager는 알림을 라벨에 따라 수신처로 나눠 보냅니다. 기대하는 라우팅은 다음과 같습니다.

라벨 기대 수신처
severity=critical alertname=InstanceDown pager
severity=warning alertname=HighErrorRate team-chat
severity=info alertname=Other team-default(어느 쪽에도 안 맞으면 기본)

amtool config routes test --config.file=설정 라벨...은 해당 라벨이 갈 수신처 이름을 한 줄로 출력합니다. 두 설정으로 위 표를 검사했습니다.

설정 check-config 라우팅 어긋남
am_bad.yml(severity="critcal" 오타) SUCCESS 1 / 3
am_good.yml SUCCESS 0 / 3

오타 난 설정은 check-config를 통과했습니다. 다만 critical 알림은 pager로 가지 않고 기본 수신처 team-default로 갔습니다. 이것이 알림 설정에서 가장 조용한 사고로, 설정도 유효하고 알림도 어딘가로는 가지만 담당자는 못 받습니다. 라우팅 시험은 이 칸에서 어긋났다고 알려 줍니다.

반대로 team-chat 수신처 정의를 지운 파일(am_missing.yml)은 check-config가 undefined receiver "team-chat" used in route로 실패시켰습니다. 정의 누락은 도구가 직접 잡고, 라벨 오타 같은 의미 오류는 라우팅 시험이 잡습니다.

amtool config routes show는 라우팅 트리를 그려 줍니다. 좋은 설정에서는 기본 경로 아래에 severity="critical" → pager, severity="warning" → team-chat이 한 단계씩 나왔습니다.

amtool check-config가 수신처를 빠뜨린 설정을 실패시키고, am_bad.yml은 critical이 team-default로 가서 1칸 어긋나며, am_good.yml은 0칸 어긋나고 라우팅 트리가 표시되는 것을 확인합니다.
amtool check-config가 수신처를 빠뜨린 설정을 실패시키고, am_bad.yml은 critical이 team-default로 가서 1칸 어긋나며, am_good.yml은 0칸 어긋나고 라우팅 트리가 표시되는 것을 확인합니다.

이 단계의 파일 내려받기:am_bad.ymlam_good.yml

5. 파이프라인에 넣을 때

네 가지 검사를 순서대로 두면 됩니다. promtool check rules, promtool test rules, amtool check-config, 라우팅 표 검사입니다. 하나라도 비정상 종료하면 병합을 막습니다. 이 글은 이 순서를 한 스크립트로 묶어 실행했을 뿐 CI 설정을 만들지는 않았습니다.

이 단계의 파일 내려받기:alert_demo.sh

전체 코드

전체를 한 번에 돌리는 스크립트입니다. 아래 파일과 같은 폴더에서 실행합니다.

# alert_demo.sh
#!/usr/bin/env bash
# promtool 로 알림 규칙의 문법과 동작을 시험하고, amtool 로 라벨별 수신처(라우팅)를 시험한다. 서버는 띄우지 않는다.
# 준비: Docker (prom/prometheus:v2.51.0, prom/alertmanager:v0.27.0), 같은 폴더에 rules_good.yml, rules_bad.yml, rules_test.yml, am_good.yml, am_bad.yml.
# 실행(Git Bash): bash alert_demo.sh   (약 20초)
export MSYS_NO_PATHCONV=1
HERE="$(pwd)"
OUT=../osk-fb-prom-out                       # 작업 폴더는 이 폴더 밖에 둔다
rm -rf "$OUT"; mkdir -p "$OUT"; ABS="$(cd "$OUT" && pwd)"
PT() { docker run --rm -v "$ABS:/w" --entrypoint promtool prom/prometheus:v2.51.0 "$@"; }
AT() { docker run --rm -v "$ABS:/w" --entrypoint amtool prom/alertmanager:v0.27.0 "$@"; }
cp "$HERE/rules_test.yml" "$ABS/rules_test.yml"

echo "## 1. 문법 오류는 check rules 가 잡는다"
sed 's/> 0.05/> /' "$HERE/rules_good.yml" > "$ABS/rules.yml"
PT check rules /w/rules.yml 2>&1 | sed 's/^/  /' | cut -c1-150; echo "  종료 코드 ${PIPESTATUS[0]}"

echo "## 2. 논리 오류는 check 를 통과하고 test rules 가 잡는다"
for v in bad good; do
  cp "$HERE/rules_$v.yml" "$ABS/rules.yml"
  echo "### rules_$v.yml"
  PT check rules /w/rules.yml 2>&1 | sed 's/^/  /'
  PT test rules /w/rules_test.yml > "$ABS/test_$v.txt" 2>&1; rc=$?
  grep -E '^ +name: |SUCCESS' "$ABS/test_$v.txt" | sed 's/^ */  /; s/,$//; s/^  name:/  실패한 시험:/'
  grep -E 'alertname: [A-Za-z]+, time' "$ABS/test_$v.txt" | sed 's/^ */    어긋난 판정 /; s/, $//'
  echo "  어긋난 판정 합계 $(grep -cE 'alertname: [A-Za-z]+, time' "$ABS/test_$v.txt")건"
  echo "  test rules 종료 코드 $rc"
done

echo "## 3. Alertmanager 설정과 라우팅"
sed '/name: team-chat/,$d' "$HERE/am_good.yml" > "$ABS/am_missing.yml"
cp "$HERE/am_good.yml" "$ABS/am_good.yml"; cp "$HERE/am_bad.yml" "$ABS/am_bad.yml"
echo "### 수신처를 빠뜨린 설정"
AT check-config /w/am_missing.yml 2>&1 | grep -E 'FAILED|error|SUCCESS' | cut -c1-160 | sed 's/^/  /'
ROUTES=("severity=critical alertname=InstanceDown|pager" "severity=warning alertname=HighErrorRate|team-chat" "severity=info alertname=Other|team-default")
for v in bad good; do
  echo "### am_$v.yml 라우팅"
  AT check-config /w/am_$v.yml 2>&1 | grep -E 'SUCCESS|FAILED' | sed 's/^/  /'
  mis=0
  for r in "${ROUTES[@]}"; do
    labels="${r%%|*}"; want="${r##*|}"
    got=$(AT config routes test --config.file=/w/am_$v.yml $labels | tr -d '\r')
    mark="  "; [ "$got" != "$want" ] && { mark="X "; mis=$((mis+1)); }
    printf "  %s%-45s 기대 %-12s 실제 %s\n" "$mark" "$labels" "$want" "$got"
  done
  echo "  어긋난 칸 $mis / ${#ROUTES[@]}"
done
echo "## 4. 라우팅 트리(좋은 설정)"
AT config routes show --config.file=/w/am_good.yml | sed 's/^/  /'
echo "## 끝"

고친 알림 규칙입니다.

rules_good.yml

groups:
  - name: lab
    rules:
      - alert: InstanceDown
        expr: up == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "{{ $labels.instance }} 가 2분 넘게 응답하지 않습니다"
      - alert: HighErrorRate
        expr: sum(rate(http_requests_total{code=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "5xx 비율이 5%를 넘었습니다"

결함을 넣은 알림 규칙입니다(뒤집힌 조건, 오타, 큰 임계값).

rules_bad.yml

groups:
  - name: lab
    rules:
      - alert: InstanceDown
        expr: up == 1
        labels:
          severity: critcal
        annotations:
          summary: "{{ $labels.instance }} 가 2분 넘게 응답하지 않습니다"
      - alert: HighErrorRate
        expr: sum(rate(http_requests_total{code=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) > 0.5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "5xx 비율이 5%를 넘었습니다"

두 규칙에 같이 쓰는 단위 시험 파일입니다.

rules_test.yml

rule_files:
  - rules.yml
evaluation_interval: 1m
tests:
  - name: 인스턴스가 죽으면 2분 뒤에 알림
    interval: 1m
    input_series:
      - series: 'up{job="web", instance="a:80"}'
        values: '1 1 0 0 0 0 0'
    alert_rule_test:
      - eval_time: 1m
        alertname: InstanceDown
        exp_alerts: []
      - eval_time: 3m
        alertname: InstanceDown
        exp_alerts: []
      - eval_time: 5m
        alertname: InstanceDown
        exp_alerts:
          - exp_labels:
              severity: critical
              job: web
              instance: "a:80"
            exp_annotations:
              summary: "a:80 가 2분 넘게 응답하지 않습니다"
  - name: 살아 있으면 알림 없음
    interval: 1m
    input_series:
      - series: 'up{job="web", instance="a:80"}'
        values: '1 1 1 1 1 1 1'
    alert_rule_test:
      - eval_time: 5m
        alertname: InstanceDown
        exp_alerts: []
  - name: 5xx 비율 9퍼센트는 5분 뒤 경고
    interval: 1m
    input_series:
      - series: 'http_requests_total{code="200"}'
        values: '0+100x15'
      - series: 'http_requests_total{code="500"}'
        values: '0+10x15'
    alert_rule_test:
      - eval_time: 12m
        alertname: HighErrorRate
        exp_alerts:
          - exp_labels:
              severity: warning
            exp_annotations:
              summary: "5xx 비율이 5%를 넘었습니다"
  - name: 5xx 비율 1퍼센트 미만은 알림 없음
    interval: 1m
    input_series:
      - series: 'http_requests_total{code="200"}'
        values: '0+100x15'
      - series: 'http_requests_total{code="500"}'
        values: '0+1x15'
    alert_rule_test:
      - eval_time: 12m
        alertname: HighErrorRate
        exp_alerts: []

고친 Alertmanager 설정입니다.

am_good.yml

route:
  receiver: team-default
  group_by: [alertname]
  routes:
    - matchers: ['severity="critical"']
      receiver: pager
    - matchers: ['severity="warning"']
      receiver: team-chat
receivers:
  - name: team-default
    webhook_configs: [{url: "http://127.0.0.1:9/default"}]
  - name: pager
    webhook_configs: [{url: "http://127.0.0.1:9/pager"}]
  - name: team-chat
    webhook_configs: [{url: "http://127.0.0.1:9/chat"}]

라벨에 오타가 있는 Alertmanager 설정입니다.

am_bad.yml

route:
  receiver: team-default
  group_by: [alertname]
  routes:
    - matchers: ['severity="critcal"']
      receiver: pager
    - matchers: ['severity="warning"']
      receiver: team-chat
receivers:
  - name: team-default
    webhook_configs: [{url: "http://127.0.0.1:9/default"}]
  - name: pager
    webhook_configs: [{url: "http://127.0.0.1:9/pager"}]
  - name: team-chat
    webhook_configs: [{url: "http://127.0.0.1:9/chat"}]

자주 막히는 곳

증상 원인 해결
promtool 실행이 이미지 기본 명령(prometheus)으로 시작함 이미지 진입점이 서버 --entrypoint promtool
시험에서 rule_files를 못 찾음 규칙 파일 경로가 시험 파일 기준 시험 파일과 같은 폴더에 rules.yml로 복사
check rules가 통과했는데 알림이 안 울림 문법이 맞아도 논리가 틀릴 수 있음 test rules로 기대값 확인
check-config가 통과했는데 담당자가 알림을 못 받음 라벨 오타로 기본 수신처로 감 amtool config routes test로 라벨별 수신처 확인

확인 범위

  • 해 본 것: 2026-10-30, Windows 11 · Docker 29.5.3 · promtool 2.51.0 · amtool 0.27.0에서 문법 오류 검사(종료 코드 1), 논리 오류가 있는 규칙의 check(통과)와 test rules(어긋난 판정 4건, 종료 코드 1), 고친 규칙의 시험(0건, 종료 코드 0), 수신처 누락 설정의 check-config(실패), 라벨 오타 설정의 라우팅 시험(1 / 3), 고친 설정의 시험(0 / 3), 라우팅 트리 출력을 확인했습니다. 전체 스크립트를 세 번 실행해 출력이 완전히 같았습니다.
  • 해 보지 않은 것: Prometheus와 Alertmanager 서버를 띄운 실제 발송, 그룹화와 억제(inhibit), 침묵(silence), 알림 템플릿 렌더링 확인, keep_firing_for, 녹화 규칙(recording rule)의 시험, 이메일과 메신저 연동, 다른 버전, Linux와 macOS.
  • 읽을 때 주의: 시험 시계열은 직접 만든 숫자이며 실제 서비스의 값이 아닙니다. 수신처 주소는 시험용 로컬 주소이고 어디로도 발송하지 않았습니다. 출력 문구는 위 버전 기준입니다.

이 글은 스타트업·소규모 조직 보안 구축 로드맵의 한 단계입니다.

이 글의 다음 단계

  • Loki로 nginx 로그 모으고 LogQL로 조회하기: 라벨 설계와 개인정보 마스킹nginx 접근 로그 하나를 Promtail 설정 두 개로 Loki 두 대에 보냅니다. 요청 주소와 IP를 라벨로 만든 나쁜 설정은 스트림이 11개로 늘고 이메일과 토큰이 그대로 저장되며, 좋은 설정은 스트림 1개에 마스킹된 줄만 저장합니다. 5xx 개수와 401 반복 IP를 LogQL로 세고, 점검 결과를 종료 코드로 바꿉니다.
  • matplotlib 그래프 그리기: 막대, 선, 히스토그램 기초로그인 시도 CSV 600건으로 matplotlib 막대 그래프, 선 그래프, 히스토그램을 하나씩 그리고 savefig로 PNG를 저장합니다. 한글이 깨질 때 나오는 경고와 Malgun Gothic 글꼴 설정까지 실제 출력으로 정리합니다.

이 내용을 팀 교육으로 진행하고 싶으신가요?

인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.

교육 문의하기

교육 진행 순서와 자주 묻는 질문 보기

팀이나 교육 담당자에게 이 글 제안하기

메일로 보내실 수도 있습니다: fankh111@gmail.com

같은 카테고리의 글