Machbase-neo Prometheus 모니터링 데모 가이드

이 문서는 독자의 OS에 맞게 Machbase-neo의 Prometheus metrics endpoint를 수집하고 Grafana 대시보드를 여는 절차를 안내합니다. Linux는 host network 방식, macOS/Windows는 Docker Desktop 방식으로 나눠서 실행합니다.

0. 데모 구성 개요

• 대상 endpoint: http://127.0.0.1:5654/debug/metrics
• 수집기: Prometheus (Docker)
• 시각화: Grafana (Docker)

생성된 주요 파일:

• compose.yml
• compose.linux.yml
• compose.desktop.yml
• prometheus/prometheus.linux.yml
• prometheus/prometheus.desktop.yml
• grafana/provisioning/datasources/datasource.yml
• grafana/provisioning/dashboards/dashboard.yml
• grafana/dashboards/machbase-neo-metrics.json

1. 사전 조건

• Docker 및 Docker Compose 사용 가능
• 5654, 9090, 3000 포트 사용 가능
• Machbase-neo 실행 파일 사용 가능
• 이 문서는 프로젝트 루트에서 실행하는 기준입니다

2. Machbase-neo 시작

어느 OS에서든 Machbase-neo는 호스트에서 먼저 실행합니다.

cd neo-server
./tmp/machbase-neo serve --host 0.0.0.0

정상 기동 확인 포인트:

• 로그에 HTTP Listen tcp://0.0.0.0:5654
• 로그에 machbase-neo web running at: http://127.0.0.1:5654

3. Metrics endpoint 수동 확인

별도 터미널에서:

curl -sS http://127.0.0.1:5654/debug/metrics | head -n 20

예시로 # HELP, # TYPE, memoryfs_count 등의 Prometheus 형식 텍스트가 보여야 합니다.

4. OS별 실행 방법

4-1. Linux

Linux에서는 Prometheus를 host network로 실행합니다.

docker compose -f compose.yml -f compose.linux.yml up -d

확인:

docker compose -f compose.yml -f compose.linux.yml ps

4-2. macOS / Windows

Docker Desktop 환경에서는 Prometheus를 포트 공개 방식으로 실행합니다.

docker compose -f compose.yml -f compose.desktop.yml up -d

확인:

docker compose -f compose.yml -f compose.desktop.yml ps

5. 접속 URL

• Prometheus: http://127.0.0.1:9090
• Grafana: http://127.0.0.1:3000
• Grafana 기본 계정: admin / admin

6. Prometheus 수집 상태 확인

6-1. Target 상태 확인

curl -sS http://127.0.0.1:9090/api/v1/targets

machbase-neo target의 health 값이 up 이어야 합니다.

6-2. up 메트릭 확인

curl -sS 'http://127.0.0.1:9090/api/v1/query?query=up%7Bjob%3D%22machbase-neo%22%7D'

value가 1인 시계열이 존재하면 수집 성공입니다.

7. Grafana 대시보드 확인

대시보드:

• Machbase Neo Metrics Demo (Neo Demo 폴더에 자동 등록)

8. 왜 OS별 파일을 분리했는가

Linux에서는 Prometheus가 host network를 사용해야 Machbase-neo의 debug endpoint가 localhost 기준으로 접근되어 403 Forbidden을 피하기 쉽습니다. macOS/Windows에서는 Docker Desktop 특성상 host network가 같은 방식으로 동작하지 않으므로, 대신 9090 포트를 공개하고 host.docker.internal을 사용합니다.

Prometheus 설정은 OS별 prometheus/prometheus.linux.yml 또는 prometheus/prometheus.desktop.yml을 사용합니다.

9. 트러블슈팅

증상 A: Prometheus target이 DOWN

• 확인: curl -sS http://127.0.0.1:9090/api/v1/targets
• 원인 후보:
  • Machbase-neo 미기동
  • 5654 포트 충돌
  • OS에 맞지 않는 compose 파일 실행
  • debug 접근 제어로 인한 403

증상 B: Grafana에서 데이터가 안 보임

• Prometheus datasource URL 확인: host.docker.internal:9090
• Prometheus 자체 query에서 up{job="machbase-neo"} 값이 1인지 선확인

증상 C: machbase-neo가 IOT instruction (core dumped)로 종료됨

• 현상:
  • ./tmp/machbase-neo serve --host 0.0.0.0 실행 후 일정 시점에 프로세스 종료
  • Prometheus up{job="machbase-neo"} 값이 0으로 하락
• 즉시 복구:

cd neo-server
./tmp/machbase-neo serve --host 0.0.0.0

복구 확인:

curl -sS http://127.0.0.1:5654/debug/metrics | head -n 5
curl -sS 'http://127.0.0.1:9090/api/v1/query?query=up%7Bjob%3D%22machbase-neo%22%7D'

• 운영 팁:
  • 데모 중에는 neo 서버 실행 터미널을 별도로 유지하고, 종료 로그 발생 시 즉시 재기동
  • 장기 실행이 필요하면 systemd/supervisor 등 프로세스 관리자를 사용해 자동 재시작 정책 적용

10. 종료/정리

모니터링 스택 종료

docker compose -f compose.yml -f compose.linux.yml down

또는 macOS / Windows에서는:

docker compose -f compose.yml -f compose.desktop.yml down

볼륨까지 완전 제거

docker compose -f compose.yml -f compose.linux.yml down -v

또는 macOS / Windows에서는:

docker compose -f compose.yml -f compose.desktop.yml down -v