cv4pve-metrics-exporter

노드 및 클러스터 상태

• 노드 업타임, 로드 평균, 메모리·스왑 사용량, 루트 파일시스템 사용량, CPU 코어 할당량 등 노드 전반의 리소스 지표 수집
• 클러스터 쿼럼 상태, 노드 수, 클러스터 정보 등 클러스터 단위 지표 제공
• 노드별 Proxmox VE 버전·릴리스·리포지토리 정보를 cv4pve_node_version_info로 노출

가상 머신 및 컨테이너

• VM/CT 단위 CPU 사용량 및 할당 코어, 메모리 크기·사용량, 디스크 크기·사용량, 네트워크 송수신 바이트, 업타임 제공
• 게스트의 잠금 상태(백업, 스냅샷, 마이그레이션 등)를 cv4pve_guest_lock 시리즈로 분해해 알림에 활용 가능
• 백업 누락 여부를 게스트 단위 cv4pve_not_backed_up_info와 클러스터 단위 cv4pve_guests_not_backed_up으로 확인

스토리지, HA, 복제, 구독, SMART

• 스토리지 총량·사용량과 공유 여부 메트릭 제공
• HA 게스트·노드 상태 및 쿼럼 상태 메트릭 노출
• 복제 작업의 소스·타깃, 마지막 동기화 시각, 실패 횟수 등 메트릭 제공
• 구독 레벨·상태·다음 만료일을 cv4pve_node_subscription_* 시리즈로 제공
• 디스크 SMART 건강 상태 및 마모율을 cv4pve_node_disk_health, cv4pve_node_disk_wearout으로 노출(옵트인)

자체 모니터링 및 API 계측

• cv4pve_scrape_duration_seconds, cv4pve_scrape_errors_total 등 스크랩 자체 상태 메트릭 제공
• Proxmox API 호출별 지연 히스토그램과 오류 카운터를 엔드포인트별로 노출하여 성능 튜닝에 활용 가능

플랫폼별 설치

• Linux: GitHub 릴리스의 cv4pve-metrics-exporter-linux-x64.zip을 내려받아 압축 해제 후 실행 권한을 부여
• Windows: WinGet으로 winget install Corsinvest.cv4pve.metrics-exporter 또는 릴리스 페이지에서 ZIP 수동 설치
• Arch Linux: yay -S cv4pve-metrics-exporter 사용
• Debian/Ubuntu: 제공되는 .deb 패키지를 sudo dpkg -i로 설치
• RHEL/Fedora: .rpm 패키지를 sudo rpm -i로 설치
• macOS: Homebrew(brew install corsinvest/tap/cv4pve-metrics-exporter) 또는 ZIP 수동 설치

실행과 스크랩

• 기본 스크랩 엔드포인트는 http://localhost:9221/metrics/
• API 토큰을 사용한 권장 실행 예: ./cv4pve-metrics-exporter --host=YOUR_HOST --api-token=user@realm!token=uuid run
• 프로필은 Fast(대규모 클러스터, 낮은 API 호출), Standard(기본, 균형), Full(소규모 클러스터, 전체 관측) 세 가지 제공되며 --fast, --full 옵션으로 선택
• 설정 파일은 create-settings 명령으로 생성한 뒤 --settings-file 옵션으로 지정

서비스로 등록

• Linux: 동일한 바이너리를 systemd 서비스(Type=notify)로 등록하여 사용 가능
• Windows: sc.exe로 Windows 서비스에 직접 등록 가능

활용 예시

• Prometheus에서 Proxmox VE 클러스터의 노드, VM, 컨테이너 리소스 사용량을 주기적으로 수집
• HA 및 복제 상태, 백업 누락 여부를 알림 규칙과 연결해 운영 알림 구성
• 구독 만료일, 디스크 SMART 건강 상태 같은 느리게 변하는 지표를 캐시 설정으로 수집 부담을 줄이면서 모니터링
• 대규모 클러스터에서는 Fast 프로필을 적용해 스크랩 지연 시간을 단축

제한 및 확인사항

• 라이선스는 GPL-3.0이며, 자세한 내용은 저장소 내 LICENSE.md에서 확인 가능
• API 토큰을 사용할 경우 비밀 값이 외부에 노출되지 않도록 설정 파일 접근 권한을 적절히 관리해야 함
• systemd 또는 Windows 서비스로 등록할 때 --settings-file은 반드시 절대 경로로 지정해야 정상 동작
• 디스크 SMART 및 게스트 Balloon 정보는 기본 비활성화된 옵트인 컬렉터로, 활성화 시 Proxmox API 호출이 추가됨