에이전트 운영Agent operations

pidfile-process-watchdog

pid 파일과 작업 폴더로 서비스 상태를 판정하는 작은 감시 도구입니다. 유예 시간, 플랩 경고, 포기 규칙이 있습니다.

어떤 문제를 푸나The problem

추측으로 재시작하면 막으려던 장애를 오히려 만듭니다. 이 감시자는 pid 파일의 프로세스가 살아 있고 그 작업 폴더가 서비스 루트일 때만 정상으로 봅니다. 확인할 수 없을 때는 아무것도 하지 않고, 죽었을 때만 재시작합니다.

재시작 직후에는 유예 시간을 두고, 연속 재시작이 실패하면 무한 반복하지 않고 포기를 알립니다.

이런 분께 맞습니다Who it is for

봇이나 데몬을 직접 돌리면서 이미 쓰는 스케줄러에 붙일 간단한 점검기가 필요한 사람.

무엇을 하나What it does

상태는 HEALTHY, DEAD, UNKNOWN 중 하나이고 UNKNOWN에서는 행동하지 않습니다.
동작은 none, wait, restart, restart+flapping, giveup입니다.
--grace, --give-up-after, --flap-per-hour로 규칙을 조절하고 --dry-run으로 판단만 확인합니다.
재시작 명령이 실패하면 종료 코드 3입니다. 확인 불가는 stderr에 한 줄 남깁니다.

직접 돌려 본 출력Real output

저장소의 examples 폴더를 실행한 결과입니다.

$ python3 examples/quickstart.py
t=0    healthy                  -> none
t=60   cannot inspect           -> none
t=120  dies                     -> restart
t=150  still dead, in grace     -> wait
t=260  still dead, grace over   -> restart
t=400  still dead               -> restart
t=540  still dead               -> giveup
t=700  recovers                 -> none

알아둘 한계Limits

pid 파일이 있는 서비스를 가정합니다. Linux는 /proc, 그 밖에는 lsof로 작업 폴더를 확인합니다.
--restart-cmd는 셸로 실행되므로 신뢰할 수 없는 입력으로 만들지 마십시오.

받아서 쓰기Get it

# 저장소를 받습니다
git clone https://github.com/Kein-chronicle/pidfile-process-watchdog.git

# Claude Code 스킬로 쓰려면 이 폴더 이름으로 받습니다
git clone https://github.com/Kein-chronicle/pidfile-process-watchdog.git ~/.claude/skills/service-health-watchdog

정보Info

분류Category: 에이전트 운영Agent operations
형태Type: 명령줄 도구Command-line tool
라이선스License: MIT
필요한 것Requires: Python 3.10 이상
저장소Repository: pidfile-process-watchdog
토픽Topics: watchdog process-supervision devops macos linux launchd reliability claude-code

2026-10-18 기준: 저장소의 테스트를 로컬에서 실행해 통과했고, 예제 출력은 저장소의 examples 폴더를 실제로 실행한 결과입니다.