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

/**
 * 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.

"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.