Laravel Telescope徹底解説｜SQL・例外・dumpを丸ごと可視化する公式デバッグツール

技術

はじめに

Laravelで開発していると、つい dd() を乱発して画面を真っ白にしたり、ログを漁って時間を食ったりしていませんか？
「SQLが遅いのはどこ？」「例外の原因を一瞬で知りたい」「dumpしたけどレスポンスを汚したくない」——そんな“デバッグあるある”を一気に解決してくれるのが Laravel Telescope です。

公式パッケージなので導入も簡単。リクエストからSQL、例外、ジョブ、dump出力までをブラウザUIで丸ごと可視化できます。
この記事では インストールから主要ウォッチャーの使いこなし、本番運用のコツ まで徹底的に解説します。

インストールとセットアップ

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

生成される設定ファイル

  • config/telescope.php
    各ウォッチャーや保存期間などを管理する設定ファイル。
  • app/Providers/TelescopeServiceProvider.php
    アクセス制御やフィルタ設定を記述するサービスプロバイダ。

生成されるDBテーブル

php artisan migrate 実行時に以下が作成されます。

  • telescope_entries：記録本体
  • telescope_entries_tags：タグとのリレーション
  • telescope_monitoring：監視対象クラスの管理

アクセス制御（Gate）と有効化/無効化

誰が見られるか制御する

// app/Providers/TelescopeServiceProvider.php

use Illuminate\Support\Facades\Gate;

protected function gate()
{
    Gate::define('viewTelescope', function ($user) {
        return in_array($user->email, [
            'you@example.com',
        ]);
    });
}

環境変数で一括ON/OFF

TELESCOPE_ENABLED=false

本番は原則OFF、障害調査時のみ一時的にONにする運用が安心です。

Dump Watcher：dumpをUIに逃がす

設定ファイル

// config/telescope.php

'dump_watcher' => [
    'enabled' => env('TELESCOPE_DUMP_WATCHER', true),
],

使い方

.envで有効化して dump($foo) を書くだけ。
結果はレスポンスには混ざらず、Telescopeの Dumpsタブ に記録されます。

主要ウォッチャーと活用シーン

Telescopeの「ウォッチャー」はアプリの各領域を監視してくれる仕組みです。ここでは特によく使うものを実務目線で解説します。

Request Watcher（HTTPリクエスト）

  • 記録：メソッド、URL、ステータス、所要時間、入力パラメータ、ヘッダ。
  • 活用：
    • 遅いAPIを特定する。
    • フロント→バックのデータ渡しをチェック。
  • 注意：パスワードやトークンなどはマスク必須。

Query Watcher（SQL）

  • 記録：実行されたSQL、バインド値、実行時間、回数。
  • 活用：
    • N+1問題の検出（同じクエリが大量発行されていないか）。
    • 遅いクエリの発見。

Model Watcher（Eloquentモデル）

  • 記録：モデルの created / updated / deleted イベント。
  • 活用：
    • 意図しない大量更新や削除の発見。
    • モデルイベント／オブザーバーの動きを検証。

Exception Watcher（例外）

  • 記録：例外メッセージ、スタックトレース。
  • 活用：
    • エラー原因を即把握。
    • 本番トラブル時にログを漁る手間が激減。

Job Watcher（ジョブ／キュー）

  • 記録：投入ジョブ、実行／失敗、所要時間、ペイロード。
  • 活用：
    • 遅延処理の詰まりや失敗を一目で確認。
    • リトライ戦略の検証。

Notification / Mail Watcher

  • 記録：通知／メールの宛先、件名、内容。
  • 活用：
    • 通知が飛ばない問題や宛先間違いを即確認。
    • HTMLメールをUI上でプレビュー。

Cache / Redis Watcher

  • 記録：キャッシュ操作、キー、ヒット／ミス。
  • 活用：
    • キャッシュ戦略の妥当性チェック。
    • ミスが多い処理を改善。

View Watcher

  • 記録：レンダリングされたビュー、渡されたデータ。
  • 活用：
    • Bladeに無駄なデータを渡していないか確認。
    • 複雑なビューがどの程度負荷になっているか把握。

Log Watcher

  • 記録：logger() / Log::* の出力。
  • 活用：
    • わざわざログファイルを見なくてもUIで流れを追える。
    • 本番ではstdoutログと合わせてチェックできる。

Command / Schedule Watcher

  • 記録：Artisanコマンドやスケジュール実行の履歴と出力。
  • 活用：
    • 定期バッチが走っているか確認。
    • 失敗や長時間実行を検出。

