워치독 점검법

작성일: 2026-10-19 · 대상: 국가 라인 워치독 루프(_watchdog_*.sh), 메타워치독(_meta_watchdog1.sh), 국가 팀장 워치독(country_watchdog.py)

1. 워치독이 하는 일

워치독은 수집기를 감싸는 루프다. 한 사이클 실행 후 대기하고 다시 실행한다. 수집기가 죽어도 다음 사이클에 살아난다. 이 루프는 Claude를 호출하지 않는다(토큰 0원). 관측 수단은 로그뿐이다.

2. 점검 순서

# ① 루프 프로세스가 있는가 (라인 마커로 검색)
ps aux | grep -E '_watchdog|meta_watchdog' | grep -v grep

# ② 로그가 최근에 찍히는가
ls -lt ~/raker_logs/*/watchdog_*.log | head
tail -3 ~/raker_logs/th/watchdog_$(date +%Y%m%d).log

# ③ 수집기가 실제로 일하는가
ps aux | grep raker_g_ | grep -v grep | wc -l

①은 있는데 ②가 오래 멈춰 있으면 루프가 정지했다. 워치독이 "살아 있다"는 것과 수집이 "돌고 있다"는 것은 다르다.
워치독 스크립트가 맞는 로그를 쓰는지 확인한다. 로그가 다른 라인 이름이면 마커가 겹친 것일 수 있다.

3. 중복 기동 방지

기동 스크립트는 pgrep으로 같은 마커가 이미 떠 있으면 다시 띄우지 않는다. 마커 이름이 다른 라벨의 접두어면 짧은 쪽 재기동이 영구 차단된다(BD 사례). 마커는 고유한 긴 이름으로 정한다.
재부팅 후 자동 기동이 필요하면 launchd에 등록한다. 등록하지 않은 워치독은 재부팅 후 영구 정지한다(2026-08 사례).

4. 시작 지연(jitter) — 필수

여러 워치독이 같은 순간에 동시에 깨어나면 저장소가 몰린다(2026-08-07 사고). 새 루프는 첫 사이클 전에 무작위 지연을 넣는다.

sleep $((RANDOM % 300))     # 0~5분 분산
for i in $(seq 1 300); do
  python3 raker_....py >> log 2>&1
  sleep 1800
done

crontab에 넣을 때는 %를 \%로 이스케이프한다. 빠뜨리면 명령이 중간에 잘린다(2026-09-02 사고).

5. 메타워치독 (워치독의 워치독)

_meta_watchdog1.sh는 죽은 라인 워치독을 감지해 라인의 기존 기동 스크립트를 그대로 다시 호출한다. 감지 로직을 따로 만들지 않는다. 기대 수량을 절대값으로 지정해야 한다(--expected-min). 변동 여부만 보면 재기동 자체가 실패해도 정상으로 오판한다.

6. 국가 팀장 워치독 (country_watchdog.py)

국가별 기관 목록을 주기적으로 조회해, 처리 중인 워커가 없는 기관에 워커를 배정한다. 호스트 설정(HOST_CONFIG)의 이름이 새 함대 명칭과 다를 수 있다. 2026-09-17 재편성 이후에는 호스트 키와 실제 기기를 확인하고 나서 배정한다(~/.ssh/config 별칭 기준).

7. 금지 사항

D 상태(디스크 대기) 프로세스가 있다고 바로 죽이지 않는다. 경합일 수 있다.
"정상 진행 중"이라는 자기보고만으로 확정하지 않는다. 로그 타임스탬프로 확인한다.
워치독이 떠 있어도 로그가 멈추면 "가동 중"으로 적지 않는다.