> ## 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，包括本地专用安装、监视器（Watcher）配置等。

## 什么是 Laravel Telescope

[Laravel Telescope](https://github.com/laravel/telescope) 是 Laravel 官方的调试工具，用于将应用内部状态可视化。
它可以详细记录请求、异常、查询、任务、日志、邮件、通知、缓存操作、计划任务等信息。

它是**本地开发环境专用**的调试工具。生产环境监控请使用 [Laravel Pulse](/zh/pulse) 或 [Laravel Nightwatch](/zh/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"
      ]
    }
  }
}
```

***

## 可用的监视器（Watcher）

监视器负责在请求或命令执行期间收集遥测数据。
可以在 `config/telescope.php` 中管理启用状态与配置。

<AccordionGroup>
  <Accordion title="Request Watcher">
    记录请求、请求头、Session 及响应内容。
    可以通过 `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`                |
| 数据库性能排查  | 利用 Query Watcher 的慢查询标签（默认 100ms）          |

## 下一步

<Columns cols={2}>
  <Card title="Laravel Pulse" icon="chart-line" href="/zh/pulse">
    引入用于生产环境性能聚合的仪表盘。
  </Card>

  <Card title="Laravel Nightwatch" icon="moon" href="/zh/blog/nightwatch-introduction">
    生产环境的实时监控可以使用 Nightwatch。
  </Card>
</Columns>


## Related topics

- [Laravel Telescope 实战技巧](/zh/blog/telescope-introduction.md)
- [Laravel Pulse](/zh/pulse.md)
- [用 Laravel 构建 MCP 服务器](/zh/advanced/mcp-server.md)
- [包的版本兼容性管理](/zh/advanced/package-versioning.md)
- [Laravel Nightwatch 入门](/zh/blog/nightwatch-introduction.md)