How to use Telescope in a Laravel 11 Application
The elegant debugging and monitoring tool for the Laravel web artisan
Introduction
In this article i’ll guide you through how to use Laravel Telescope an elegant debugging assistant that provides complete real-time insights to different part of a Laravel application (requests, exceptions, queries, jobs, caching, queues). It can be used to monitor the development of the application.
Let’s proceed to installing Laravel Telescope in Laravel 11.
Installation
To install Laravel Telescope in your application head over to the terminal of your code editor in your project directory and execute the command below:
composer require laravel/telescope
For local installation use the —dev
flag
composer require laravel/telescope --dev
Next,
Publish Telescope Assets
Use the telescope:install
artisan command to publish the Telescope assets and migrations
php artisan telescope:install
telescope:install
, you should remove the TelescopeServiceProvider
service provider registration from your application's bootstrap/providers.php
configuration file. Instead, manually register Telescope's service providers in the register
method of your App\Providers\AppServiceProvider
class. We will ensure the current environment is local
before registering the providers:/**
* 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);
}
}
Next, execute the migration command to create the database tables needed for Laravel Telescope
php artisan migrate
This will create the necessary files and prepare your database for Telescope's tracking.
composer.json
file:"extra": {
"laravel": {
"dont-discover": [
"laravel/telescope"
]
}
},
Telescope Configurations
The primary telescope configuration file is located at config/telescope.php
which is used to configure watcher options.
- The Telescope can accessed via
/telescope
http://your-app-url/telescope
You can change the path in the telescope configuration file
'path' => env('TELESCOPE_PATH', 'telescope'),
- You can change the Telescope driver for telescope_entries
'driver' => env('TELESCOPE_DRIVER', 'database'),
- To disable Telescope data collection entirely:
'enabled' => env('TELESCOPE_ENABLED', true),
Telescope in production
Setting the TELESCOPE_ENABLED
to false
in your .env
file or in the telescope.php config file automatically disables gathering of data by Telescope in Production environments.
'watchers' => [
'enabled' => env('TELESCOPE_ENABLED', false),
],
- Use the telescope prune command to mitigate accumulation of telescope entries
use Illuminate\Support\Facades\Schedule;
Schedule::command('telescope:prune')->daily();
//records will be deleted after 48 hours
Schedule::command('telescope:prune --hours=48')->daily();
- Authorization
Telescope entries contains sensitive information of the application. One of the outstanding feature is the authorization that can be defined to limit access. Access in production (when APP_ENV
value is not local) is controlled by an authorization gate in TelescopeServiceProvider.php
, which can be modified to manage access.
use App\Models\User;
/**
* Register the Telescope gate.
*
* This gate determines who can access Telescope in non-local environments.
*/
protected function gate(): void
{
Gate::define('viewTelescope', function (User $user) {
return in_array($user->email, [
'info@alemsbaja.io',
]);
});
}
Filtering
- Entries
You can customize the closure below to filter individual entries that is recorded by Telescope.
<?php
namespace App\Providers;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
use Laravel\Telescope\TelescopeApplicationServiceProvider;
class TelescopeServiceProvider extends TelescopeApplicationServiceProvider
{
public function register(): void
{
// Telescope::night();
$this->hideSensitiveRequestDetails();
$isLocal = $this->app->environment('local');
//filter closure
Telescope::filter(function (IncomingEntry $entry) use ($isLocal) {
return $isLocal ||
$entry->isReportableException() ||
$entry->isFailedRequest() ||
$entry->isFailedJob() ||
$entry->isScheduledTask() ||
$entry->hasMonitoredTag();
});
}
}
- Batches
The filterBatch
method may be used to filter all data for a given request or console command. All the entries will be captured by Telescope if the closure returns true:
Telescope::filterBatch(function (IncomingEntry $entry) use ($isLocal) {
return $isLocal ||
$entry->isReportableException() ||
$entry->isFailedRequest() ||
$entry->isFailedJob() ||
$entry->isScheduledTask() ||
$entry->hasMonitoredTag();
});
Tagging
Search can be performed on Telescope entries by using “tag”. They’re automatically added by Telescope but you can create custom tags as shown in the closure below:
Telescope::tag(function (IncomingEntry $entry) {
return $entry->type === 'request'
? ['status:'.$entry->content['response_status']]
: [];
});
Watchers
Watchers collate application data when a request or command is executed. The watchers registered in the telescope config file might be cumbersome for a project so you can configure the watchers based on the project need.
'watchers' => [
Watchers\BatchWatcher::class => env('TELESCOPE_BATCH_WATCHER', true),
........
Watchers\ScheduleWatcher::class => env('TELESCOPE_SCHEDULE_WATCHER', true),
Watchers\ViewWatcher::class => env('TELESCOPE_VIEW_WATCHER', true),
],
This is what it looks like when a watcher is turned off:
Type of Watchers with Demo
Batch watcher: logs application data about queued batches
Cache Watcher: logs data whenever a cache key is accessed, missed, modified, or deleted.
Command Watcher: logs the arguments, options, exit code, and output each time an Artisan command is run.
- Dump Watcher: logs and shows all your variable dumps within Telescope for easy viewing and tracking. The dump tab has to be opened for dump to be recorded.
dump('here')
Event Watcher: logs the payload, listeners, and broadcast details for all events triggered by the application.
Exception Watcher: logs the details and stack trace of any reportable exceptions thrown by your application.
Gate Watcher: logs data and result of gate and policy checks by the application.
HTTP Client Watcher: records all request made by the application.
Job Watcher: logs data and status of any jobs dispatched by your application.
Log Watcher: record application logs
Mail Watcher: The mail watcher provides an in-browser preview of emails sent by your application, along with their related data.
- Model Watcher: logs changes to models whenever an Eloquent model event is triggered. You can specify which model events to track using the watcher's events option.
'watchers' => [
Watchers\ModelWatcher::class => [
'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
'events' => ['eloquent.created*', 'eloquent.updated*'],
],
],
- Notification Watcher: logs all notifications sent by the application.
- Query Watcher: logs the raw SQL, bindings, and execution time for every query executed by the application.
Redis Watcher: logs records about redis command in the application.
Request Watcher: logs the request details, headers, session, and response data for all requests processed by the application
Schedule Watcher: logs the command and output of all scheduled tasks executed by your application.
View Watcher: logs the view name, path, data, and "composers" utilized during the rendering of views.
Look up the Watchers documentation in the Laravel Documentation
Conclusion
Laravel Telescope helps the developer to understand different functionalities and features of a Laravel application. It is an essential tool for Laravel developers. Telescope is an excellent tool to monitor the health and performance of your application during development!
If you find this article useful please kindly share it with your network and feel free to use the comment section for questions, answers, and contributions.