AI 에이전트를 위한 헬스 모니터를 구축했습니다 — 이제 에이전트들이 죽어갈 때 저에게 알려줍니다

2주 동안, 저의 AI 콘텐츠 파이프라인(pipeline)은 소리 없이 고장 나 있었습니다.

크론 잡(cron job)은 여전히 실행 중이었고, 로그에는 "SUCCESS"라고 표시되었습니다. 하지만 실제로는 어떤 기사도 게시되지 않았습니다. Dev.to API는 429 오류(rate limited, 속도 제한)를 반환하고 있었지만, 제가 응답 상태(response status)를 확인하는 것을 잊었기 때문에 스크립트가 해당 오류를 삼켜버린 것이었습니다.

우연히 블로그를 확인하다가 게시물이 비어 있는 것을 보고서야 비로소 알아차렸습니다. 2주 동안 게시물이 누락되었습니다. 시스템이 조용히 실패하고 있는 동안, 모든 것이 괜찮다고 생각하며 보낸 2주였습니다.

그 순간 깨달았습니다: 나의 에이전트들에게는 맥박(pulse)이 필요하다는 것을 말이죠.

문제: 소리 없는 실패는 최악의 실패다

저는 세 대의 머신에서 세 개의 AI 에이전트를 실행합니다. Mac Mini에서는 Celebi를, Windows PC에서는 ProgrammierMinna를, 그리고... 역시 Mac Mini에서는 DocMinna를 실행합니다. 이들은 단순한 라우터(router)를 통해 연결되어 있고, 크론 잡(cron job)에 의해 트리거되며, Telegram을 통해 저에게 메시지를 보냅니다.

모든 것이 제대로 작동할 때는 마법 같습니다. 하지만 무언가 고장 나면, 그것은 고고학 작업이 됩니다.

제가 겪었던 일반적인 실패 모드들은 다음과 같습니다:

• Ollama가 Windows 업데이트 이후 Windows PC에서 충돌함. 아무도 몰랐습니다. 쿼리(queries)는 그냥 타임아웃(timed out)되었습니다.
• 모델 파일이 계속 쌓이면서 Mac Mini의 디스크가 가득 참. 로그 로테이션(logs rotating)이 중단되었습니다. 시스템이 멈춰버렸습니다.
• Dev.to의 API 속도 제한 (API rate limits) (하루 최대 10개 게시물). 게시 스크립트가 재시도하거나 알림을 보내지 않았습니다.
• 라우터 재시작 후 라우터 설정 오류. Windows PC가 새로운 IP를 할당받았습니다. 쿼리들이 허공으로 사라졌습니다.
• 모델은 다운로드(pulled)되었으나 로드(loaded)되지 않음. 모델을 업데이트하고 Ollama를 재시작했지만, 실제로 ollama run을 실행하는 것을 잊었습니다. 첫 번째 쿼리에서 오류가 발생했습니다.

이 각각의 문제들을 진단하는 데 20~60분이 걸렸습니다. 문제가 어려워서가 아니라, 어디를 살펴봐야 할지 몰랐기 때문입니다.

해결책: 30줄짜리 헬스 체크 스크립트

저는 Prometheus를 구축하지 않았습니다. Grafana를 설치하지도 않았습니다. 대신 10분마다 실행되며, 제가 신경 쓰는 항목들을 확인하고, 문제가 발생하면 Telegram 메시지를 보내주는 Python 스크립트를 작성했습니다.

그게 전부입니다. 대시보드도 없고, 메트릭 서버 (metrics server)도 없습니다. 그저 "문제가 생기면 알려줘"라고 했을 뿐입니다.

# health_check.py
import requests
import shutil
...

총 의존성: requests (아마 이미 설치되어 있을 것입니다). 총 라인 수: 약 50줄. 총 설정 시간: 10분.

실제로 모니터링하는 항목들

1. Ollama 하트비트 (Heartbeat)

가장 중요한 체크 항목입니다. 10분마다 모든 머신에 /api/tags로 핑 (ping)을 보냅니다. 5초 이내에 응답이 없으면, 머신 이름과 함께 Telegram 알림을 받습니다.

지난주에 Windows 업데이트로 인한 재부팅을 이 기능 덕분에 잡아낼 수 있었습니다. PC는 다시 켜졌지만, Ollama가 시작되지 않았던 것입니다 (아직 시작 프로그램에 등록하지 않았었습니다). 실제로 필요할 때 알게 되는 대신, 10분 이내에 문제를 파악할 수 있었습니다.

