인터랙티브 매뉴얼 · Antigravity Server Monitor

이 시스템은 어떻게 동작하나요?

감시할 각 서버에 에이전트 1개를 두면, 서버 상태를 스스로 모아 중앙 백엔드로 밀어(push) 보냅니다. 아래 각 단계를 눌러 역할을 확인하세요.

host-agent감시 대상 서버마다 1개

→POST · 5초마다

monitor 백엔드중앙 수집·저장·판정

→

대시보드 · 텔레그램보기와 알림

꼭 알아둘 5가지 개념

Push 단방향

백엔드가 서버로 접속하지 않습니다. 에이전트가 밖으로 내보내기만 하므로 감시 대상 서버에 인바운드 포트를 열 필요가 없습니다.

자동 등록

사전 등록 절차가 없습니다. 에이전트가 첫 전송을 하는 순간 호스트·서비스가 대시보드에 자동으로 나타납니다.

전송 버퍼링

백엔드가 잠깐 꺼져도 에이전트는 데이터를 메모리에 기본 10분치 보관했다가 복구 시 원래 시각 그대로 재전송 — 그래프에 공백이 없습니다.

상태 레벨

모든 지표를 ok warn crit offline 네 단계로 판정합니다. 아래 임계값 표 참고.

전이 기반 알림

임계값을 넘을 때마다가 아니라 상태가 바뀌는 순간에만 1회 알립니다. 같은 상태가 이어지면 조용합니다(스팸 방지).

상태 레벨과 임계값

백엔드가 이 기준으로 주의·위험을 판정하고, 전이 시 텔레그램으로 알립니다.

대상	주의 (warn)	위험 (crit)
호스트 CPU / MEM / DISK?	≥ 75%	≥ 90%
서비스 상태(status)?	degraded · restarting · unhealthy	down · exited · dead
컨테이너?	재시작 ≥ 5회, 메모리 ≥ 75%	정지 상태, 메모리 ≥ 90%, unhealthy
PostgreSQL 캐시 히트율?	< 95%	< 90%
PostgreSQL 데드락?	> 0	≥ 5
PostgreSQL 죽은 튜플 비율?	≥ 10%	≥ 25%
PG/MySQL 연결 사용률?	≥ 80%	≥ 95%
Redis 히트율?	< 95%	< 90%
HTTP 앱 상태 코드?	4xx	5xx
HTTP 앱 응답 지연?	≥ 1,000ms	≥ 3,000ms
호스트 오프라인?	마지막 수신 후 15초 초과 (알림은 60초 연속 미수신 시 확정)

구조를 이해했다면 다음 단계로 — 2. 적용하기에서 내 서버에 맞는 설정 파일을 폼으로 바로 만들 수 있습니다.

에이전트 설치하고 설정 만들기

감시할 서버마다 에이전트를 내려받아 두고, 아래 폼으로 만든 .env·services.json과 함께 start.sh로 실행하면 됩니다.

↓1. 에이전트 내려받기

실행은 start.sh / stop.sh 하나로 합니다. start.sh가 소스를 빌드해서 실행하므로, 아래 소스 번들을 받아 감시할 서버(Go 1.21+ 설치)에 두면 됩니다.

소스 번들 · host-agent-src.tar.gzstart.sh · stop.sh · 소스 · 설정 예시 포함 — start.sh 실행에 사용23 KB

서버에 Go를 설치할 수 없다면 — 사전 빌드 실행파일

Go를 못 까는 서버라면 아래 실행파일을 받아 start.sh 없이 바로 실행할 수 있습니다. 서버 아키텍처 확인: uname -m → x86_64=amd64, aarch64=arm64.

Linux · amd64Intel/AMD 64비트7.3 MB Linux · arm64ARM64 · Graviton6.8 MB

# 받은 파일을 host-agent로 이름 변경 후, .env·services.json과 같은 폴더에서 실행
mv host-agent-linux-amd64 host-agent && chmod +x host-agent
nohup ./host-agent > host-agent.log 2>&1 &
# 중지: kill $(cat host-agent.pid) — 또는 소스 번들의 ./stop.sh 사용

무결성 확인(선택): SHA256SUMS.txt 내려받아 shasum -a 256 -c SHA256SUMS.txt

받은 뒤: ① tar xzf host-agent-src.tar.gz로 풀기 → ② 그 폴더에 아래에서 만든 .env·services.json 저장 → ③ 아래 "실행 방법"의 ./start.sh로 실행

2백엔드 연결

수집 서버 주소*?monitor 백엔드 URL (경로 포함)

API 키*?

호스트명?유일해야 함

수집 주기(초)?15초 미만

주기 로그?

3감시할 서비스

이 서버 위에서 도는 서비스를 추가하세요. 없으면 시스템 자원만 수집합니다.

4실행 방법 — start.sh / stop.sh

빌드부터 백그라운드 실행까지 ./start.sh 하나로, 중지는 ./stop.sh로 합니다. 두 스크립트가 실행 중복·PID·종료를 알아서 처리합니다. 서버에 Go 1.21+ 필요(소스에서 빌드).

./start.sh① 이미 실행 중인지 확인(PID) → ② services.json·.env 존재 확인 → ③ go build로 빌드 → ④ nohup으로 백그라운드 실행, PID 기록, 로그는 host-agent.log

./stop.shPID로 정상 종료 신호 전송 → 최대 5초 대기 → 그래도 살아 있으면 강제 종료 → PID 파일 정리

.env환경 설정 · 비밀은 여기에

services.json감시 서비스 정의

실행 명령

대시보드와 알림 사용하기

http://서버주소:8009/ — 로그인 없이 접근하며 5초마다 자동 갱신됩니다. 새로고침이 필요 없습니다.

호스트 카드 읽는 법

● Online

정상. 모든 지표가 임계값 안쪽이며 최근 수신이 확인됨.

● 주의

일부 지표가 주의(75%대) 구간. 곧 조치가 필요할 수 있음.

● 위험

서비스 중단 또는 위험(90%대) 임계 초과. 즉시 확인 필요.

● Offline

15초 이상 수신 없음. 에이전트·네트워크·서버 상태 점검.

카드를 클릭하면 상세 모달이 열려 시스템 자원(CPU·MEM·Disk·Load·Network)과 카테고리별(웹서버·캐시·DB) 서비스 지표, 그리고 "왜 이 상태인가"를 설명하는 진단·조치 안내를 볼 수 있습니다.

텔레그램 알림 — 전이가 생길 때만

상태가 바뀌는 순간에만 1회 알립니다. 같은 상태가 지속되면 추가 알림이 없습니다.

🟡 [주의] 정상(ok) ──▶ 주의(warn) 알림 1회 🔴 [위험] 주의(warn) ──▶ 위험(crit) 알림 1회 🟢 [복구] 위험/주의 ──▶ 정상(ok) 알림 1회 (ALERT_RECOVERY=false면 생략) ⚫ [오프라인] 수신 끊김 60초 확정 ──▶ 재수신 시 [복구]

알림에는 구체적 사유가 함께 옵니다. 대시보드 하단 "최근 알림" 타임라인과 GET /api/v1/incidents에도 같은 내용이 기록됩니다. DAILY_REPORT_TIMES(기본 09:00·18:00 KST)에 전체 현황 요약도 자동 전송됩니다.

봇 설정은 @BotFather로 봇 생성 → 봇에게 메시지 1회 전송 → getUpdates로 chat_id 확인 → 백엔드 .env에 TELEGRAM_BOT_TOKEN·TELEGRAM_CHAT_ID 입력 후 재기동. 자세한 단계는 문서형 매뉴얼 6.1절.