메인 콘텐츠로 건너뛰기

​
Laravel Nightwatch란

Laravel Nightwatch는 Laravel 애플리케이션의 프로덕션 환경을 지속적으로 모니터링하기 위한 호스티드형 SaaS 플랫폼입니다. HTTP 요청, SQL 쿼리, 예외, 큐 잡, 로그, 스케줄 태스크 등 애플리케이션 전체의 텔레메트리 데이터를 실시간으로 수집 · 가시화합니다.
Nightwatch는 유료 서비스(월 과금)입니다. 무료 플랜에서도 이용할 수 있지만, 수집 가능한 이벤트 수에 상한이 있습니다. 무료 플랜에서 실용적으로 사용하려면 후술하는 샘플링과 필터링 설정이 필수입니다.

​
Telescope · Pulse와의 차이

Nightwatch는 Laravel 에코시스템에 있는 기존 모니터링 · 디버그 도구와 목적이 다릅니다. 각각의 용도를 정리합니다.
도구용도호스팅대상 환경
Telescope개발 시 디버그 · 쿼리 조사자체 (Laravel 앱 내)로컬 개발
Pulse퍼포먼스 지표의 집계 · 표시자체 (Laravel 앱 내)프로덕션 · 스테이징
Nightwatch프로덕션 앱의 실시간 모니터링Laravel 호스티드형 SaaS프로덕션 환경
Telescope와 거의 같은 정보를 수집하지만, Nightwatch는 에이전트 프로세스를 상주시켜 데이터를 클라우드에 송신합니다. 그 때문에 서버가 다운되어 있어도 이력 데이터를 확인할 수 있고, 여러 서버 · 여러 애플리케이션을 일원 관리할 수 있습니다.

​
아키텍처

Nightwatch는 Laravel 앱과 Nightwatch 클라우드 사이에 에이전트 프로세스를 끼우는 구성을 취하고 있습니다. 에이전트는 로컬(127.0.0.1:2407)에서 대기하며, Laravel 앱으로부터의 이벤트를 받아 클라우드에 전송합니다. 이 때문에 에이전트 프로세스를 상시 가동시켜야 합니다.

​
설치와 초기 설정

​
1. 계정 · 애플리케이션 생성

nightwatch.laravel.com에서 계정을 만들고, 조직과 애플리케이션을 등록합니다. 애플리케이션 등록 후에 환경 토큰이 발행됩니다.

​
2. 패키지 설치

composer require laravel/nightwatch
Telescope와는 달리, --dev 플래그는 불필요합니다. Nightwatch는 프로덕션 환경에서의 사용을 전제로 하고 있습니다.

​
3. 토큰 설정

.env 파일에 토큰을 추가합니다. 
NIGHTWATCH_TOKEN=your-api-key

​
4. 에이전트 기동

php artisan nightwatch:agent
에이전트는 백그라운드에서 상시 가동시켜야 합니다. Laravel Cloud, Laravel Forge, Laravel Vapor에는 전용 가이드가 준비되어 있습니다. Forge의 경우 공식 인테그레이션을 사용하면 자동 설정됩니다. 에이전트 상태 확인: 
php artisan nightwatch:status

​
5. 테스트 환경에서의 비활성화

테스트 실행 시에는 Nightwatch를 비활성화하는 것을 권장합니다. 
# .env
NIGHTWATCH_ENABLED=false
phpunit.xml에서도 설정할 수 있습니다. 
<php>
    <env name="APP_ENV" value="testing"/>
    <env name="NIGHTWATCH_ENABLED" value="false"/>
</php>

​
무료 플랜에서 실용적으로 사용하기 위한 설정

무료 플랜에는 월간 이벤트 수의 상한이 있습니다. 기본 설정(샘플링 레이트 100% · 전 데이터 수집) 그대로는 트래픽이 많은 애플리케이션에서 곧 상한에 도달해 버립니다. 이하의 설정을 반드시 적용해 주세요.

​
샘플링 레이트 낮추기

NIGHTWATCH_REQUEST_SAMPLE_RATE는 기본이 1.0(전 요청 수집)입니다. 무료 플랜에서는 0.1(10%) 정도로 억제할 것을 권장합니다. 
# .env
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
예외와 명령은 계속 전건 수집하는 설정 예: 
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1    # 요청은 10%만
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0  # 예외는 전건 (기본)
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0    # 명령은 전건 (기본)

