메인 콘텐츠로 건너뛰기
기본적인 설치와 설정은 가이드 페이지를 참고하세요. 이 페이지에서는 공식 문서에 실려 있지 않은, 로컬 개발에서의 실전 활용 패턴을 소개합니다. Telescope는 로컬 개발 전용 도구입니다. 프로덕션 환경의 모니터링에는 Laravel PulseLaravel Nightwatch를 사용해 주세요.

N+1 문제를 체계적으로 발견하기

Telescope를 사용한 N+1 디버그의 실전 흐름을 설명합니다. 단순히 “같은 SELECT가 반복되고 있다”고 알아채는 것뿐만 아니라, 수정 후 확인까지 일련의 워크플로우로 수행할 수 있습니다.
1

Requests에서 느린 요청 찾기

/telescope를 열고, Requests 탭에서 실행 시간이 긴 요청을 특정합니다.
2

Queries에서 발행된 SQL 확인

요청의 상세를 열면, 그 요청 중에 실행된 모든 SQL 쿼리가 표시됩니다. 비슷한 SELECT 문이 반복되고 있다면 N+1입니다.
3

Eager Loading을 추가하여 수정

코드에 with()를 추가하고 쿼리를 재확인합니다. 쿼리 수가 대폭 감소했다면 수정 완료입니다.
// N+1이 발생하는 코드
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->user->name; // 게시물의 수만큼 추가 쿼리
}

// Eager Loading으로 해결
$posts = Post::with('user')->get();
디버그용 dd()나 로그를 코드에 추가하지 않고, 이 일련의 흐름을 브라우저 상에서 완결시킬 수 있습니다.

태그를 사용한 특정 요청의 추적

Telescope에는 태그 기능이 있습니다. Telescope::tag()로 엔트리에 임의의 태그를 붙이면, 대시보드의 필터에서 그 태그의 엔트리만을 재빨리 좁힐 수 있습니다. 특정 사용자 ID나 주문 ID에 관련된 처리만을 추적하고 싶은 케이스에서 매우 유용합니다.
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

// TelescopeServiceProvider의 tags 메서드를 오버라이드한다
Telescope::tag(function (IncomingEntry $entry) {
    if ($entry->type === 'request') {
        return array_filter([
            'status:' . $entry->content['response_status'],
            auth()->check() ? 'user:' . auth()->id() : null,
        ]);
    }

    return [];
});
이제 /telescope/requests 화면의 Search에 user:42를 입력하는 것만으로, 사용자 ID=42의 요청만을 일람할 수 있습니다.

모델에 태그를 자동 부여

TelescopeServiceProvidertags 메서드로, 특정 모델 ID를 모든 엔트리에 부여할 수 있습니다.
// TelescopeServiceProvider
Telescope::tag(function (IncomingEntry $entry) {
    return $entry->tags();
});
또한 HasTags 컨트랙트를 모델에 구현함으로써, 그 모델이 기록될 때 자동으로 태그가 붙습니다.
use Laravel\Telescope\Contracts\EntriesRepository;

class Order extends Model implements \Laravel\Telescope\Contracts\HasTags
{
    public function telescopeTags(): array
    {
        return ['order:' . $this->id];
    }
}

Dump 워처 활용

dump()를 사용하면 HTML 응답에 출력이 섞여 들어가 API의 디버그가 어려워질 수 있습니다. Telescope의 Dump 워처를 사용하면 dump()의 출력을 브라우저의 응답에서 분리하여 대시보드에 기록할 수 있습니다. 사용법은 심플합니다. /telescope의 “Dump” 탭을 연 상태에서 dump()를 호출하기만 하면 됩니다.
// 컨트롤러
public function index()
{
    $users = User::with('posts')->get();
    dump($users->first()->toArray()); // Telescope의 dump 탭에 표시됨
    return response()->json($users);
}
페이지를 연 상태에서만 캡처되므로, 필요할 때만 감시할 수 있습니다. dd()와는 달리 앱의 실행을 멈추지 않으므로, 연속된 요청을 흘려보내면서 디버그할 경우에 편리합니다.

