> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Telescope

> Laravel Telescope 도입을 설명합니다. 로컬 전용 설치, 워처 구성까지 다룹니다.

## Laravel Telescope란

[Laravel Telescope](https://github.com/laravel/telescope)는 Laravel 애플리케이션의 내부 상태를 시각화하는 공식 디버깅 도구입니다.
요청, 예외, 쿼리, 잡, 로그, 메일, 알림, 캐시 조작, 스케줄 실행 등을 상세하게 기록할 수 있습니다.

**로컬 개발 환경 전용** 디버깅 도구입니다. 프로덕션 환경 모니터링에는 [Laravel Pulse](/ko/pulse)나 [Laravel Nightwatch](/ko/blog/nightwatch-introduction)를 사용해 주세요.

### 모니터링 대상 레이어

```mermaid theme={null}
flowchart LR
    A["HTTP 레이어<br>Request / Response"] --> T["Telescope 엔트리 저장"]
    B["애플리케이션 레이어<br>Events / Logs / Exceptions"] --> T
    C["데이터 레이어<br>DB Queries / Redis / Cache"] --> T
    D["비동기 레이어<br>Queue Jobs / Schedule / Notifications"] --> T
    T --> E["대시보드<br>/telescope"]
```

***

## 설치

<Steps>
  <Step title="Telescope를 설치한다">
    ```shell theme={null}
    composer require laravel/telescope
    ```
  </Step>

  <Step title="에셋과 마이그레이션을 게시한다">
    ```shell theme={null}
    php artisan telescope:install
    ```
  </Step>

  <Step title="마이그레이션을 실행한다">
    ```shell theme={null}
    php artisan migrate
    ```
  </Step>
</Steps>

설치 후 `/telescope`에서 대시보드에 접근할 수 있습니다.

## 로컬 전용 설치(권장)

<Info>
  로컬 개발에서의 디버깅이 주된 목적이라면, `--dev`로 설치하고 서비스 프로바이더를 `local` 환경에서만 수동 등록하는 구성을 권장합니다.
</Info>

```shell theme={null}
composer require laravel/telescope --dev

php artisan telescope:install
php artisan migrate
```

`telescope:install` 실행 후에는 `bootstrap/providers.php`에서 `TelescopeServiceProvider`의 등록을 삭제해 주세요.
그런 다음 `App\Providers\AppServiceProvider`의 `register` 메서드에서 수동 등록합니다.

```php theme={null}
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);
    }
}
```

추가로 `composer.json`에서 auto-discovery를 비활성화해 주세요.

```json theme={null}
{
  "extra": {
    "laravel": {
      "dont-discover": [
        "laravel/telescope"
      ]
    }
  }
}
```

***

## 사용 가능한 워처

워처는 요청이나 명령 실행 시의 텔레메트리를 수집합니다.
`config/telescope.php`에서 활성화·설정을 관리합니다.

<AccordionGroup>
  <Accordion title="Request Watcher">
    요청, 헤더, 세션, 응답을 기록합니다.\
    `size_limit`으로 응답 기록 크기를 제한할 수 있습니다.
  </Accordion>

  <Accordion title="Query Watcher(특히 중요)">
    SQL, 바인딩, 실행 시간을 기록합니다.\
    기본적으로 **100ms** 초과 쿼리가 `slow` 태그로 기록되므로 성능 병목 감지에 매우 유용합니다.

    ```php theme={null}
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 100,
    ],
    ```
  </Accordion>

  <Accordion title="Job Watcher">
    큐 잡의 투입과 실행 결과를 기록합니다.
  </Accordion>

  <Accordion title="Exception Watcher">
    report 대상 예외와 스택 트레이스를 기록합니다.
  </Accordion>

  <Accordion title="Log Watcher">
    애플리케이션 로그를 기록합니다.\
    기본은 `error` 이상이며, 설정에서 `debug`까지 낮출 수 있습니다.
  </Accordion>

  <Accordion title="Command Watcher">
    Artisan 명령의 인수, 옵션, 출력, 종료 코드를 기록합니다.
  </Accordion>

  <Accordion title="Event Watcher">
    dispatch된 이벤트의 페이로드와 리스너 정보를 기록합니다(Laravel 내부 이벤트는 제외).
  </Accordion>

  <Accordion title="Cache Watcher">
    캐시의 히트, 미스, 갱신, 삭제를 기록합니다.
  </Accordion>

  <Accordion title="Redis Watcher">
    애플리케이션에서 실행된 Redis 명령을 기록합니다.
  </Accordion>

  <Accordion title="Model Watcher">
    Eloquent 모델 이벤트를 기록하고, 필요에 따라 hydration 건수도 수집할 수 있습니다.
  </Accordion>

  <Accordion title="Notification Watcher">
    전송된 알림을 기록합니다.
  </Accordion>

  <Accordion title="Mail Watcher">
    전송된 메일을 브라우저에서 미리보기 하고 `.eml`로 다운로드할 수 있습니다.
  </Accordion>

  <Accordion title="HTTP Client Watcher">
    외부로 향하는 HTTP 클라이언트 요청을 기록합니다.
  </Accordion>

  <Accordion title="Gate Watcher">
    Gate / Policy의 인가 체크 결과를 기록합니다.
  </Accordion>

  <Accordion title="Schedule Watcher">
    스케줄 실행된 명령과 출력을 기록합니다.
  </Accordion>

  <Accordion title="View Watcher">
    렌더링된 뷰 이름, 경로, 데이터, composer를 기록합니다.
  </Accordion>

  <Accordion title="Batch Watcher">
    큐 배치 정보(잡이나 커넥션 정보)를 기록합니다.
  </Accordion>

  <Accordion title="Dump Watcher">
    Telescope의 Dump 탭이 열려 있는 동안의 `dump` 출력을 기록합니다.
  </Accordion>
</AccordionGroup>

***

## 정리

| 작업            | 권장 설정                                      |
| ------------- | ------------------------------------------ |
| 도입            | `composer require laravel/telescope --dev` |
| 로컬 전용의 확실한 분리 | 수동 프로바이더 등록 + `dont-discover`              |
| DB 성능 조사      | Query Watcher의 slow 쿼리 태그(기본 100ms) 활용     |

## 다음 단계

<Columns cols={2}>
  <Card title="Laravel Pulse" icon="chart-line" href="/ko/pulse">
    프로덕션 환경의 퍼포먼스 집계 대시보드를 도입합니다.
  </Card>

  <Card title="Laravel Nightwatch" icon="moon" href="/ko/blog/nightwatch-introduction">
    프로덕션 환경의 실시간 모니터링에는 Nightwatch를 사용합니다.
  </Card>
</Columns>


## Related topics

- [Laravel Telescope 실전 테크닉](/ko/blog/telescope-introduction.md)
- [Laravel Pulse](/ko/pulse.md)
- [Laravel에서 MCP 서버 만들기](/ko/advanced/mcp-server.md)
- [패키지의 버전 호환성 관리](/ko/advanced/package-versioning.md)
- [Laravel Nightwatch 입문](/ko/blog/nightwatch-introduction.md)