Laravel 7.x Laravel Telescope

イントロダクション

Laravel TelescopeはLaravelフレームワークのエレガントなデバッグアシスタントです。Telescopeはアプリケーションへ送信されたリクエスト、例外、ログエンティティ、データクエリ、キュージョブ、メール、通知、キャッシュ操作、スケジュールされたタスク、さまざまなダンプなどを提示します。TelescopeはLaravelローカル開発環境における、素晴らしいコンパニオンです。

インストレーション

LaravelプロジェクトへTelescopeをインストールするには、Composerを使用します。

composer require laravel/telescope

Telescopeをインストールしたら、telescope:install Artisanコマンドを使用し、アセットをリソース公開してください。Telescopeのインストールが終わったら、migrateコマンドも実行する必要があります。

php artisan telescope:install

php artisan migrate

特定の環境でのみのインストレーション

Telescopeをローカル環境でのみ使用する場合は、--devフラグを付けてインストールします。

composer require laravel/telescope --dev

telescope:install実行後、app設定ファイルからTelescopeServiceProviderサービスプロバイダの登録を削除する必要があります。app設定ファイルで登録する代わりに、このサービスプロバイダをAppServiceProviderのregisterメソッドで登録してください。

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    if ($this->app->isLocal()) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

また、composer.jsonへ以下の内容を追加することにより、Telescopeが自動検出されるのを防げます。

"extra": {
    "laravel": {
        "dont-discover": [
            "laravel/telescope"
        ]
    }
},

マイグレーションのカスタマイズ

Telescopeのデフォルトマイグレーションに従わない場合、AppServiceProviderのregisterメソッドの中で、Telescope::ignoreMigrationsメソッドを呼び出す必要があります。php artisan vendor:publish --tag=telescope-migrationsコマンドを使い、デフォルトマイグレーションをエクスポートすることもできます。

設定

Telescopeのアセットをリソース公開すると、主となる設定ファイルがconfig/telescope.phpへ設置されます。この設定ファイルでワッチャーのオプションや、説明をコメントで記述している各種の設定オプションを調整できます。そのため、このファイルを全部読んでください。

望むのであれば、enabled設定オプションを使用し、Telescopeのデータ収集全体を無効にできます。

'enabled' => env('TELESCOPE_ENABLED', true),

データの刈り込み

データを刈り込まないと、telescope_entriesテーブルへとても早くレコードが集積してしまいます。これを軽減するために、telescope:prune Artisanコマンドを毎日実行するように、スケジュールすべきでしょう。

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

デフォルトでは、24時間を過ぎているすべてのエンティティが削除されます。Telescopeデータをどの期間保持するかを指定するために、コマンド呼び出し時にhoursオプションが使えます。

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

ダッシュボードの認可

Telescopeはデフォルトで、ダッシュボードを/telescopeで表示します。デフォルトではlocal環境からのみ、このダッシュボードへアクセスできます。app/Providers/TelescopeServiceProvider.phpファイルの中に、gateメソッドが存在しています。この認可ゲートで、Telescopeのlocal以外でのアクセスをコントロールできます。Telescopeに対するアクセスを宣言する必要に応じ、このゲートを自由に変更してください。

/**
 * Telescopeゲートの登録
 *
 * このゲートはlocal以外の環境で、誰がTelescopeへアクセスできるかを決定している。
 *
 * @return void
 */
protected function gate()
{
    Gate::define('viewTelescope', function ($user) {
        return in_array($user->email, [
            'taylor@laravel.com',
        ]);
    });
}

Note: 実行環境では、APP_ENV環境変数を必ずproductionに変更してください。それ以外の値の場合、Telescopeインストールは一般公開されます。

Telescopeのアップグレード

Telescopを新しいバージョンへアップグレードするときは、Telescopeのアセットを必ず再リソース公開してください。

php artisan telescope:publish

アセットを最新状態に保ち、将来のアップデートで起きる問題を防ぐために、アプリケーションのcomposer.jsonファイルのpost-update-cmdスクリプトへtelescope:publishコマンドを追加しておくのが良いでしょう。

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan telescope:publish --ansi"
        ]
    }
}

フィルタリング

エンティティ

TelescopeServiceProviderの中で登録されているfilterコールバックにより、Telescopeが保存するデータをフィルタリングできます。デフォルトでは、このコールバックはlocal環境、例外、失敗したジョブ、スケジュール済みタスク、他の全環境においてモニター対象とタグ付けされたデータを記録します。

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();

    Telescope::filter(function (IncomingEntry $entry) {
        if ($this->app->isLocal()) {
            return true;
        }

        return $entry->isReportableException() ||
            $entry->isFailedJob() ||
            $entry->isScheduledTask() ||
            $entry->hasMonitoredTag();
    });
}

バッチ

