패키지 분석laravel패키지vigilance

Vigilance 패키지 분석 — 한국 Laravel 개발자 가이드

작성: 라라벨 코리아 (초안)

발행: 2026년 7월 12일

Laravel 서버 모니터링 에이전트 패키지

요약

cms-orbit/vigilance v1.2.0은 Laravel 프로젝트에 직접 설치하는 경량 서버 모니터링 에이전트 패키지로, CPU·메모리·디스크 사용량 및 Laravel 에러 로그를 1분마다 Sentinel-Hub로 전송합니다. Laravel 9~~13, PHP 8.0~~8.5의 넓은 호환성을 제공하며, OS별 자동 감지 아키텍처로 Ubuntu·CentOS·Rocky Linux·Windows·macOS 환경을 모두 지원합니다. 별도의 외부 에이전트 없이 Composer 한 줄로 설치할 수 있어 인프라 접근이 제한된 공유 호스팅이나 매니지드 서비스 환경에서도 활용 가능합니다.

편집자 주: 이 글은 v1.2.0 기준으로 작성되었으나, README 버전 히스토리에는 v1.3.0 내용이 포함되어 있습니다. Packagist 최신 버전을 반드시 확인하세요.

핵심 내용

1. 패키지 개요 및 작동 방식

Vigilance는 Laravel의 스케줄러(Schedule) 에 자동 등록되어, 1분마다 vigilance:report Artisan 명령을 실행합니다. 수집된 데이터는 JSON 형태로 Sentinel-Hub 엔드포인트에 HTTP POST 방식으로 전송됩니다. 전송 실패 시 지수 백오프(Exponential Backoff) 를 적용한 최대 3회 재시도를 수행하며, 기본 HTTP 타임아웃은 10초입니다.

설치 → .env에 SENTINEL_HUB_URL 설정 → 크론 등록 → 자동 모니터링 시작

별도의 Service Provider 수동 등록이 필요 없으며, Laravel의 패키지 자동 디스커버리를 통해 스케줄러 등록까지 완료됩니다.

2. 수집 데이터 범위

카테고리	수집 항목
시스템 정보	OS명/버전, CPU 코어 수, PHP 버전, Laravel 버전
CPU	로드 에버리지(1/5/15분), 전체 사용률(%)
메모리	전체/사용량(MB), 사용률(%), 프로세스별 상세
디스크	설정된 경로별 사용량
헬스체크	DB 연결 상태, 큐 상태
에러 로그	Laravel 로그 파일 에러 (SHA256 중복 제거, 200자 요약)

특히 로그 모니터링은 데일리 로그 파일(laravel-2025-10-11.log) 형식을 자동 지원하며, SHA256 해시로 동일 에러를 식별하고 1분 단위 발생 횟수를 집계합니다.

3. OS별 StatusGetter 아키텍처

패키지는 AbstractStatusGetter를 기반으로 OS별 구현체를 자동 선택합니다.

AbstractStatusGetter├── LinuxStatusGetter│   ├── Ubuntu24 / Ubuntu22 / Ubuntu20StatusGetter│   ├── CentosStatusGetter│   ├── RockyStatusGetter│   └── DebianStatusGetter├── WindowsStatusGetter│   ├── Windows11 / Windows10StatusGetter│   └── WindowsServerStatusGetter└── MacStatusGetter

각 구현체는 해당 OS의 시스템 명령어(/proc/meminfo, wmic, vm_stat 등)를 내부적으로 호출합니다. 개발자가 OS를 별도로 지정할 필요 없이 런타임에 자동 감지됩니다.

4. 호환성 매트릭스

Laravel 버전	PHP 버전	지원 여부
Laravel 13	PHP 8.3 ~ 8.5	✅
Laravel 12	PHP 8.2 ~ 8.5	✅
Laravel 11	PHP 8.2 ~ 8.4	✅
Laravel 10	PHP 8.1 ~ 8.3	✅
Laravel 9	PHP 8.0 ~ 8.2	✅
Laravel 8 이하	—	❌

5. 설정 파일 주요 항목

// config/vigilance.php
'disk_paths' => ['/'],                    // 모니터링할 디스크 경로 (다중 설정 가능)
'log_monitor_prefixes' => [               // 로그 파일 prefix (데일리 로그 자동 매칭)
    storage_path('logs/laravel'),
],
'retry' => [
    'max_attempts' => 3,
    'initial_delay' => 1,                 // 초 단위
    'max_delay' => 60,
],
'timeout' => 10,                          // HTTP 타임아웃 (초)

