Laravel Telescope 실전 테크닉

Telescope를 로컬 개발에서 최대한 활용하는 실전 패턴을 소개합니다. N+1 검출, 태그를 사용한 추적, 커스텀 워처, Dump 워처 활용 등 공식 문서만으로는 알기 어려운 노하우를 정리했습니다.

기본적인 설치와 설정은 가이드 페이지를 참고하세요. 이 페이지에서는 공식 문서에 실려 있지 않은, 로컬 개발에서의 실전 활용 패턴을 소개합니다.

Telescope는 로컬 개발 전용 도구입니다. 프로덕션 환경의 모니터링에는 Laravel Pulse나 Laravel 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의 요청만을 일람할 수 있습니다.

​

모델에 태그를 자동 부여

TelescopeServiceProvider의 tags 메서드로, 특정 모델 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에서 수행합니다.