フィルタとマスク

Telescope は強力ですが、全てを無制限に記録すると ノイズ過多 や 情報漏洩リスク につながります。
そこで重要なのが フィルタ と マスク の設定です。

フィルタで不要なイベントを除外する

app/Providers/TelescopeServiceProvider.php で記録対象を制御できます。

use Laravel\Telescope\Telescope;
use Laravel\Telescope\IncomingEntry;

public function booted()
{
    Telescope::filter(function (IncomingEntry $entry) {
        if (app()->isLocal()) {
            return true; // ローカルは全部
        }

        // 本番は重要なものだけ
        return $entry->isReportableException()
            || $entry->isFailedRequest()
            || $entry->isFailedJob()
            || $entry->isScheduledTask()
            || $entry->isSlowQuery();
    });
}
  • ローカル → 全ログを残して開発効率優先
  • 本番 → 失敗や遅延など重要なログだけ

こうすれば監視に必要な情報だけを安全に集められます。

マスクで機密データを隠す

次に大事なのが マスク処理。
デフォルトで password などは隠されますが、APIキーやトークン類は追加でマスク必須です。

// config/telescope.php

return [
    'hide' => [
        'request_headers' => [
            'authorization', 'cookie',
        ],
        'request_parameters' => [
            'password', 'password_confirmation', 'api_key',
            'access_token', 'refresh_token',
        ],
        'query' => [
            'token',
        ],
        'user' => [
            'password', 'remember_token',
        ],
    ],
];

動的に追加する場合は app/Providers/TelescopeServiceProvider.php の booted() で、Telescope::hideRequestParameters() や Telescope::hideRequestHeaders() を呼び出せます。

use Laravel\Telescope\Telescope;

public function booted()
{
    // クレカ・SSN をリクエストパラメータからマスク
    Telescope::hideRequestParameters(['credit_card_number', 'ssn']);

    // カスタムヘッダをマスク
    Telescope::hideRequestHeaders(['x-custom-auth']);

    // DBクエリで隠したいパラメータ
    Telescope::hideQueryParameters(['secret_token']);

    // ユーザー情報の特定カラムをマスク
    Telescope::hideUserAttributes(['two_factor_code']);
}

マスク対象の具体例（ケース別）

認証・ユーザー管理系

  • password, password_confirmation, remember_token
  • two_factor_code, otp

OAuth / API 認証系

  • access_token, refresh_token, client_secret, id_token, api_key

決済系

  • credit_card_number, cvc, account_number, stripe_token

社内業務系

  • employee_id, internal_secret, admin_code

HTTPヘッダ

  • authorization, cookie, x-api-key, x-custom-auth

実運用のポイント

  • フィルタ → 本番では「失敗・遅延・例外」に絞る
  • マスク → 認証情報・金融データ・個人情報を徹底的に隠す
  • 新機能追加時に見直し → APIや認証フローが増えたらマスク対象も更新

この仕組みを徹底すれば、Telescope を 安全かつ効率的に使い倒す ことができます。

データ保存期間とPrune

Telescopeの記録はDBに蓄積されるため、定期削除が必須です。

php artisan telescope:prune --hours=48

スケジュールに登録：

$schedule->command('telescope:prune --hours=48')->daily();

運用Tips

  • ローカル：Request / Query / Exception / Dumps を常時ON。
  • 本番調査：必要なウォッチャーだけON、Filterで遅クエリや例外に絞る。
  • 調査後：必ずOFFに戻してPrune実行。

まとめ

Laravel Telescope は「IDEでブレークポイント張るまでもないちょっとした確認」を一瞬で片付けてくれる、いわば “開発者のダッシュボード” です。
SQL、例外、リクエスト、ジョブ、イベント……アプリのあらゆる挙動がリアルタイムで可視化されるので、デバッグ効率が格段に上がります。

特に リクエストやSQLの挙動をブラウザで一覧できる体験 は、一度味わうと手放せません。
dump() もブラウザ上に綺麗に整列して表示されるので、チーム開発で「ログ漁り合戦」をしなくても済むようになります。

また、フィルタやマスクを組み合わせることで、環境に合わせた柔軟な運用 も可能。
ローカルでは「全部見る」、ステージングでは「主要イベントだけ」、本番では「監視対象に絞る」といった切り替えが簡単に実現できます。

つまり Telescope は、単なるデバッグツールにとどまらず、開発から運用までをスムーズにつなぐ公式サポーター。
積極的に使っていくことで、Laravel 開発はさらに快適で効率的になるはずです。

コメント

タイトルとURLをコピーしました