Laravel Telescope

번역일: 2026년 6월 20일

Laravel Telescope

소개
설치
Telescope 업그레이드
필터링
- 엔트리 필터링
- 배치 필터링
태깅
사용 가능한 워처
사용자 아바타 표시

소개

Laravel Telescope는 Laravel 로컬 개발 환경을 위한 강력한 디버깅 도구입니다. Telescope를 사용하면 애플리케이션으로 들어오는 요청, 예외, 로그, 데이터베이스 쿼리, 큐 Job, 메일, 알림, 캐시 작업, 스케줄 작업, 변수 덤프 등 다양한 정보를 한눈에 확인할 수 있습니다.

설치

Composer를 사용해 Telescope를 프로젝트에 설치합니다:

composer require laravel/telescope

설치 후 telescope:install Artisan 명령어로 에셋과 마이그레이션 파일을 게시(publish)하고, migrate 명령어로 Telescope 데이터를 저장할 테이블을 생성합니다:

php artisan telescope:installphp artisan migrate

설치가 완료되면 /telescope 라우트로 대시보드에 접근할 수 있습니다.

로컬 전용 설치

Telescope를 로컬 개발 환경에서만 사용할 계획이라면 --dev 플래그를 사용해 설치하세요:

composer require laravel/telescope --devphp artisan telescope:installphp artisan migrate

telescope:install 실행 후에는 bootstrap/providers.php에서 TelescopeServiceProvider 등록을 제거해야 합니다. 대신 App\Providers\AppServiceProvider의 register 메서드 안에서 현재 환경이 local일 때만 수동으로 등록합니다:

/**
 * 애플리케이션 서비스를 등록합니다.
 */
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);
    }
}

마지막으로 Telescope 패키지가 자동 검색(auto-discovery)되지 않도록 composer.json에 다음을 추가합니다:

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

NOTE

이렇게 수동 등록 방식으로 설정하면 Telescope는 local 환경에서만 로드되므로, 프로덕션 배포 시 불필요한 패키지가 로드되는 것을 방지할 수 있습니다.

설정

에셋을 게시하면 주요 설정 파일이 config/telescope.php에 생성됩니다. 이 파일에서 워처 옵션을 비롯한 다양한 설정을 조정할 수 있습니다. 각 옵션에는 설명이 포함되어 있으므로 파일 전체를 살펴보는 것을 권장합니다.

필요하다면 enabled 옵션으로 Telescope의 데이터 수집을 완전히 비활성화할 수 있습니다:

'enabled' => env('TELESCOPE_ENABLED', true),

데이터 정리(Pruning)

정리 작업을 설정하지 않으면 telescope_entries 테이블에 레코드가 빠르게 쌓입니다. 이를 방지하기 위해 telescope:prune Artisan 명령어를 매일 실행되도록 스케줄에 등록하세요:

use Illuminate\Support\Facades\Schedule;

Schedule::command('telescope:prune')->daily();

기본적으로 24시간이 지난 모든 엔트리가 삭제됩니다. hours 옵션으로 보존 기간을 조정할 수 있습니다. 아래 예시는 48시간이 지난 레코드를 삭제합니다:

use Illuminate\Support\Facades\Schedule;

Schedule::command('telescope:prune --hours=48')->daily();

대시보드 접근 제어

Telescope 대시보드는 /telescope 라우트로 접근합니다. 기본적으로 local 환경에서만 접근이 허용됩니다. app/Providers/TelescopeServiceProvider.php 파일에는 비-로컬 환경에서의 접근을 제어하는 인증 게이트(authorization gate)가 정의되어 있습니다. 필요에 따라 이 게이트를 수정하여 접근 가능한 사용자를 제한할 수 있습니다:

use App\Models\User;

/**
 * Telescope 게이트를 등록합니다.
 *
 * 이 게이트는 비-로컬 환경에서 Telescope에 접근할 수 있는 사용자를 결정합니다.
 */
protected function gate(): void
{
    Gate::define('viewTelescope', function (User $user) {
        return in_array($user->email, [
            'admin@example.com',
        ]);
    });
}

WARNING

프로덕션 환경에서는 반드시 APP_ENV 환경 변수를 production으로 설정하세요. 그렇지 않으면 Telescope 대시보드가 외부에 공개될 수 있습니다.

Telescope 업그레이드

새로운 메이저 버전으로 업그레이드할 때는 업그레이드 가이드를 꼼꼼히 확인하세요.

어떤 버전으로 업그레이드하든 에셋을 다시 게시해야 합니다:

php artisan telescope:publish

에셋을 항상 최신 상태로 유지하려면 composer.json의 post-update-cmd 스크립트에 다음을 추가하세요. Composer 업데이트 시 자동으로 에셋이 게시됩니다:

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
        ]
    }
}

필터링

엔트리 필터링

App\Providers\TelescopeServiceProvider의 filter 클로저를 통해 Telescope가 기록할 데이터를 제어할 수 있습니다. 기본 설정에서는 local 환경이면 모든 데이터를 기록하고, 그 외 환경에서는 예외, 실패한 Job, 스케줄 작업, 모니터링 태그가 달린 데이터만 기록합니다:

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

/**
 * 애플리케이션 서비스를 등록합니다.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();

    Telescope::filter(function (IncomingEntry $entry) {
        if ($this->app->environment('local')) {
            return true;
        }

        return $entry->isReportableException() ||
            $entry->isFailedJob() ||
            $entry->isScheduledTask() ||
            $entry->isSlowQuery() ||
            $entry->hasMonitoredTag();
    });
}

배치 필터링

filter 클로저가 개별 엔트리를 필터링한다면, filterBatch 메서드는 하나의 요청 또는 콘솔 명령 전체에 해당하는 모든 엔트리를 한 번에 필터링합니다. 클로저가 true를 반환하면 해당 배치의 모든 엔트리가 기록됩니다:

use Illuminate\Support\Collection;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

/**
 * 애플리케이션 서비스를 등록합니다.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();

    Telescope::filterBatch(function (Collection $entries) {
        if ($this->app->environment('local')) {
            return true;
        }

        return $entries->contains(function (IncomingEntry $entry) {
            return $entry->isReportableException() ||
                $entry->isFailedJob() ||
                $entry->isScheduledTask() ||
                $entry->isSlowQuery() ||
                $entry->hasMonitoredTag();
            });
    });
}

태깅

Telescope는 태그로 엔트리를 검색할 수 있습니다. Eloquent 모델 클래스명이나 인증된 사용자 ID는 Telescope가 자동으로 태그로 추가합니다. 필요하다면 Telescope::tag 메서드로 커스텀 태그를 직접 추가할 수도 있습니다. tag 메서드는 태그 배열을 반환하는 클로저를 받으며, 반환된 태그는 자동 태그와 병합됩니다. 보통 App\Providers\TelescopeServiceProvider의 register 메서드 안에서 호출합니다:

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

/**
 * 애플리케이션 서비스를 등록합니다.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();

    Telescope::tag(function (IncomingEntry $entry) {
        return $entry->type === 'request'
            ? ['status:'.$entry->content['response_status']]
            : [];
    });
}

사용 가능한 워처

Telescope의 "워처(watcher)"는 요청이나 콘솔 명령이 실행될 때 애플리케이션 데이터를 수집합니다. config/telescope.php 설정 파일에서 활성화할 워처 목록을 지정할 수 있습니다:

'watchers' => [
    Watchers\CacheWatcher::class => true,
    Watchers\CommandWatcher::class => true,
    ...
],

일부 워처는 추가 옵션도 제공합니다:

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

Batch Watcher

Batch Watcher는 큐 배치(batch)에 대한 정보(Job 정보, 연결 정보 등)를 기록합니다.

Cache Watcher

Cache Watcher는 캐시 키 조회 성공(hit), 실패(miss), 갱신(updated), 삭제(forgotten) 시 해당 데이터를 기록합니다.

Command Watcher

Command Watcher는 Artisan 명령어 실행 시 인수, 옵션, 종료 코드, 출력 결과를 기록합니다. 특정 명령어를 기록에서 제외하려면 config/telescope.php의 ignore 옵션에 추가하세요:

'watchers' => [
    Watchers\CommandWatcher::class => [
        'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
        'ignore' => ['key:generate'],
    ],
    ...
],

Dump Watcher

Dump Watcher는 dump 함수로 출력한 변수를 Telescope 대시보드에서 확인할 수 있게 기록합니다. 단, 브라우저에서 Telescope의 Dump 탭이 열려 있을 때만 기록됩니다. 탭이 닫혀 있으면 덤프는 무시됩니다.

Event Watcher

Event Watcher는 애플리케이션에서 디스패치된 이벤트의 페이로드, 리스너, 브로드캐스트 데이터를 기록합니다. Laravel 프레임워크 내부 이벤트는 기록 대상에서 제외됩니다.

Exception Watcher

Exception Watcher는 애플리케이션에서 발생한 보고 가능한(reportable) 예외의 데이터와 스택 트레이스를 기록합니다.

Gate Watcher

Gate Watcher는 게이트 및 정책(gate and policy) 검사의 데이터와 결과를 기록합니다. 특정 ability를 기록에서 제외하려면 config/telescope.php의 ignore_abilities 옵션을 활용하세요:

'watchers' => [
    Watchers\GateWatcher::class => [
        'enabled' => env('TELESCOPE_GATE_WATCHER', true),
        'ignore_abilities' => ['viewNova'],
    ],
    ...
],

HTTP Client Watcher

HTTP Client Watcher는 애플리케이션에서 발송한 외부 HTTP 클라이언트 요청을 기록합니다.

Job Watcher

Job Watcher는 애플리케이션에서 디스패치된 Job의 데이터와 상태를 기록합니다.

Log Watcher

Log Watcher는 애플리케이션에서 기록된 로그 데이터를 수집합니다.

기본적으로 error 레벨 이상의 로그만 기록됩니다. config/telescope.php의 level 옵션을 수정하면 기록 기준을 변경할 수 있습니다:

'watchers' => [
    Watchers\LogWatcher::class => [
        'enabled' => env('TELESCOPE_LOG_WATCHER', true),
        'level' => 'debug',
    ],

    // ...
],

Mail Watcher

Mail Watcher를 사용하면 애플리케이션이 발송한 메일을 브라우저에서 미리보기로 확인하고 관련 데이터도 볼 수 있습니다. 메일을 .eml 파일로 다운로드하는 것도 가능합니다.

Model Watcher

Model Watcher는 Eloquent 모델 이벤트가 디스패치될 때마다 모델 변경 사항을 기록합니다. events 옵션으로 기록할 모델 이벤트를 지정할 수 있습니다:

'watchers' => [
    Watchers\ModelWatcher::class => [
        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
        'events' => ['eloquent.created*', 'eloquent.updated*'],
    ],
    ...
],

요청 처리 중 하이드레이션(hydration)된 모델 수를 함께 기록하려면 hydrations 옵션을 활성화하세요:

'watchers' => [
    Watchers\ModelWatcher::class => [
        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
        'events' => ['eloquent.created*', 'eloquent.updated*'],
        'hydrations' => true,
    ],
    ...
],

Notification Watcher

Notification Watcher는 애플리케이션에서 발송된 모든 알림을 기록합니다. 알림이 메일을 발송하고 Mail Watcher가 활성화되어 있다면, Mail Watcher 화면에서 해당 메일도 미리볼 수 있습니다.

Query Watcher

Query Watcher는 애플리케이션에서 실행된 모든 쿼리의 원시 SQL, 바인딩 값, 실행 시간을 기록합니다. 100밀리초를 초과하는 쿼리는 자동으로 slow 태그가 붙습니다. slow 옵션으로 느린 쿼리 기준값을 조정할 수 있습니다:

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

Redis Watcher

Redis Watcher는 애플리케이션에서 실행된 모든 Redis 명령을 기록합니다. Redis를 캐시로 사용하는 경우, 캐시 관련 명령도 Redis Watcher에 기록됩니다.

Request Watcher

Request Watcher는 애플리케이션이 처리한 요청의 요청 정보, 헤더, 세션, 응답 데이터를 기록합니다. size_limit 옵션(킬로바이트 단위)으로 기록할 응답 데이터의 크기를 제한할 수 있습니다:

'watchers' => [
    Watchers\RequestWatcher::class => [
        'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
        'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
    ],
    ...
],

Schedule Watcher

Schedule Watcher는 애플리케이션에서 실행된 스케줄 작업의 명령어와 출력 결과를 기록합니다.

View Watcher

View Watcher는 뷰를 렌더링할 때 사용된 뷰 이름, 경로, 데이터, 컴포저(composer) 정보를 기록합니다.

사용자 아바타 표시

Telescope 대시보드는 각 엔트리가 저장될 때 인증된 사용자의 아바타를 표시합니다. 기본적으로 Gravatar 서비스를 통해 아바타를 가져옵니다. App\Providers\TelescopeServiceProvider에 콜백을 등록하면 아바타 URL을 직접 지정할 수 있습니다. 콜백은 사용자 ID와 이메일을 받아 아바타 이미지 URL을 반환해야 합니다:

use App\Models\User;
use Laravel\Telescope\Telescope;

/**
 * 애플리케이션 서비스를 등록합니다.
 */
public function register(): void
{
    // ...

    Telescope::avatar(function (string $id, string $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}