disk_paths에 여러 경로를 추가하면 마운트된 볼륨별 디스크 사용량을 독립적으로 모니터링할 수 있습니다.

한국 Laravel 개발자에게 미치는 영향

호환성

현재 국내 Laravel 커뮤니티에서 가장 많이 사용하는 Laravel 10/11 환경(PHP 8.1~8.4)과 완전히 호환됩니다. PHP 8.5 지원도 명시되어 있어 향후 PHP 버전 업그레이드 시에도 즉시 사용 가능합니다.

Sentinel-Hub 의존성 확인 필요

이 패키지는 https://sentinel-hub.amuz.co.kr 를 기본 전송 대상으로 문서에 예시로 제시하고 있습니다. Sentinel-Hub는 별도 서비스이며, 패키지만 설치한다고 해서 모니터링 대시보드가 자동으로 제공되지 않습니다. 도입 전에 Sentinel-Hub 서비스의 이용 조건, 데이터 보관 정책, 비용 구조를 반드시 확인하세요.

보안 주의: 서버의 CPU, 메모리, 디스크, 에러 로그 등 민감한 시스템 정보가 외부 엔드포인트로 전송됩니다. 금융권, 의료, 공공기관 등 보안 규정이 엄격한 환경에서는 데이터 외부 전송 정책을 반드시 검토해야 합니다.

Laravel Valet (로컬 개발)

로컬 개발 환경에서 Valet을 사용하는 경우, Laravel 스케줄러가 상시 실행되지 않으므로 자동 전송은 동작하지 않습니다. 테스트 목적이라면 수동 Artisan 명령을 활용하세요.

php artisan vigilance:report

Laravel Sail / Docker

Sail 환경에서는 컨테이너 내부의 시스템 정보(컨테이너 레벨 CPU·메모리)가 수집됩니다. 호스트 머신 전체의 리소스가 아님을 인지해야 하며, OS 감지 결과가 컨테이너 배포 이미지(주로 Debian/Ubuntu 기반)로 표시됩니다. 다중 컨테이너 환경에서는 컨테이너마다 별도 VIGILANCE_SERVER_ID가 생성되므로 Sentinel-Hub에서 서버별 구분이 필요합니다.

크론 설정 누락 위험

패키지 자체는 스케줄러에 자동 등록되지만, 서버의 시스템 크론(crontab)은 반드시 수동 등록해야 합니다. 국내 공유 호스팅 환경 중 일부는 crontab 접근이 제한되어 있으니 사전 확인이 필요합니다.

실무 체크리스트

로컬 / 스테이징 환경

composer require cms-orbit/vigilance 설치 확인
.env에 SENTINEL_HUB_URL 설정 (스테이징용 별도 URL 권장)
php artisan vendor:publish --tag=vigilance-config 로 설정 파일 생성 (필요 시)
php artisan vigilance:report 수동 실행으로 데이터 전송 정상 여부 확인
전송되는 JSON 데이터 내용 검토 (민감 정보 포함 여부 확인)
config/vigilance.php의 disk_paths를 실제 서버 마운트 경로에 맞게 조정
Docker/Sail 환경이라면 컨테이너 레벨 메트릭임을 팀에 공유

프로덕션 배포 전

Sentinel-Hub 서비스 이용 약관 및 데이터 보관 정책 검토 완료
보안/컴플라이언스 팀의 외부 데이터 전송 승인 획득 (해당하는 경우)
crontab에 Laravel 스케줄러 등록 확인
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
VIGILANCE_SERVER_ID 자동 생성 후 .env에 고정 저장 여부 확인 (재배포 시 UUID 유지)
retry.max_attempts, timeout 값을 서버 환경에 맞게 조정
방화벽 아웃바운드 규칙에서 SENTINEL_HUB_URL 도메인 허용 여부 확인

모니터링 운영 중

Sentinel-Hub 대시보드에서 서버 UUID별 데이터 수신 정상 여부 주기적 확인
log_monitor_prefixes 설정이 실제 로그 파일 경로와 일치하는지 검증
여러 서버에 설치 시 각 서버의 VIGILANCE_SERVER_ID 중복 여부 점검
Laravel 버전 업그레이드 시 호환성 매트릭스 재확인 후 패키지 업데이트