2. 모델 존재 여부 (Model Presence)

Ollama가 실행 중이더라도, 제가 필요한 모델이 로드되어 있지 않을 수 있습니다. 저는 세 가지 핵심 모델(qwen3.5:9b, qwen3-coder:30b, granite3.2:8b)이 각 머신에서 사용 가능한지 확인합니다.

한번은 qwen3-coder를 업데이트했을 때 이 기능 덕분에 위기를 넘겼습니다. 새 버전의 태그 (tag)가 달랐고, 이전 태그는 사라진 상태였습니다. 라우터 (router)가 존재하지 않는 대상을 가리키고 있었던 것이죠. 모니터가 첫 번째 쿼리 (query)가 실패하기 전에 이를 잡아냈습니다.

3. 디스크 공간 (Disk Space)

모델 파일은 용량이 매우 큽니다. 30B 파라미터 모델은 약 20GB에 달합니다. 머신 3대에 각각 모델 3개씩 있다면, 조용히 늘어나는 엄청난 저장 공간이 필요합니다. 저는 디스크 사용량이 90%에 도달하면 알림을 받습니다.

Mac Mini는 256GB SSD를 사용합니다. 한 번은 95%에 도달했는데, 시스템이 공격적으로 스와핑 (swapping)을 시작했습니다. 응답 시간이 2초에서 30초로 늘어났죠. 이제는 문제가 생기기 전에 정리합니다.

4. 파이프라인 활성 상태 (Pipeline Liveness)

이것은 미묘한 부분입니다. 크론 잡 (cron job)은 실행되고 있지만, 실제로 무언가를 하고 있느냐는 것이죠. 저는 기사가 성공적으로 게시될 때마다 타임스탬프 (timestamp) 파일을 작성합니다. 헬스 체크는 그 타임스탬프를 "현재"와 비교합니다. 만약 3일 이상 경과했다면 알림을 받습니다.

이 기능은 조용한 429 에러 (429 errors)를 잡아낼 수 있었을 것입니다. 스크립트는 실행되고 있었지만, 게시를 하지 못하고 있었던 상황 말이죠. 타임스탬프가 업데이트되지 않았을 것이고, 저는 바로 알 수 있었을 것입니다.

5. 라우터 도달 가능성 (Router Reachability) (보너스)

게이트웨이 라우터(gateway router) 자체에 핑(ping)을 보내는 체크 항목을 추가했습니다. 네트워크 전체가 다운되면 다른 종류의 알림을 받게 됩니다. 정전 중에 이런 일이 한 번 있었는데, 라우터가 머신들보다 더 빨리 재부팅되었지만 DHCP가 IP를 재할당했습니다. 저는 무엇인가를 쿼리(query)하려고 시도하기도 전에 네트워크가 불안정하다는 것을 알 수 있었습니다.

의도적으로 모니터링하지 않는 것들

저는 데이터 센터(datacenter)를 운영하는 것이 아닙니다. 제가 의도적으로 확인하지 않는 것들이 있습니다:

• GPU 온도. 제 RTX 3060은 순정 쿨러(stock cooler) 상태로도 아주 잘 작동합니다. 만약 스로틀링(throttling)이 발생한다면 응답 시간(response times)을 통해 알 수 있을 것입니다. 온도 모니터링을 추가하는 것은 센서, 드라이버, 더 많은 코드를 의미합니다. 그럴 가치가 없습니다.
• 네트워크 대역폭 (Network bandwidth). 저는 비디오 스트리밍을 하는 것이 아닙니다. 로컬 네트워크 지연 시간(latency)은 결코 병목 현상(bottleneck)이 되지 않습니다.
• CPU 부하 (CPU load). Mac Mini는 대부분의 시간 동안 15% 상태를 유지합니다. 부하가 급증하더라도 지속적이지 않다면 상관하지 않습니다. 지속된다면 Ollama의 응답 시간이 저에게 알려줄 것입니다.
• 로그 집계 (Log aggregation). 무언가 고장 나면 로그를 읽습니다. 로그를 Elasticsearch로 전송할 필요는 없습니다.

규칙은 이렇습니다: 실패 모드(failure mode)가 디버깅하기 짜증스러운 상황이라면 모니터링하십시오. 단순히 "알면 좋은" 정도라면 건너뛰십시오.

