Getting Started with Laravel Telescope: Your Ultimate Debugging Assistant #
Laravel Telescope is an elegant debugging assistant for the Laravel framework. It provides insight into the requests coming into your application, exceptions, log entries, database queries, queued jobs, mail, notifications, cache operations, scheduled tasks, variable dumps, and more. Telescope makes debugging and understanding your Laravel application's behavior incredibly intuitive, especially during development.
Why Laravel Telescope?
Before Telescope, developers often relied on dd() statements, log files, or browser dev tools. While effective, these methods could be cumbersome. Telescope aggregates all crucial application activities into a beautiful, centralized web interface, offering real-time insights and historical data, significantly streamlining the development workflow.
Installation
Installing Laravel Telescope is straightforward. Start by pulling the package into your project using Composer:
composer require laravel/telescope
After installation, publish Telescope's assets and run its database migrations. This will create the necessary tables to store its data.
php artisan telescope:install
php artisan migrate
By default, Telescope will only be installed for the local environment. If you want to use it in other environments (e.g., staging), you can adjust your composer.json or explicitly add --dev when requiring it and then move it to require. For production, it's generally recommended to keep it disabled or strictly secured.
Configuration and Access
Telescope's configuration file is config/telescope.php. You can publish it for customization if needed:
php artisan vendor:publish --provider="Laravel\Telescope\TelescopeServiceProvider"
Enabling/Disabling Telescope
You can control Telescope's active status via the TELESCOPE_ENABLED environment variable in your .env file:
TELESCOPE_ENABLED=true
Authorizing Telescope Access
For security, especially in non-local environments, you must restrict access to the Telescope dashboard. Laravel Telescope comes with a simple gate for this. By default, it allows access only in the local environment. You can customize this in your App\Providers\TelescopeServiceProvider:
use Laravel\Telescope\Telescope;
use Illuminate\Support\Facades\Gate;
/**
* Register the Telescope gate.
*
* This gate determines who can access Telescope in non-local environments.
*
* @return void
*/
protected function gate()
{
Gate::define('viewTelescope', function ($user) {
return in_array($user->email, [
'[email protected]',
]);
});
}
Replace '[email protected]' with the email addresses of users who should have access. For production, it's highly recommended to completely disable Telescope or ensure extremely strict access control.
Diving into Telescope's Features
Once installed, you can access the Telescope dashboard by navigating to /telescope in your browser. Here's a look at its core features:
1. Requests
Monitor all incoming HTTP requests. You can inspect request headers, session data, payload, response, and even performance metrics like total duration, application duration, and memory usage.
2. Commands
Track Artisan command executions. Useful for debugging console commands and understanding their lifecycle.
3. Schedule
View scheduled tasks and their execution status. This helps in verifying if your cron jobs are running as expected.
4. Jobs
Observe all queued jobs – pending, completed, or failed. You can even retry failed jobs directly from the UI.
5. Cache
Monitor cache operations: hits, misses, gets, puts, forgets. Essential for optimizing cache usage.
6. Events
Inspect events dispatched by your application. See which listeners are attached and if they are handled correctly.
7. Mail
Preview sent emails directly in the browser without actually sending them. This is a massive time-saver during development.
8. Notifications
Similar to mail, preview notifications (e.g., database, mail, SMS via custom channels) sent by your application.
9. Gates
Track authorization checks (Laravel Gates and Policies), showing what was checked and the result (allowed/denied).
10. Dumps
Any dump() calls in your application will appear here, providing a clean, organized view of dumped variables without cluttering your browser output.
11. Queries
Inspect all database queries executed by your application, including their execution time, connection, and full SQL statement. Slow queries are highlighted, helping identify performance bottlenecks.
12. Exceptions
Catch and view all uncaught exceptions, along with their stack traces and relevant request data.
13. Logs
All log entries written via Laravel's logging facilities are captured, making it easy to review application activity.
14. Redis
Monitor Redis commands executed by your application, providing insights into your Redis usage.
Customization: Filtering Entries
You can customize which entries Telescope records. In your TelescopeServiceProvider, within the boot method, you can use Telescope::filter to define your logic:
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
/**
* Register any application services.
*/
public function register(): void
{
// ... other registrations
Telescope::filter(function (IncomingEntry $entry) {
if (app()->environment('local')) {
return true;
}
return $entry->isReportableException() ||
$entry->isFailedJob() ||
$entry->isScheduledTask() ||
$entry->hasTag('important'); // Example: only log entries with 'important' tag
});
}
This example shows how to only record specific types of entries or entries with custom tags when not in the local environment.
Pruning Entries
Telescope can accumulate a lot of data. You should prune old entries regularly. You can schedule the telescope:prune Artisan command:
// in app/Console/Kernel.php
protected function schedule(Schedule $schedule): void
{
$schedule->command('telescope:prune')->daily(); // Prune daily (default 7 days retention)
// Or prune based on retention days (e.g., older than 48 hours)
// $schedule->command('telescope:prune --hours=48')->hourly();
}
Conclusion
Laravel Telescope transforms the debugging experience, offering a comprehensive and intuitive overview of your application's internals. From monitoring HTTP requests and database queries to inspecting emails and queued jobs, Telescope provides invaluable insights that accelerate development and enhance understanding of your Laravel applications. Integrate it into your development workflow today and experience a new level of productivity!