fileterコールバックで個別のエンティティのデータをフィルタリングできますが、指定したリクエストやコンソールコマンドの全データをフィルタリングするコールバックをfilterBatchメソッドにより登録できます。コールバックがtrueを返すと、Telescopeによりすべてのエンティティが保存されます。

use Illuminate\Support\Collection;

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();

    Telescope::filterBatch(function (Collection $entries) {
        if ($this->app->isLocal()) {
            return true;
        }

        return $entries->contains(function ($entry) {
            return $entry->isReportableException() ||
                $entry->isFailedJob() ||
                $entry->isScheduledTask() ||
                $entry->hasMonitoredTag();
            });
    });
}

タグ付け

Telescopeでは「タグ」により検索を登録できます。タグはEloquentモデルクラス名や認証済みユーザーのIDが多いでしょうが、Telescopeは自動的にエントリーを登録します。まれに、独自のカスタムタグエントリーを追加する必要も起きるでしょう。その場合は、Telescope::tagメソッドを使用してください。tagメソッドはタグの配列を返すコールバックを引数に取ります。コールバックから返されたタグは、Telescopeが自動的にエントリーに追加したタグとマージされます。tagメソッドは、TelescopeServiceProviderの中で呼び出してください。

use Laravel\Telescope\Telescope;

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();

    Telescope::tag(function (IncomingEntry $entry) {
        if ($entry->type === 'request') {
            return ['status:'.$entry->content['response_status']];
        }

        return [];
    });
 }

利用可能なワッチャー

Telescopeのワッチャーは、リクエストやコマンドが実行されると、アプリケーションデータを収集します。config/telescope.php設定ファイルで、ワッチャーのリストを有効にすることにより、カスタマイズできます。

'watchers' => [
    Watchers\CacheWatcher::class => true,
    Watchers\CommandWatcher::class => true,
    ...
],

いくつかのワッチャーには、追加のカスタマイズオプションが用意されています。

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 100,
    ],
    ...
],

Cacheワッチャー

Cacheワッチャーは、キャッシュキーのヒット、不一致、削除時にデータを記録します。

Commandワッチャー

Commandワッチャーは、Artisanコマンドが実行されたときの引数、オプション、終了コード、出力コードを記録します。このワッチャーの対象から特定のコマンドを外したい場合は、config/telescope.phpファイルのignoreオプションの中で、除外するコマンドを指定してください。

'watchers' => [
    Watchers\CommandWatcher::class => [
        'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
        'ignore' => ['key:generate'],
    ],
    ...
],

Dumpワッチャー

Dumpワッチャーは、Telescope中の変数のダンプを記録し、表示します。Laravelを使ってるなら、グローバルdump関数を使用し変数をダンプできます。記録される時点でDumpワッチャータブは、ブラウザで開かれていなければなりません。開かれてなければ、ワッチャーはダンプを無視します。

Eventワッチャー

Eventワッチャーは、アプリケーションで発行されたすべてのイベントのペイロード（本体）、リスナ、ブロードキャストデータを記録します。Eventワッチャーは、Laravelフレームワーク内部のイベントを無視します。

Exceptionワッチャー

Exceptionワッチャーはアプリケーションで投げられた、reportableな全例外のデータとスタックトレースを記録します。

Gateワッチャー

Gateワッチャーは、アプリケーションのゲートとポリシーチェックによる、データと結果を記録します。特定のアビリティをこのワッチャーで記録されないようにしたい場合は、config/telescope.phpファイルのignore_abilitiesオプションで指定してください。

'watchers' => [
    Watchers\GateWatcher::class => [
        'enabled' => env('TELESCOPE_GATE_WATCHER', true),
        'ignore_abilities' => ['viewNova'],
    ],
    ...
],

Jobワッチャー

Jobワッチャーは、アプリケーションでディスパッチされた全ジョブのデータと状態を記録します。

Logワッチャー

Logワッチャーは、アプリケーションにより書き出されたすべてのログデータを記録します。

Mailワッチャー

Mailワッチャーにより、メールのプレビューに加え、関連するデータをブラウザで確認できます。さらに、.emlファイルとしてメールをダウンロードできます。

Modelワッチャー

Modelワッチャーは、Eloquentのcreated、updated、restored、deletedイベントがディスパッチされた時点のモデルの変更を記録します。このワッチャーのeventsオプションにより、どのモデルイベントを記録するかを指定できます。

'watchers' => [
    Watchers\ModelWatcher::class => [
        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
        'events' => ['eloquent.created*', 'eloquent.updated*'],
    ],
    ...
],

Notificationワッチャー

Notificationワッチャーは、アプリケーションにより送信された全通知を記録します。通知がメールを送信し、Mailワッチャーが有効になっていれば、Mailワッチャー画面によりプレビューも利用できます。

Queryワッチャー