실행 방식

스크립트는 Mac Mini에서 systemd 타이머(systemd timer)로 실행됩니다. 10분마다 상태를 확인하며, 문제가 있으면 Telegram으로 알림을 보냅니다. 모든 것이 정상이라면 아무 일도 일어나지 않습니다. 조용한 성공이 목표입니다.

# /etc/systemd/system/ai-health-check.timer
[Unit]
Description=AI Agent Health Check
...

# /etc/systemd/system/ai-health-check.service
[Unit]
Description=Run AI health check
...

sudo systemctl enable ai-health-check.timer
sudo systemctl start ai-health-check.timer

설정하는 데 30초가 걸립니다. 그리고 영원히 실행됩니다.

무엇이 변했는가 (솔직한 버전)

문제가 심각해지기 전에 해결합니다. Windows PC 문제는 알림을 받은 지 10분 이내에 해결되었습니다. 모니터링을 하기 전이었다면, "왜 오늘따라 이 쿼리가 이렇게 느리지?"라고 의문을 가진 뒤 20분 동안 ssh 접속과 로그 읽기에 매달려야 했을 것입니다.

저는 시스템을 더 신뢰합니다. "작동하고 있는 것 같다"와 "모니터가 초록색이니까 작동하고 있다는 것을 안다" 사이에는 큰 차이가 있습니다. 덕분에 걱정하는 대신 구축하는 데 집중할 수 있습니다.

하지만 원치 않는 알림도 더 많이 받습니다. Ubuntu 박스가 WiFi를 사용 중이라 가끔 30초 정도 연결이 끊깁니다. 그러면 "도달할 수 없음 (unreachable)" 알림이 오고, 10분 뒤에는 다시 괜찮아집니다. 임계값 (thresholds)을 아직 조정하지 않았는데... 솔직히 말해서, 수정할 만큼 짜증 나지는 않기 때문입니다.

오탐 (False positives)도 존재합니다. 한 번은 재시작 후 Ollama가 여전히 로딩 중이라 모델 체크가 실패한 적이 있습니다. 모델은 존재했지만, /api/tags가 15초 동안 빈 리스트를 반환했습니다. 5초 재시도 (retry) 로직을 추가했더니 문제가 해결되었습니다.

이것이 중요한 경우 (그리고 그렇지 않은 경우)

이런 분들은 하세요:

• 감독 없이 실행되는 자동화된 프로세스를 운영 중인 경우
• "잠깐, 이게 언제부터 고장 난 거지?"라고 당황했던 경험이 있는 경우
• 어차피 Telegram (또는 Slack, 이메일)을 사용하는 경우
• 완벽한 지표 (metrics)보다 문제 발생 사실을 아는 것을 더 가치 있게 여기는 경우

이런 분들은 하지 마세요:

• 여전히 매일 수동으로 설정을 디버깅하고 있는 경우 (먼저 핵심 문제부터 해결하세요)
• 아름다운 대시보드를 원하는 경우 (대신 Prometheus + Grafana를 사용하세요)
• 갑작스러운 장애가 주는 스릴을 즐기는 경우

진짜 교훈

최고의 모니터링은 모든 것을 알려주는 것이 아닙니다. 당신이 실제로 알아야 할 것을, 당신이 여전히 조치를 취할 수 있는 시점에 알려주는 것입니다.

저의 50줄짜리 스크립트는 대단하지 않습니다. DevOps로서의 명성을 가져다주지도 않을 것입니다. 하지만 첫 달에 세 번의 실제 문제를 잡아냈고, 비용은 오후 시간 외에는 전혀 들지 않았습니다.

집에서 AI 에이전트를 실행하고 있는데 언제 고장 나는지 모른다면... 당신은 그냥 언제 고장 나는지 모르는 상태인 것입니다. 그것부터 해결하세요. 그 외의 모든 것은 최적화 (optimization)일 뿐입니다.

Sam Hartley는 모니터링 시스템이 갖춰진 3대의 머신으로 AI 홈 랩을 운영하는 1인 개발자입니다. 로컬 AI를 실제로 신뢰할 수 있게 만드는 지루한 인프라에 대해 글을 씁니다.

→ Fiverr에서 커스텀 자동화 설정하기
→ Telegram에서 CelebiBots 팔로우하기

#ai #에이전트 #모니터링 #데브옵스 #셀프호스팅 #홈랩 #공개개발