イントロダクション
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のアップデート
Telescopeを更新したら、Telescopeのアセットを再公開してください。
php artisan telescope:publish
特定の環境でのみのインストレーション
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(TelescopeServiceProvider::class);
}
}
マイグレーションのカスタマイズ
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',
]);
});
}
フィルタリング
エンティティ
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ワッチャーは、アプリケーションで実行された全スケジュール済みタスクのコマンドと出力を記録します。