Vigilance

인증된 제출자

cms-orbit/vigilance

제출자 이우진

최신 v1.2.0라이센스 MIT배포 2026년 8월 17일

DevOps

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

GitHub

Vigilance - Laravel 서버 모니터링 에이전트

Vigilance는 Laravel 프로젝트에 설치하여 시스템 상태를 자동으로 수집하고, 1분마다 Sentinel-Hub로 전송하는 경량 모니터링 에이전트입니다.

특징
요구사항
- 호환성 매트릭스
설치
설정
사용법
아키텍처
- StatusGetter 상속 구조
- LogMonitor
버전 히스토리
라이선스
지원

특징

🔍 실시간 시스템 모니터링: CPU, 메모리, 디스크 사용량 자동 수집
📊 프로세스 모니터링: 메모리를 많이 사용하는 프로세스 추적
🚨 오류 로그 수집: Laravel 로그 파일에서 오류를 자동 감지하고 중복 제거
🔄 자동 재시도: 전송 실패 시 지수 백오프(Exponential Backoff) 기반 재시도
🖥️ 크로스 플랫폼: Linux, Windows, macOS 지원
⚡ 경량 설계: 시스템 리소스 사용 최소화

요구사항

PHP 8.0 ~ 8.5 (>=8.0 <8.6)
Laravel 9.0 이상 (Laravel 9, 10, 11, 12, 13 지원)
Guzzle HTTP Client 7.0 이상

호환성 매트릭스

Laravel 버전	PHP 버전	Vigilance 지원
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 이하	-	❌ 미지원

설치

1. Composer를 통한 패키지 설치

composer require cms-orbit/vigilance

NOTE

업그레이드 안내: v1.0.1에서 v1.1.0 이상으로 업그레이드하는 경우, 별도의 설정 변경이 필요하지 않습니다. 모든 기능이 하위 호환성을 유지합니다.

2. 환경 설정

.env 파일에 Sentinel-Hub URL을 추가합니다:

SENTINEL_HUB_URL=https://sentinel-hub.amuz.co.kr

아래 사항은 별도로 설정하지 않아도 자동으로 처리됩니다:

서버 UUID (VIGILANCE_SERVER_ID): 최초 실행 시 자동 생성됩니다.
스케줄러 등록: 패키지 설치만으로 자동 등록됩니다.
데이터 전송: 1분마다 자동으로 서버 상태를 Sentinel-Hub로 전송합니다.

3. 크론 작업 설정 (서버에서 한 번만 설정)

Laravel 스케줄러가 실제로 동작하려면 서버 OS의 크론에 아래 항목을 등록해야 합니다. 이 작업은 서버당 한 번만 설정하면 됩니다.

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

NOTE

크론 작업이 등록되지 않으면 스케줄러가 실행되지 않아 모니터링 데이터가 전송되지 않습니다. crontab -e 명령으로 등록하거나, 서버 관리 패널(예: 가비아, 카페24, Forge 등)의 크론 설정 화면을 이용하세요.

설정

패키지 설치 후 config/vigilance.php 파일에서 다양한 동작을 조정할 수 있습니다:

return [
    // Sentinel-Hub 도메인 (API 엔드포인트 경로는 자동으로 추가됨)
    'base_url' => env('SENTINEL_HUB_URL', 'http://localhost'),

    // 서버 UUID (자동 생성되므로 직접 수정할 필요 없음)
    'server_uuid' => env('VIGILANCE_SERVER_ID', ''),

    // 모니터링할 디스크 경로
    'disk_paths' => [
        '/',
    ],

    // 모니터링할 로그 파일 prefix
    // 데일리 로그 (laravel-2025-10-11.log) 형식도 자동 지원
    'log_monitor_prefixes' => [
        storage_path('logs/laravel'),
    ],

    // 전송 실패 시 재시도 설정
    'retry' => [
        'max_attempts' => 3,    // 최대 재시도 횟수
        'initial_delay' => 1,   // 첫 재시도 대기 시간 (초)
        'max_delay'     => 60,  // 최대 대기 시간 (초)
    ],

    // HTTP 요청 타임아웃 (초)
    'timeout' => 10,
];

사용법

자동 모니터링

패키지를 설치하고 크론을 등록하면, 별도의 코드 작성 없이 1분마다 서버 상태가 자동으로 Sentinel-Hub에 전송됩니다.

