> ## 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](/jp/pulse) や [Laravel Nightwatch](/jp/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="/jp/pulse">
    本番環境のパフォーマンス集計ダッシュボードを導入します。
  </Card>

  <Card title="Laravel Nightwatch" icon="moon" href="/jp/blog/nightwatch-introduction">
    本番環境のリアルタイム監視にはNightwatchを使います。
  </Card>
</Columns>