Laravel Telescope

업데이트됨

번역일: 2026년 7월 31일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 7월 31일
번역 갱신: 2026년 7월 31일

Laravel Telescope

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

소개

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

설치

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

composer require laravel/telescope

설치 후, telescope:install Artisan 명령어로 에셋과 마이그레이션 파일을 퍼블리시한 다음, 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

이렇게 설정하면 composer require 시 Telescope 서비스 프로바이더가 자동으로 등록되지 않으므로, 프로덕션 빌드에 Telescope 코드가 포함되는 것을 방지할 수 있습니다.

설정

에셋 퍼블리시 후 주요 설정 파일은 config/telescope.php에 위치합니다. 이 파일에서 Watcher 옵션을 비롯한 다양한 설정을 관리할 수 있습니다. 각 옵션에는 설명이 포함되어 있으므로 꼼꼼히 살펴보세요.

Telescope의 데이터 수집 기능 자체를 끄고 싶다면 enabled 옵션을 사용합니다:

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

Content Security Policy (CSP) Nonce

Content Security Policy 적용 시 Telescope 뷰의 <script>, <style> 태그에 nonce 속성을 지정해야 한다면, Telescope::cspNonce 메서드를 사용하세요. 요청마다 새로운 nonce가 설정되어야 하므로 미들웨어 안에서 호출하는 것이 적합합니다:

use Closure;
use Illuminate\Http\Request;
use Laravel\Telescope\Telescope;
use Symfony\Component\HttpFoundation\Response;

public function handle(Request $request, Closure $next): Response
{
    Telescope::cspNonce('csp-nonce');

    return $next($request);
}

작성한 미들웨어는 config/telescope.php의 middleware 옵션에 추가합니다:

'middleware' => [
    'web',
    App\Http\Middleware\AddTelescopeCspNonce::class,
    Authorize::class,
],

데이터 정리(Pruning)

정리(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 업그레이드

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::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"는 요청이나 콘솔 명령어가 실행될 때 애플리케이션 데이터를 수집하는 역할을 합니다. 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) 관련 정보(Job 및 커넥션 정보 포함)를 기록합니다.

Cache Watcher

캐시 키의 조회 성공(hit), 조회 실패(miss), 업데이트, 삭제(forgotten) 이벤트를 기록합니다.

Command Watcher

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

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

Dump Watcher

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

Event Watcher

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

Exception Watcher

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

Gate Watcher

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

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

HTTP Client Watcher

애플리케이션에서 외부로 보내는 HTTP 클라이언트 요청을 기록합니다.

Job Watcher

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

Log Watcher

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

기본적으로 error 레벨 이상의 로그만 기록합니다. config/telescope.php의 level 옵션을 변경해 수집 범위를 조정할 수 있습니다:

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

    // ...
],

Mail Watcher

애플리케이션에서 발송된 메일을 브라우저에서 미리 볼 수 있으며, 관련 데이터도 함께 확인할 수 있습니다. 메일을 .eml 파일로 다운로드하는 기능도 제공합니다.

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)을 기록합니다. 알림이 이메일을 발송하고 Mail Watcher가 활성화되어 있다면, Mail Watcher 화면에서도 해당 메일을 미리 볼 수 있습니다.

Query Watcher

실행된 모든 쿼리의 원본 SQL, 바인딩 값, 실행 시간을 기록합니다. 100밀리초 이상 소요된 쿼리는 자동으로 slow 태그가 붙습니다. slow 옵션으로 기준값을 조정할 수 있습니다:

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

Redis Watcher

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

Request Watcher

애플리케이션이 처리한 요청의 요청 데이터, 헤더, 세션, 응답 데이터를 기록합니다. size_limit 옵션(단위: KB)으로 기록할 응답 데이터의 최대 크기를 제한할 수 있습니다:

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

Schedule Watcher

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

View Watcher

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

사용자 아바타 표시

Telescope 대시보드는 항목이 저장될 당시 인증된 사용자의 아바타를 표시합니다. 기본적으로 Gravatar 서비스를 통해 아바타 이미지를 가져옵니다. 아바타 URL을 직접 지정하고 싶다면, App\Providers\TelescopeServiceProvider의 register 메서드 안에서 콜백을 등록하세요. 콜백은 사용자 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';
    });
}