# Prometheus 알림 규칙 promtool 단위 시험

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

- 주소: https://copyandrun.com/blog/prometheus-alert-rules-promtool-test/
- 분야: SIEM·보안관제
- 발행일: 2026-10-30
- 태그: Prometheus, promtool, Alertmanager, 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%).

## 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`가 통과했다는 사실은 규칙이 의도대로 동작한다는 뜻이 아니라 읽을 수 있다는 뜻입니다.

## 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인 것을 확인합니다.](https://copyandrun.com/img/prometheus-alert-rules-promtool-test/01-promtool-check-test.png)

## 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칸 어긋나고 라우팅 트리가 표시되는 것을 확인합니다.](https://copyandrun.com/img/prometheus-alert-rules-promtool-test/02-amtool-라우팅.png)

## 5. 파이프라인에 넣을 때

<!-- files: alert_demo.sh -->

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

## 전체 코드

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

```bash
# 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`

```yaml
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`

```yaml
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`

```yaml
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`

```yaml
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`

```yaml
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.
- **읽을 때 주의:** 시험 시계열은 직접 만든 숫자이며 실제 서비스의 값이 아닙니다. 수신처 주소는 시험용 로컬 주소이고 어디로도 발송하지 않았습니다. 출력 문구는 위 버전 기준입니다.