Mailpit 연동으로 메일 디버그를 쾌적하게

Mail 워처와 로컬 SMTP 서버인 Mailpit을 조합함으로써, 메일 개발의 흐름이 대폭 개선됩니다.
# .env
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
Telescope의 Mail 탭에서는 송신 메일의 HTML/텍스트 양쪽을 프리뷰할 수 있습니다. Mailpit에서는 수신한 메일을 브라우저에서 확인할 수 있고, 게다가 첨부 파일 확인이나 스팸 스코어 확인도 가능합니다.
테스트 중에 실수로 외부에 메일을 보내지 않도록, 로컬에서는 반드시 Mailpit이나 Mailhog 등의 로컬 SMTP를 사용합시다.

이벤트와 리스너의 디버그

이벤트 드리븐한 구현의 디버그는 종종 어려워집니다. “이벤트는 발화되고 있는가”, “어느 리스너가 호출되고 있는가”를 로그를 보면서 쫓는 것은 번거롭습니다. Telescope의 Events 워처를 사용하면, 발행된 이벤트와 그 리스너가 일람으로 확인할 수 있습니다. 리스너가 호출되지 않는 경우, Events 탭에서 이벤트 엔트리를 확인합니다.
  • 이벤트는 발행되어 있지만 리스너가 표시되지 않음 → 리스너가 등록되어 있지 않음 (EventServiceProvider 확인)
  • 이벤트 자체가 발행되어 있지 않음 → event() 호출 부분 확인
// 테스트 대신 로컬에서 확인하는 흐름
event(new OrderShipped($order));
// → /telescope/events에서 OrderShipped가 표시되는지 확인
// → 리스너 SendShippingConfirmation이 호출되고 있는지 확인

큐 잡의 디버그

비동기 처리의 디버그는 로그를 보는 것만으로는 원인 특정이 어렵습니다. Telescope의 Jobs 워처는 잡의 디스패치부터 실행 결과까지 기록합니다. 실패한 잡의 엔트리를 클릭하면 스택 트레이스와 예외 메시지를 확인할 수 있습니다. queue:failed 테이블과는 별도로 Telescope에서도 확인할 수 있으므로, 실패의 원인 조사를 재빨리 수행할 수 있습니다.
// 잡의 디버그 시에는 sync 드라이버로 동기 실행하면 추적하기 쉽다
// .env
QUEUE_CONNECTION=sync
sync 드라이버로 함으로써, 잡이 요청 내에서 동기 실행되고, Requests 워처에 잡의 실행 결과도 포함됩니다.

HTTP 클라이언트의 디버그

외부 API와의 통신을 디버그할 때, HTTP Client Watcher가 유용합니다. Http:: 파사드에서 이루어진 요청과, 그 응답이 기록됩니다.
$response = Http::get('https://api.example.com/users');
// → /telescope/client-requests에서 확인할 수 있음
응답의 내용, 상태 코드, 실행 시간이 한눈에 보입니다. dd($response->json())을 쓰지 않아도 대시보드에서 확인할 수 있습니다.

정리

테크닉효과
N+1 워크플로우dd() 불필요하게 쿼리 문제를 체계적으로 발견 · 수정
태그 부여특정 사용자 · 모델의 기록을 즉시 좁히기
Dump 워처API 응답을 더럽히지 않고 dump 출력을 확인
Mailpit 연동로컬 메일 개발 쾌적화
Events 워처이벤트/리스너의 발화를 시각적으로 확인
Jobs + sync비동기 처리를 동기 실행하여 디버그
HTTP 클라이언트외부 API 통신의 기록과 확인

Laravel Telescope 가이드

설치와 워처 설정의 상세는 가이드 페이지를 참고하세요.

Laravel Nightwatch

프로덕션 환경의 모니터링은 Nightwatch에서 수행합니다.
마지막 수정일 2026년 7월 13일