Laravel Telescope

번역일: 2026년 6월 20일

Laravel Telescope

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

소개

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

설치

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

composer require laravel/telescope

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

php artisan telescope:installphp artisan migrate

설치가 완료되면 /telescope 라우트로 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 패키지가 자동 검색되지 않도록 composer.json에 다음 설정을 추가합니다.

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

NOTE

이 설정은 프로덕션 환경에서 Telescope가 불필요하게 로드되는 것을 방지합니다. --dev로 설치했더라도 위 설정을 빠뜨리면 자동 검색을 통해 등록될 수 있으므로 반드시 추가하세요.

설정

에셋 게시 후 기본 설정 파일은 config/telescope.php에 위치합니다. 이 파일에서 각 Watcher 옵션을 세부적으로 조정할 수 있습니다. 각 설정 항목에는 용도 설명이 포함되어 있으니 꼼꼼히 살펴보시기 바랍니다.

필요하다면 enabled 옵션으로 Telescope의 데이터 수집 기능 전체를 비활성화할 수 있습니다.

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

데이터 정리(Pruning)

별도의 정리 작업 없이 Telescope를 운영하면 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 환경에서만 접근이 허용됩니다. local 이외의 환경에서의 접근은 app/Providers/TelescopeServiceProvider.php에 정의된 인증 게이트(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 업그레이드

Telescope의 새로운 메이저 버전으로 업그레이드할 때는 업그레이드 가이드를 반드시 먼저 확인하세요.

버전에 관계없이 Telescope를 업그레이드한 후에는 아래 명령어로 에셋을 다시 게시해야 합니다.

php artisan telescope:publish

에셋을 항상 최신 상태로 유지하려면 composer.json의 post-update-cmd 스크립트에 다음 명령어를 추가하세요. 이렇게 하면 composer update 실행 시 에셋이 자동으로 갱신됩니다.

{
    "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 메서드는 태그 배열을 반환하는 클로저를 인수로 받으며, 반환된 태그는 Telescope가 자동으로 추가하는 태그와 합쳐집니다. 일반적으로 App\Providers\TelescopeServiceProvider의 register 메서드 안에서 호출합니다.

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

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

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

사용 가능한 Watcher 목록

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

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

일부 Watcher는 추가 옵션도 지원합니다.

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

Batch Watcher

Batch Watcher는 큐에 디스패치된 배치 Job 정보를 기록합니다. Job 정보와 연결(connection) 정보를 함께 확인할 수 있습니다.

Cache Watcher

Cache Watcher는 캐시 키에 대한 적중(hit), 미스(miss), 갱신(update), 삭제(forget) 이벤트를 기록합니다.

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는 변수 덤프 내용을 캡처해 Telescope 대시보드에 표시합니다. Laravel의 전역 dump 함수를 사용한 덤프가 기록됩니다. 단, 브라우저에서 Dump Watcher 탭이 열려 있어야 기록되며, 탭이 닫혀 있으면 덤프는 무시됩니다.

Event Watcher

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

Exception Watcher

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

Gate Watcher

Gate Watcher는 게이트 및 정책(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를 캐싱에 사용하고 있다면, 캐시 관련 명령어도 함께 기록됩니다.

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 서비스를 통해 아바타 이미지를 가져옵니다. 아바타 URL을 커스터마이징하려면 App\Providers\TelescopeServiceProvider의 register 메서드 안에서 Telescope::avatar 콜백을 등록하세요. 콜백은 사용자 ID와 이메일 주소를 인수로 받아 아바타 이미지 URL을 반환해야 합니다.

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

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

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