Debugging Laravel with Laravel Telescope

Summary: Use Telescope for real-time debugging and performance monitoring.

Laravel is a powerful PHP framework that simplifies web application development. However, complex applications often require deep visibility into their inner workings, especially during debugging and performance tuning. Laravel Telescope is Laravel’s official debug assistant, providing real-time insight into requests, exceptions, queries, and more. In this blog post, we'll dive into how to install, configure, and use Telescope to streamline your Laravel debugging experience.

What is Laravel Telescope?

Laravel Telescope is a powerful debugging and profiling tool for Laravel applications. It effortlessly monitors and displays requests, database queries, queued jobs, log entries, exceptions, cache operations, scheduled tasks, and much more directly from a beautiful web interface.

Telescope provides developers with:

  • Real-time monitoring: Inspect what's happening right as you develop.
  • Detailed profiling: Analyze database queries, jobs, cache hits/misses, and other events.
  • Exception tracking: Instantly see stack traces and debug errors.
  • Performance monitoring: Identify bottlenecks and long-running operations.

Installing Laravel Telescope

To get started with Telescope, make sure your Laravel application meets the version requirements. Laravel 8.x and higher are supported.

Install Telescope via Composer:

composer require laravel/telescope --dev

The --dev flag ensures Telescope is only installed in local and development environments.

Publishing Telescope Resources

Publish Telescope’s resources:

php artisan telescope:install

Then, migrate your database to add Telescope’s tables:

php artisan migrate

Securing Telescope

By default, Telescope’s dashboard is only accessible in the local environment. To modify access, update the TelescopeServiceProvider:

// app/Providers/TelescopeServiceProvider.php

protected function gate()
{
    Gate::define('viewTelescope', function ($user) {
        // Restrict access to specific users
        return in_array($user->email, [
            'your@email.com',
        ]);
    });
}

Using the Telescope Dashboard

After installation, launch your Laravel development server:

php artisan serve

Navigate to /telescope in your browser (e.g. http://localhost:8000/telescope).

The dashboard provides a sleek interface, broken down into core panels:

  • Requests: View all incoming HTTP requests, their response status, execution time, and associated user (if any).
  • Exceptions: Instantly see every thrown exception, complete with stack traces.
  • Logs: Review log entries, including their level, message, and context.
  • Database Queries: Analyze queries, bound parameters, execution time, and source files that originated them.
  • Jobs: Observe dispatched and processed queued jobs, including their status and payload.
  • Events: Explore broadcasted/listened events and their listeners.
  • Cache: Inspect cache hits, misses, writes, and tags.
  • Mail: Review sent emails, including content, recipients, and even mailable preview.
  • Notifications: Debug notifications sent to users.
  • Commands, Schedules, Dumps, Gates: Comprehensive tracking of many other aspects.

Each entry provides deep details, helping developers quickly pinpoint issues or performance bottlenecks.

Real-Time Debugging with Telescope

Let's explore some common debugging scenarios and how Telescope helps:

1. Tracking Slow Queries

Within the Queries panel, Telescope highlights the execution time of each database query. Use this to:

  • Identify N+1 problems (repeated similar queries).
  • Track missing indexes or inefficient queries.
  • Optimize query structure.

2. Debugging Failed Jobs

The Jobs panel displays every queued job lifecycle event:

  • See if/when a job fails and the associated exception.
  • Replay failed jobs after addressing their issue.
  • Inspect job payload and parameters.

3. Monitoring Exception Frequency

Under Exceptions, Telescope lists every error as it happens:

  • View full stack traces.
  • Filter by request type, status code, or URL.
  • Quickly reproduce and isolate issues.

4. Analyzing Cache Usage

The Cache panel shows get/set/delete operations, including cache misses and which tags or keys are being read or written.

Performance Monitoring

Telescope acts as a profiler, summarizing request execution times, slow queries, and any long-running synchronous jobs. This is invaluable for zooming in on:

  • Sluggish endpoints or resource-intensive operations.
  • Middleware, service container, or event listener performance.
  • Unoptimized database patterns.

Advanced Configuration

Telescope is designed to be customizable. Among the options:

  • Pruning: Automatically delete old entries from the Telescope tables using scheduled pruning (docs).
  • Storage: Store Telescope data in other database connections.
  • Tagging: Tag entries to logically group related data.

For example, to enable data pruning, schedule the included command in your app/Console/Kernel.php:

protected function schedule(Schedule $schedule)
{
    $schedule->command('telescope:prune')->daily();
}

Best Practices for Telescope in Production

Telescope is intended primarily for local/development use. Be careful exposing sensitive data in production. If you must run it in staging or production, strictly guard access via policies and ensure database pruning is scheduled to manage data size.

Conclusion

Laravel Telescope streamlines debugging, profiling, and monitoring in a highly visual and developer-friendly way. Whether you’re chasing down a hard-to-find bug, optimizing sluggish database queries, or simply exploring your application’s activity, Telescope makes the process seamless and insightful.

Looking to supercharge your Laravel development workflow? Give Telescope a try, and unlock real-time insight into your application like never before.

Further Reading

Back to All Articles