수동 보고서 전송 (테스트용)

설치가 올바르게 완료되었는지 확인하거나, 즉시 데이터를 전송하고 싶을 때는 아래 Artisan 명령을 사용합니다:

php artisan vigilance:report

전송 데이터 구조

Vigilance가 Sentinel-Hub로 전송하는 JSON 데이터의 구조는 다음과 같습니다:

{
  "uuid": "서버 고유 UUID",
  "reported_at": "2025-10-10T12:00:00+00:00",
  "referer": "http://example.com",
  "system_info": {
    "os_name": "Linux",
    "os_version": "Ubuntu 22.04 LTS",
    "cpu_cores": 8,
    "php_version": "8.3.0",
    "laravel_version": "11.0.0"
  },
  "metrics": {
    "cpu": {
      "load_avg": [0.5, 0.6, 0.7],
      "total_usage_percent": 25.5,
      "core_details": []
    },
    "memory": {
      "total_mb": 16384,
      "used_mb": 8192,
      "usage_percent": 50.0,
      "process_details": ["..."]
    },
    "disks": ["..."],
    "health_check": {
      "db_connection": "ok",
      "queue_status": "ok",
      "message": "All systems operational"
    }
  },
  "errors": ["..."]
}

아키텍처

StatusGetter 상속 구조

OS별로 시스템 정보를 수집하는 방법이 다르기 때문에, Vigilance는 추상 클래스를 기반으로 각 플랫폼에 맞는 구현체를 제공합니다. 실행 환경의 OS를 자동으로 감지하여 적절한 구현체를 선택합니다.

AbstractStatusGetter (추상 클래스)├── LinuxStatusGetter│   ├── Ubuntu24StatusGetter│   ├── Ubuntu22StatusGetter│   ├── Ubuntu20StatusGetter│   ├── CentosStatusGetter│   ├── RockyStatusGetter│   └── DebianStatusGetter├── WindowsStatusGetter│   ├── Windows11StatusGetter│   ├── Windows10StatusGetter│   └── WindowsServerStatusGetter└── MacStatusGetter

자동 OS 감지 범위:

Linux: Ubuntu (버전별), CentOS, Rocky Linux, Debian 자동 식별
Windows: Windows 10, 11, Server 자동 식별
macOS: 지원

각 OS별 StatusGetter는 다음 메서드를 구현합니다:

메서드	설명
`getCpuData()`	CPU 사용률 및 로드 에버리지 수집
`getMemoryData()`	메모리 사용량 및 프로세스 정보 수집
`getDiskData()`	디스크 사용량 수집
`getSystemInfo()`	OS, PHP, Laravel 버전 등 환경 정보 수집
`getHealthCheck()`	DB 연결 및 큐 상태 확인

LogMonitor

Laravel 로그 파일을 주기적으로 읽어 오류를 수집하고 정제합니다.

Prefix 기반 파일 매칭: storage/logs/laravel.log, storage/logs/laravel-2025-10-11.log 등 데일리 로그 형식을 자동으로 인식합니다.
중복 제거: SHA256 해시를 생성하여 동일한 오류를 하나로 묶습니다.
발생 횟수 집계: 1분 간격 내에 동일 오류가 반복된 횟수를 카운팅합니다.
메시지 요약: 200자 제한으로 DB 저장 용량을 최적화합니다.
파일/라인 정보 추출: Exception 스택 트레이스에서 정확한 파일 경로와 라인 번호를 추출합니다.

버전 히스토리

자세한 변경 사항은 CHANGELOG.md를 참조하세요.

v1.3.0 (현재)

Laravel 12 / Laravel 13 지원 추가
PHP 지원 범위를 >=8.0 <8.6으로 명시 (PHP 8.5 호환 포함)
illuminate/support 지원 범위를 ^9.0|^10.0|^11.0|^12.0|^13.0으로 확장

v1.1.2

문서 및 설정 개선: .gitignore, .gitattributes 추가
README 문서 보완 (호환성 매트릭스, 업그레이드 가이드)
CHANGELOG 문서 개선

v1.1.0

하위 호환성 개선: PHP 8.0+, Laravel 9.0+ 지원
모든 기존 기능 유지
추가 설정 변경 불필요

v1.0.1

초기 릴리스

라이선스

MIT License

지원

문제가 발생하거나 기능 제안이 있으시면 GitHub Issues를 통해 알려주세요.