Queryワッチャーは、アプリケーションにより実行された全クエリのSQL文とバインド、実行時間を記録します。このワッチャーは、100msよりも遅いクエリをslowとしてタグ付けします。ワッチャーのslowオプションにより、このスロークエリの判定時間をカスタマイズできます。

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 50,
    ],
    ...
],

Redisワッチャー

Redisワッチャーはアプリケーションで実行された全Redisコマンドを記録します。Redisをキャッシュで利用する場合、キャッシュコマンドもRedisワッチャーにより記録されます。

Requestワッチャー

Requestワッチャーはアプリケーションにより処理された全リクエスト、ヘッダ、セッション、レスポンスデータを記録します。size_limitオプションによりKB単位でレスポンデータを制限できます。

'watchers' => [
    Watchers\RequestWatcher::class => [
        'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
        'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
    ],
    ...
],

Scheduleワッチャー

Scheduleワッチャーは、アプリケーションで実行された全スケジュール済みタスクのコマンドと出力を記録します。

ユーザーアバターの表示

Telescopeダッシュボードは与えられたエントリーが保存されている時、ログインしているユーザーのアバターを表示します。TelescopeはデフォルトでGravatar Webサービスを使用してアバターを取得します。しかし、TelescopeSeerviceProviderでコールバックを登録すれば、アバターのURLをカスタマイズできます。コールバックにはユーザーのIDとメールアドレスが渡されますので、ユーザーのアバターイメージのURLを返す必用があります。

use App\User;
use Laravel\Telescope\Telescope;

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    Telescope::avatar(function ($id, $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}

ドキュメント章別ページ

前章
リリースノート アップグレードガイド 貢献ガイド
API
APIドキュメント
準備
インストール 設定 ディレクトリ構造 Homestead Valet デプロイ
構成の概念
ライフサイクル サービスコンテナ サービスプロバイダ ファサード 契約
基礎
ルーティング ミドルウェア CSRF保護 コントローラ リクエスト レスポンス ビュー URL生成 セッション バリデーション エラー処理 ログ
フロントエンド
Bladeテンプレート 多言語化 スカフォールド アセットコンパイル
セキュリティ
認証 認可 メール確認 暗号化 ハッシュ パスワードリセット
より深く知る
Artisanコンソール ブロードキャスト キャッシュ コレクション イベント ファイルストレージ ヘルパ HTTPクライアント メール 通知 パッケージ開発 キュー タスクスケジュール
データベース
データベースの準備 クエリビルダ ペジネーション マイグレーション シーディング Redis
Eloquent ORM
Eloquentの準備 リレーション コレクション ミューテタ APIリソース シリアライズ
テスト
テストの準備 HTTPテスト コンソールテスト ブラウザテスト データベース モック
公式パッケージ
Cashier (Stripe) Cashier (Paddle) Cashier (Mollie) Dusk Envoy Horizon Passport Sanctum Scout Socialite Telescope
言語 ファイル
auth.php pagination.php passwords.php validation.php

ヘッダー項目移動

注目：アイコン：ページ内リンク設置（リンクがないヘッダーへの移動では、リンクがある以前のヘッダーのハッシュをURLへ付加します。

移動

クリックで即時移動します。

リンク
サイトホーム ページ上部へ
言語
バージョン
10.x 9.x 8.x 7.x 6.x LTS 5.8 5.7 5.6 5.5 LTS 5.4 5.3 5.2 5.1 LTS 5.0 5.dev 4.2

設定

適用ボタンクリック後に、全項目まとめて適用されます。

カラーテーマ
和文指定 Pagination
和文指定 Scaffold
Largeスクリーン表示幅
インデント
本文フォント
コードフォント
フォント適用確認

フォントの指定フィールドから、フォーカスが外れると、当ブロックの内容に反映されます。EnglishのDisplayもPreviewしてください。

フォント設定時、表示に不具合が出た場合、当サイトのクッキーを削除してください。

バックスラッシュを含むインライン\Code\Blockの例です。

以下はコードブロックの例です。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * ユーザに関連する電話レコードを取得
     */
    public function phone()
    {
        return $this->hasOne('App\Phone');
    }
}

設定を保存する前に、表示が乱れないか必ず確認してください。CSSによるフォントファミリー指定の知識がない場合は、フォントを変更しないほうが良いでしょう。

キーボード・ショートカット

オープン操作

P／D／C

ページ（章）移動の左オフキャンバスオープン

H／A

ヘッダー移動モーダルオープン

M／S

移動／設定の右オフキャンバスオープン

ヘッダー移動

T

最初のヘッダーへ移動

E

最後のヘッダーへ移動

N／J

次ヘッダー(H2〜H4)へ移動

B／K

前ヘッダー(H2〜H4)へ移動

その他

?

このヘルプページ表示
閉じる