Laravel Telescope - Knowledge of Laravel

Laravel Telescope란

Laravel Telescope는 Laravel 애플리케이션의 내부 상태를 시각화하는 공식 디버깅 도구입니다. 요청, 예외, 쿼리, 잡, 로그, 메일, 알림, 캐시 조작, 스케줄 실행 등을 상세하게 기록할 수 있습니다. 로컬 개발 환경 전용 디버깅 도구입니다. 프로덕션 환경 모니터링에는 Laravel Pulse나 Laravel Nightwatch를 사용해 주세요.

모니터링 대상 레이어

설치

Telescope를 설치한다

composer require laravel/telescope

에셋과 마이그레이션을 게시한다

php artisan telescope:install

마이그레이션을 실행한다

php artisan migrate

설치 후 /telescope에서 대시보드에 접근할 수 있습니다.

로컬 전용 설치(권장)

로컬 개발에서의 디버깅이 주된 목적이라면, --dev로 설치하고 서비스 프로바이더를 local 환경에서만 수동 등록하는 구성을 권장합니다.

composer require laravel/telescope --dev

php artisan telescope:install
php artisan migrate

telescope:install 실행 후에는 bootstrap/providers.php에서 TelescopeServiceProvider의 등록을 삭제해 주세요. 그런 다음 App\Providers\AppServiceProvider의 register 메서드에서 수동 등록합니다.

public function register(): void
{
    if ($this->app->environment('local') && class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

추가로 composer.json에서 auto-discovery를 비활성화해 주세요.

{
  "extra": {
    "laravel": {
      "dont-discover": [
        "laravel/telescope"
      ]
    }
  }
}

사용 가능한 워처

워처는 요청이나 명령 실행 시의 텔레메트리를 수집합니다. config/telescope.php에서 활성화·설정을 관리합니다.

Request Watcher

요청, 헤더, 세션, 응답을 기록합니다.
size_limit으로 응답 기록 크기를 제한할 수 있습니다.

Query Watcher(특히 중요)

SQL, 바인딩, 실행 시간을 기록합니다.
기본적으로 100ms 초과 쿼리가 slow 태그로 기록되므로 성능 병목 감지에 매우 유용합니다.

Watchers\QueryWatcher::class => [
    'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
    'slow' => 100,
],

Job Watcher

큐 잡의 투입과 실행 결과를 기록합니다.

Exception Watcher

report 대상 예외와 스택 트레이스를 기록합니다.

Log Watcher

애플리케이션 로그를 기록합니다.
기본은 error 이상이며, 설정에서 debug까지 낮출 수 있습니다.

Command Watcher

Artisan 명령의 인수, 옵션, 출력, 종료 코드를 기록합니다.

Event Watcher

dispatch된 이벤트의 페이로드와 리스너 정보를 기록합니다(Laravel 내부 이벤트는 제외).

Cache Watcher

캐시의 히트, 미스, 갱신, 삭제를 기록합니다.

Redis Watcher

애플리케이션에서 실행된 Redis 명령을 기록합니다.

Model Watcher

Eloquent 모델 이벤트를 기록하고, 필요에 따라 hydration 건수도 수집할 수 있습니다.

Notification Watcher

전송된 알림을 기록합니다.

Mail Watcher

전송된 메일을 브라우저에서 미리보기 하고 .eml로 다운로드할 수 있습니다.

HTTP Client Watcher

외부로 향하는 HTTP 클라이언트 요청을 기록합니다.

Gate Watcher

Gate / Policy의 인가 체크 결과를 기록합니다.

Schedule Watcher

스케줄 실행된 명령과 출력을 기록합니다.

View Watcher

렌더링된 뷰 이름, 경로, 데이터, composer를 기록합니다.

Batch Watcher

큐 배치 정보(잡이나 커넥션 정보)를 기록합니다.

Dump Watcher

Telescope의 Dump 탭이 열려 있는 동안의 dump 출력을 기록합니다.

정리

작업	권장 설정
도입	`composer require laravel/telescope --dev`
로컬 전용의 확실한 분리	수동 프로바이더 등록 + `dont-discover`
DB 성능 조사	Query Watcher의 slow 쿼리 태그(기본 100ms) 활용

다음 단계

Laravel Pulse

프로덕션 환경의 퍼포먼스 집계 대시보드를 도입합니다.

Laravel Nightwatch

프로덕션 환경의 실시간 모니터링에는 Nightwatch를 사용합니다.

​Laravel Telescope란

​모니터링 대상 레이어

​설치

​로컬 전용 설치(권장)

​사용 가능한 워처

​정리

​다음 단계

Laravel Pulse

Laravel Nightwatch

Laravel Telescope란

모니터링 대상 레이어

설치

로컬 전용 설치(권장)

사용 가능한 워처

정리

다음 단계