> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.
# Laravel Nightwatch 입문
> Laravel의 호스티드 SaaS 애플리케이션 모니터링 플랫폼 'Nightwatch'의 개요, Telescope · Pulse와의 차이, 설치 방법, 그리고 무료 플랜에서 실용적으로 사용하기 위한 설정을 설명합니다.
## Laravel Nightwatch란
[Laravel Nightwatch](https://nightwatch.laravel.com)는 Laravel 애플리케이션의 프로덕션 환경을 지속적으로 모니터링하기 위한 **호스티드형 SaaS 플랫폼**입니다. HTTP 요청, SQL 쿼리, 예외, 큐 잡, 로그, 스케줄 태스크 등 애플리케이션 전체의 텔레메트리 데이터를 실시간으로 수집 · 가시화합니다.
Nightwatch는 **유료 서비스**(월 과금)입니다. 무료 플랜에서도 이용할 수 있지만, 수집 가능한 이벤트 수에 상한이 있습니다. 무료 플랜에서 실용적으로 사용하려면 후술하는 샘플링과 필터링 설정이 필수입니다.
***
## Telescope · Pulse와의 차이
Nightwatch는 Laravel 에코시스템에 있는 기존 모니터링 · 디버그 도구와 목적이 다릅니다. 각각의 용도를 정리합니다.
```mermaid theme={null}
graph TD
A["Laravel 모니터링 도구"] --> B["Telescope
개발 환경의 디버그"]
A --> C["Pulse
프로덕션 환경의 퍼포먼스 집계"]
A --> D["Nightwatch
프로덕션 환경의 호스티드형 모니터링"]
B --> B1["직접 호스팅
개발 시에만
무료 · OSS"]
C --> C1["직접 호스팅
실시간 대시보드
무료 · OSS"]
D --> D1["SaaS 플랫폼
에이전트 상주 필요
유료 서비스"]
```
| 도구 | 용도 | 호스팅 | 대상 환경 |
| -------------- | ---------------- | ------------------ | ----------- |
| **Telescope** | 개발 시 디버그 · 쿼리 조사 | 자체 (Laravel 앱 내) | 로컬 개발 |
| **Pulse** | 퍼포먼스 지표의 집계 · 표시 | 자체 (Laravel 앱 내) | 프로덕션 · 스테이징 |
| **Nightwatch** | 프로덕션 앱의 실시간 모니터링 | Laravel 호스티드형 SaaS | 프로덕션 환경 |
Telescope와 거의 같은 정보를 수집하지만, Nightwatch는 에이전트 프로세스를 상주시켜 데이터를 클라우드에 송신합니다. 그 때문에 서버가 다운되어 있어도 이력 데이터를 확인할 수 있고, 여러 서버 · 여러 애플리케이션을 일원 관리할 수 있습니다.
***
## 아키텍처
Nightwatch는 Laravel 앱과 Nightwatch 클라우드 사이에 에이전트 프로세스를 끼우는 구성을 취하고 있습니다.
```mermaid theme={null}
sequenceDiagram
participant App as Laravel 앱
participant Agent as Nightwatch 에이전트
(php artisan nightwatch:agent)
participant Cloud as Nightwatch 클라우드
participant Dashboard as 대시보드
(nightwatch.laravel.com)
App->>Agent: 이벤트 데이터 송신
(127.0.0.1:2407)
Agent->>Cloud: 배치 송신
Cloud->>Dashboard: 가시화 · 알림
```
에이전트는 로컬(`127.0.0.1:2407`)에서 대기하며, Laravel 앱으로부터의 이벤트를 받아 클라우드에 전송합니다. 이 때문에 에이전트 프로세스를 상시 가동시켜야 합니다.
***
## 설치와 초기 설정
### 1. 계정 · 애플리케이션 생성
[nightwatch.laravel.com](https://nightwatch.laravel.com)에서 계정을 만들고, 조직과 애플리케이션을 등록합니다. 애플리케이션 등록 후에 **환경 토큰**이 발행됩니다.
### 2. 패키지 설치
```bash theme={null}
composer require laravel/nightwatch
```
Telescope와는 달리, `--dev` 플래그는 **불필요**합니다. Nightwatch는 프로덕션 환경에서의 사용을 전제로 하고 있습니다.
### 3. 토큰 설정
`.env` 파일에 토큰을 추가합니다.
```ini theme={null}
NIGHTWATCH_TOKEN=your-api-key
```
### 4. 에이전트 기동
```bash theme={null}
php artisan nightwatch:agent
```
에이전트는 백그라운드에서 상시 가동시켜야 합니다. Laravel Cloud, Laravel Forge, Laravel Vapor에는 전용 가이드가 준비되어 있습니다. Forge의 경우 공식 인테그레이션을 사용하면 자동 설정됩니다.
에이전트 상태 확인:
```bash theme={null}
php artisan nightwatch:status
```
### 5. 테스트 환경에서의 비활성화
테스트 실행 시에는 Nightwatch를 비활성화하는 것을 권장합니다.
```ini theme={null}
# .env
NIGHTWATCH_ENABLED=false
```
`phpunit.xml`에서도 설정할 수 있습니다.
```xml theme={null}
```
***
## 무료 플랜에서 실용적으로 사용하기 위한 설정
**무료 플랜에는 월간 이벤트 수의 상한이 있습니다.** 기본 설정(샘플링 레이트 100% · 전 데이터 수집) 그대로는 트래픽이 많은 애플리케이션에서 곧 상한에 도달해 버립니다. 이하의 설정을 반드시 적용해 주세요.
### 샘플링 레이트 낮추기
`NIGHTWATCH_REQUEST_SAMPLE_RATE`는 기본이 `1.0`(전 요청 수집)입니다. 무료 플랜에서는 `0.1`(10%) 정도로 억제할 것을 권장합니다.
```ini theme={null}
# .env
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
```
예외와 명령은 계속 전건 수집하는 설정 예:
```ini theme={null}
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1 # 요청은 10%만
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0 # 예외는 전건 (기본)
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0 # 명령은 전건 (기본)
```
### 쿼리 수집 비활성화
데이터베이스 쿼리는 이벤트 수의 큰 비율을 차지합니다. 무료 플랜에서는 쿼리 수집을 비활성화함으로써, 중요한 이벤트(예외 · 요청 · 잡)의 저장 여지를 확보할 수 있습니다.
```ini theme={null}
# .env
NIGHTWATCH_IGNORE_QUERIES=true
```
### 그 외의 필터링 설정
필요에 따라 캐시 이벤트나 메일 수집도 비활성화할 수 있습니다.
```ini theme={null}
NIGHTWATCH_IGNORE_CACHE_EVENTS=true
NIGHTWATCH_IGNORE_MAIL=true
NIGHTWATCH_IGNORE_NOTIFICATIONS=true
NIGHTWATCH_IGNORE_OUTGOING_REQUESTS=true
```
### 무료 플랜 권장 설정 정리
```ini theme={null}
# .env (무료 플랜 권장 설정)
NIGHTWATCH_TOKEN=your-api-key
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
NIGHTWATCH_IGNORE_QUERIES=true
```
이 3줄을 설정하는 것만으로, 무료 플랜에서도 실용적인 애플리케이션 모니터링을 실현할 수 있습니다.
***
## 주요 기능
### 요청 모니터링
HTTP 요청마다 응답 시간, 상태 코드, 라우트 정보 등을 수집합니다. 비정상적으로 느린 엔드포인트를 특정하여 퍼포먼스의 병목을 발견할 수 있습니다.
### 예외 추적
프로덕션 환경에서 발생한 미처리 예외를 실시간으로 포착합니다. 스택 트레이스와 소스 코드의 스니펫이 자동으로 기록되어, 원인 조사가 용이해집니다.
```ini theme={null}
# 예외의 소스 코드 수집 (기본 유효)
NIGHTWATCH_CAPTURE_EXCEPTION_SOURCE_CODE=true
```
### 로그 수집
Laravel의 로그 시스템(`Log::error()` 등)과 통합하여, 구조화 로그를 Nightwatch에 송신합니다.
```ini theme={null}
# 수집할 로그의 최저 레벨 (기본: debug)
NIGHTWATCH_LOG_LEVEL=error
```
### 잡 · 스케줄 태스크 모니터링
큐 잡이나 스케줄 태스크의 실행 이력, 성공 · 실패 상태, 실행 시간을 추적합니다. 배치 처리의 문제를 재빨리 특정할 수 있습니다.
### 배포 추적
릴리스별 변경점과 문제를 연결시킵니다. "이 배포 후부터 예외가 늘어났다"는 조사가 시각적으로 가능합니다.
### 알림과 통지
Slack 연동이나 Webhook을 사용하여, 예외의 급증이나 퍼포먼스 열화를 즉시 통지할 수 있습니다.
***
## Telescope와 Nightwatch의 사용 구분
```mermaid theme={null}
flowchart TD
Q1{"프로덕션 환경의 데이터가
필요?"} -->|예| Q2{"자기 서버에
데이터를 두고 싶다?"}
Q1 -->|아니오| T["Telescope
(로컬 개발)"]
Q2 -->|예| P["Pulse
(직접 호스팅)"]
Q2 -->|아니오| N["Nightwatch
(호스티드형 SaaS)"]
```
* **로컬 개발** → Telescope
* **프로덕션 환경의 집계 대시보드가 필요** → Pulse
* **프로덕션 환경의 상세한 트레이스나 알림이 필요** → Nightwatch
3가지는 상호 배타가 아니며, Pulse와 Nightwatch를 병용할 수도 있습니다.
***
## 정리
Laravel Nightwatch는 프로덕션 Laravel 애플리케이션의 가시성을 크게 향상시키는 강력한 SaaS 도구입니다. 도입 시에는 이하의 점을 짚어 두세요.
* 에이전트 프로세스를 상시 가동시켜야 함
* 무료 플랜은 `NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1`과 `NIGHTWATCH_IGNORE_QUERIES=true`의 설정이 실용상 필수
* Telescope(개발) · Pulse(집계) · Nightwatch(모니터링)는 역할이 다르며, 병용할 수 있음
자세한 설정에 대해서는 [공식 문서](https://nightwatch.laravel.com/docs/start-guide) 및 [환경 변수 레퍼런스](https://nightwatch.laravel.com/docs/environment-variables)를 참고하세요.
로컬 개발에서의 디버그에는 Telescope를 사용합니다.
## Related topics
- [React 입문 — Inertia × Laravel에서 사용하는 기초 지식](/ko/blog/react-introduction.md)
- [Svelte 입문 — Inertia × Laravel에서 사용하는 기초 지식](/ko/blog/svelte-introduction.md)
- [Vue.js 입문 — Inertia × Laravel에서 사용하는 기초 지식](/ko/blog/vue-introduction.md)
- [Eloquent 입문](/ko/eloquent.md)
- [인증 입문](/ko/authentication.md)