#はじめに
Laravel Telescope は、ローカルのLaravel開発環境に最適なツールです。Telescopeは、アプリケーションへのリクエスト、例外、ログエントリー、データベースクエリ、キューに入ったジョブ、メール、通知、キャッシュ操作、スケジュールされたタスク、変数のダンプなどを詳細に把握できます。
#インストール
Composerパッケージマネージャーを使って、LaravelプロジェクトにTelescopeをインストールできます。
composer require laravel/telescope
Telescopeをインストールしたら、telescope:install Artisanコマンドでアセットを公開してください。また、Telescopeのデータを保存するためのテーブルを作成するために、migrateコマンドも実行する必要があります。
php artisan telescope:install
php artisan migrate
最後に、/telescope ルートからTelescopeのダッシュボードにアクセスできます。
#マイグレーションのカスタマイズ
Telescopeのデフォルトマイグレーションを使わない場合は、アプリケーションの App\Providers\AppServiceProvider クラスの register メソッド内で Telescope::ignoreMigrations メソッドを呼び出してください。デフォルトのマイグレーションは次のコマンドでエクスポートできます：php artisan vendor:publish --tag=telescope-migrations
#ローカル専用インストール
Telescopeをローカル開発の補助としてのみ使う場合は、--dev フラグを使ってインストールできます。
composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate
telescope:install を実行した後、config/app.php の TelescopeServiceProvider サービスプロバイダー登録を削除してください。代わりに、App\Providers\AppServiceProvider クラスの register メソッド内で手動でTelescopeのサービスプロバイダーを登録します。登録前に環境が local であることを確認します。
/**
* Register any application services.
*/
public function register(): void
{
if ($this->app->environment('local')) {
$this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
$this->app->register(TelescopeServiceProvider::class);
}
}
最後に、composer.json ファイルに以下を追加して、Telescopeパッケージの 自動発見 を防止してください。
"extra": {
"laravel": {
"dont-discover": [
"laravel/telescope"
]
}
},
#設定
Telescopeのアセットを公開すると、主な設定ファイルは config/telescope.php に配置されます。この設定ファイルで ウォッチャーのオプション を設定できます。各設定項目には目的の説明があるので、よく確認してください。
必要に応じて、enabled 設定オプションでTelescopeのデータ収集を完全に無効化できます。
'enabled' => env('TELESCOPE_ENABLED', true),
#データのプルーニング
プルーニングを行わないと、telescope_entries テーブルにレコードが急速に蓄積されます。これを防ぐために、telescope:prune Artisanコマンドを毎日 スケジュール で実行してください。
$schedule->command('telescope:prune')->daily();
デフォルトでは24時間以上前のエントリーがすべてプルーニングされます。コマンド実行時に hours オプションを使って保持期間を指定できます。例えば、以下のコマンドは48時間以上前のレコードを削除します。
$schedule->command('telescope:prune --hours=48')->daily();
#ダッシュボードの認可
Telescopeのダッシュボードは /telescope ルートからアクセスできます。デフォルトでは local 環境でのみアクセス可能です。app/Providers/TelescopeServiceProvider.php ファイル内にある 認可ゲート 定義が、local以外の環境でのアクセス制御を行います。必要に応じてこのゲートを変更し、Telescopeへのアクセスを制限してください。
use App\Models\User;
/**
* Register the Telescope gate.
*
* このゲートはlocal以外の環境でTelescopeにアクセスできるユーザーを決定します。
*/
protected function gate(): void
{
Gate::define('viewTelescope', function (User $user) {
return in_array($user->email, [
'[email protected]',
]);
});
}
本番環境では必ず APP_ENV 環境変数を production に設定してください。設定しないとTelescopeが公開されてしまいます。
#Telescopeのアップグレード
Telescopeのメジャーバージョンアップ時は、アップグレードガイドをよく確認してください。
また、Telescopeの新しいバージョンにアップグレードしたら、アセットを再公開してください。
php artisan telescope:publish
アセットを最新に保ち、将来のアップデートで問題が起きないように、composer.json の post-update-cmd スクリプトに vendor:publish --tag=laravel-assets コマンドを追加できます。
{
"scripts": {
"post-update-cmd": [
"@php artisan vendor:publish --tag=laravel-assets --ansi --force"
]
}
}
#フィルタリング
#エントリー
App\Providers\TelescopeServiceProvider クラスの filter クロージャで、Telescopeが記録するデータをフィルタリングできます。デフォルトでは、local 環境ではすべてのデータを記録し、それ以外の環境では例外、失敗したジョブ、スケジュールタスク、監視タグ付きのデータのみを記録します。
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
/**
* Register any application services.
*/
public function register(): void
{
$this->hideSensitiveRequestDetails();
Telescope::filter(function (IncomingEntry $entry) {
if ($this->app->environment('local')) {
return true;
}
return $entry->isReportableException() ||
$entry->isFailedJob() ||
$entry->isScheduledTask() ||
$entry->isSlowQuery() ||
$entry->hasMonitoredTag();
});
}
#バッチ
filter クロージャは個別のエントリーをフィルタリングしますが、filterBatch メソッドはリクエストやコンソールコマンド単位でのすべてのデータをフィルタリングできます。クロージャが true を返すと、そのバッチ内のすべてのエントリーが記録されます。
use Illuminate\Support\Collection;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
/**
* Register any application services.
*/
public function register(): void
{
$this->hideSensitiveRequestDetails();
Telescope::filterBatch(function (Collection $entries) {
if ($this->app->environment('local')) {
return true;
}
return $entries->contains(function (IncomingEntry $entry) {
return $entry->isReportableException() ||
$entry->isFailedJob() ||
$entry->isScheduledTask() ||
$entry->isSlowQuery() ||
$entry->hasMonitoredTag();
});
});
}
#タグ付け
Telescopeは「タグ」でエントリーを検索できます。タグは多くの場合、Eloquentモデルのクラス名や認証済みユーザーIDで、Telescopeが自動的にエントリーに付与します。独自のカスタムタグをエントリーに付けたい場合は、Telescope::tag メソッドを使います。tag メソッドはタグの配列を返すクロージャを受け取り、そのタグはTelescopeが自動付与するタグとマージされます。通常は App\Providers\TelescopeServiceProvider クラスの register メソッド内で tag メソッドを呼び出します。
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
/**
* Register any application services.
*/
public function register(): void
{
$this->hideSensitiveRequestDetails();
Telescope::tag(function (IncomingEntry $entry) {
return $entry->type === 'request'
? ['status:'.$entry->content['response_status']]
: [];
});
}
#利用可能なウォッチャー
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,
],
...
],
#バッチウォッチャー
バッチウォッチャーは、ジョブと接続情報を含むキューの バッチ に関する情報を記録します。
#キャッシュウォッチャー
キャッシュウォッチャーは、キャッシュキーのヒット、ミス、更新、削除時のデータを記録します。
#コマンドウォッチャー
コマンドウォッチャーは、Artisanコマンド実行時の引数、オプション、終了コード、出力を記録します。特定のコマンドを記録から除外したい場合は、config/telescope.php の ignore オプションにコマンド名を指定してください。
'watchers' => [
Watchers\CommandWatcher::class => [
'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
'ignore' => ['key:generate'],
],
...
],
#ダンプウォッチャー
ダンプウォッチャーは、変数のダンプをTelescopeに記録・表示します。Laravelではグローバルの dump 関数で変数をダンプできます。ブラウザでダンプウォッチャータブが開いている場合のみ記録され、そうでない場合は無視されます。
#イベントウォッチャー
イベントウォッチャーは、アプリケーションで発火した イベント のペイロード、リスナー、ブロードキャストデータを記録します。Laravelフレームワーク内部のイベントは無視されます。
#例外ウォッチャー
例外ウォッチャーは、アプリケーションで発生した報告可能な例外のデータとスタックトレースを記録します。
#ゲートウォッチャー
ゲートウォッチャーは、アプリケーションの ゲートとポリシー チェックのデータと結果を記録します。特定のアビリティを記録から除外したい場合は、config/telescope.php の ignore_abilities オプションに指定してください。
'watchers' => [
Watchers\GateWatcher::class => [
'enabled' => env('TELESCOPE_GATE_WATCHER', true),
'ignore_abilities' => ['viewNova'],
],
...
],
#HTTPクライアントウォッチャー
HTTPクライアントウォッチャーは、アプリケーションから送信された HTTPクライアントリクエスト を記録します。
#ジョブウォッチャー
ジョブウォッチャーは、アプリケーションでディスパッチされた ジョブ のデータと状態を記録します。
#ログウォッチャー
ログウォッチャーは、アプリケーションで書き込まれた ログデータ を記録します。
デフォルトでは、Telescopeは error レベル以上のログのみ記録しますが、config/telescope.php の level オプションで変更できます。
'watchers' => [
Watchers\LogWatcher::class => [
'enabled' => env('TELESCOPE_LOG_WATCHER', true),
'level' => 'debug',
],
// ...
],
#メールウォッチャー
メールウォッチャーは、アプリケーションから送信された メール のブラウザ内プレビューと関連データを表示します。メールを .eml ファイルとしてダウンロードすることも可能です。
#モデルウォッチャー
モデルウォッチャーは、Eloquentの モデルイベント 発火時にモデルの変更を記録します。記録するモデルイベントはウォッチャーの events オプションで指定できます。
'watchers' => [
Watchers\ModelWatcher::class => [
'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
'events' => ['eloquent.created*', 'eloquent.updated*'],
],
...
],
リクエスト中にハイドレートされたモデル数を記録したい場合は、hydrations オプションを有効にしてください。
'watchers' => [
Watchers\ModelWatcher::class => [
'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
'events' => ['eloquent.created*', 'eloquent.updated*'],
'hydrations' => true,
],
...
],
#通知ウォッチャー
通知ウォッチャーは、アプリケーションから送信されたすべての 通知 を記録します。通知がメールをトリガーし、メールウォッチャーが有効な場合は、メールもメールウォッチャー画面でプレビューできます。
#クエリウォッチャー
クエリウォッチャーは、アプリケーションで実行されたすべてのクエリの生SQL、バインディング、実行時間を記録します。100ミリ秒以上かかったクエリは slow タグが付きます。slow オプションで遅いクエリの閾値を変更できます。
'watchers' => [
Watchers\QueryWatcher::class => [
'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
'slow' => 50,
],
...
],
#Redisウォッチャー
Redisウォッチャーは、アプリケーションで実行されたすべての Redis コマンドを記録します。Redisをキャッシュに使っている場合は、キャッシュコマンドも記録されます。
#リクエストウォッチャー
リクエストウォッチャーは、アプリケーションが処理したリクエストのリクエスト情報、ヘッダー、セッション、レスポンスデータを記録します。size_limit（キロバイト単位）オプションで記録するレスポンスデータのサイズを制限できます。
'watchers' => [
Watchers\RequestWatcher::class => [
'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
],
...
],
#スケジュールウォッチャー
スケジュールウォッチャーは、アプリケーションで実行された スケジュールタスク のコマンドと出力を記録します。
#ビューウォッチャー
ビューウォッチャーは、ビューをレンダリングする際に使用された ビュー の名前、パス、データ、およびビューコンポーザーを記録します。
#ユーザーアバターの表示
Telescopeのダッシュボードは、エントリー保存時に認証されていたユーザーのアバターを表示します。デフォルトではGravatarサービスを使ってアバターを取得しますが、App\Providers\TelescopeServiceProvider クラスでコールバックを登録してアバターURLをカスタマイズできます。コールバックはユーザーのIDとメールアドレスを受け取り、アバター画像のURLを返す必要があります。
use App\Models\User;
use Laravel\Telescope\Telescope;
/**
* Register any application services.
*/
public function register(): void
{
// ...
Telescope::avatar(function (string $id, string $email) {
return '/avatars/'.User::find($id)->avatar_path;
});
}