​
쿼리 수집 비활성화

데이터베이스 쿼리는 이벤트 수의 큰 비율을 차지합니다. 무료 플랜에서는 쿼리 수집을 비활성화함으로써, 중요한 이벤트(예외 · 요청 · 잡)의 저장 여지를 확보할 수 있습니다. 
# .env
NIGHTWATCH_IGNORE_QUERIES=true

​
그 외의 필터링 설정

필요에 따라 캐시 이벤트나 메일 수집도 비활성화할 수 있습니다. 
NIGHTWATCH_IGNORE_CACHE_EVENTS=true
NIGHTWATCH_IGNORE_MAIL=true
NIGHTWATCH_IGNORE_NOTIFICATIONS=true
NIGHTWATCH_IGNORE_OUTGOING_REQUESTS=true

​
무료 플랜 권장 설정 정리

# .env (무료 플랜 권장 설정)
NIGHTWATCH_TOKEN=your-api-key
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
NIGHTWATCH_IGNORE_QUERIES=true
이 3줄을 설정하는 것만으로, 무료 플랜에서도 실용적인 애플리케이션 모니터링을 실현할 수 있습니다.

​
주요 기능

​
요청 모니터링

HTTP 요청마다 응답 시간, 상태 코드, 라우트 정보 등을 수집합니다. 비정상적으로 느린 엔드포인트를 특정하여 퍼포먼스의 병목을 발견할 수 있습니다.

​
예외 추적

프로덕션 환경에서 발생한 미처리 예외를 실시간으로 포착합니다. 스택 트레이스와 소스 코드의 스니펫이 자동으로 기록되어, 원인 조사가 용이해집니다. 
# 예외의 소스 코드 수집 (기본 유효)
NIGHTWATCH_CAPTURE_EXCEPTION_SOURCE_CODE=true

​
로그 수집

Laravel의 로그 시스템(Log::error() 등)과 통합하여, 구조화 로그를 Nightwatch에 송신합니다. 
# 수집할 로그의 최저 레벨 (기본: debug)
NIGHTWATCH_LOG_LEVEL=error

​
잡 · 스케줄 태스크 모니터링

큐 잡이나 스케줄 태스크의 실행 이력, 성공 · 실패 상태, 실행 시간을 추적합니다. 배치 처리의 문제를 재빨리 특정할 수 있습니다.

​
배포 추적

릴리스별 변경점과 문제를 연결시킵니다. “이 배포 후부터 예외가 늘어났다”는 조사가 시각적으로 가능합니다.

​
알림과 통지

Slack 연동이나 Webhook을 사용하여, 예외의 급증이나 퍼포먼스 열화를 즉시 통지할 수 있습니다.

​
Telescope와 Nightwatch의 사용 구분

  • 로컬 개발 → Telescope
  • 프로덕션 환경의 집계 대시보드가 필요 → Pulse
  • 프로덕션 환경의 상세한 트레이스나 알림이 필요 → Nightwatch
3가지는 상호 배타가 아니며, Pulse와 Nightwatch를 병용할 수도 있습니다.

​
정리

Laravel Nightwatch는 프로덕션 Laravel 애플리케이션의 가시성을 크게 향상시키는 강력한 SaaS 도구입니다. 도입 시에는 이하의 점을 짚어 두세요.
  • 에이전트 프로세스를 상시 가동시켜야 함
  • 무료 플랜은 NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1과 NIGHTWATCH_IGNORE_QUERIES=true의 설정이 실용상 필수
  • Telescope(개발) · Pulse(집계) · Nightwatch(모니터링)는 역할이 다르며, 병용할 수 있음
자세한 설정에 대해서는 공식 문서 및 환경 변수 레퍼런스를 참고하세요.

Laravel Telescope 실전 테크닉

로컬 개발에서의 디버그에는 Telescope를 사용합니다.
마지막 수정일 2026년 7월 13일

관련 항목

React 입문 — Inertia × Laravel에서 사용하는 기초 지식Svelte 입문 — Inertia × Laravel에서 사용하는 기초 지식Vue.js 입문 — Inertia × Laravel에서 사용하는 기초 지식Eloquent 입문인증 입문