Telescope를 로컬 개발에서 최대한 활용하는 실전 패턴을 소개합니다. N+1 검출, 태그를 사용한 추적, 커스텀 워처, Dump 워처 활용 등 공식 문서만으로는 알기 어려운 노하우를 정리했습니다.
기본적인 설치와 설정은 가이드 페이지를 참고하세요. 이 페이지에서는 공식 문서에 실려 있지 않은, 로컬 개발에서의 실전 활용 패턴을 소개합니다.Telescope는 로컬 개발 전용 도구입니다. 프로덕션 환경의 모니터링에는 Laravel Pulse나 Laravel Nightwatch를 사용해 주세요.
또한 HasTags 컨트랙트를 모델에 구현함으로써, 그 모델이 기록될 때 자동으로 태그가 붙습니다.
use Laravel\Telescope\Contracts\EntriesRepository;class Order extends Model implements \Laravel\Telescope\Contracts\HasTags{ public function telescopeTags(): array { return ['order:' . $this->id]; }}
dump()를 사용하면 HTML 응답에 출력이 섞여 들어가 API의 디버그가 어려워질 수 있습니다. Telescope의 Dump 워처를 사용하면 dump()의 출력을 브라우저의 응답에서 분리하여 대시보드에 기록할 수 있습니다.사용법은 심플합니다. /telescope의 “Dump” 탭을 연 상태에서 dump()를 호출하기만 하면 됩니다.
이벤트 드리븐한 구현의 디버그는 종종 어려워집니다. “이벤트는 발화되고 있는가”, “어느 리스너가 호출되고 있는가”를 로그를 보면서 쫓는 것은 번거롭습니다.Telescope의 Events 워처를 사용하면, 발행된 이벤트와 그 리스너가 일람으로 확인할 수 있습니다.리스너가 호출되지 않는 경우, Events 탭에서 이벤트 엔트리를 확인합니다.
이벤트는 발행되어 있지만 리스너가 표시되지 않음 → 리스너가 등록되어 있지 않음 (EventServiceProvider 확인)
이벤트 자체가 발행되어 있지 않음 → event() 호출 부분 확인
// 테스트 대신 로컬에서 확인하는 흐름event(new OrderShipped($order));// → /telescope/events에서 OrderShipped가 표시되는지 확인// → 리스너 SendShippingConfirmation이 호출되고 있는지 확인
비동기 처리의 디버그는 로그를 보는 것만으로는 원인 특정이 어렵습니다. Telescope의 Jobs 워처는 잡의 디스패치부터 실행 결과까지 기록합니다.실패한 잡의 엔트리를 클릭하면 스택 트레이스와 예외 메시지를 확인할 수 있습니다. queue:failed 테이블과는 별도로 Telescope에서도 확인할 수 있으므로, 실패의 원인 조사를 재빨리 수행할 수 있습니다.