Companion for working with Laravel — Telescope

Nowadays, an essential part of the development process is to track the performance of an application. Analyzing the processes in the system allows you to better understand which part of the project is working well, and where urgent fixes are needed. Among the many tools that allow you to monitor and debug, there is one that is very easy to customize in the Laravel framework, because it is made by the creators of the framework themselves. Its name is Telescope. Laravel Telescope is a debugging panel, with a user-friendly and modern design. Inside the panel you can find logs and statuses of all elements of the system.

Features

Laravel Telescope is a customized debugging panel with different aspects of the application, where each aspect is highlighted in a separate menu item. Telescope allows you to see all parts of the system, such as database accesses, cache accesses, how to work with built-in events, how to work with custom events. Also there is realized the display of requests to the system or errors. We will talk more about the features a little later, but for now let's set up the application.

Local and production installation

The main convenience of working with Telescope is that it can be configured literally in a couple of clicks. After installing the package you need to load the assets with the command telescope:install , and then run migrations. When installing only locally we need, after adding the package to dev dependencies and loading the assets, to remove the TelescopeServiceProvider connection from config/app.php, but set the provider connection depending on the environment in AppServiceProvider, for example as follows

if ($this->app->environment('local')) {
   $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
   $this->app->register(TelescopeServiceProvider::class);
}

After that you need to remove the Telescope package from discover in composer.json. As for the production solution, there can't be one opinion. On the one hand - when installing and on production environment there is no need to finalize the connection, because in this case it will be available everywhere. It is also a plus, as it gives you the opportunity to quickly see what is happening with the state of production. However, such a solution has a disadvantage and quite a big one. Due to the fact that the data that is shown in Telescope is extremely sensitive, it is necessary to correctly configure the routing and disable it from being available without access to the corporate network. In my opinion, the ideal connection would be to access a local Laravel Telescope that accesses all data sources within the corporate network. The last step in setting up this tool is to set up the configuration in config/telescope.php

Let's see how it works

By default Telescope runs at /telescope. With a fresh installation, you probably won't see any requests or other data. But what we can say with certainty is that there is a lot of possibilities for this tool, if you look even just at the list of menus.

As for the settings for connecting different services, we will talk about it below. In the meantime, it is still necessary to understand how to set up the panel for yourself.

Prune command

The first problem in our application is the problem with data deletion. Since Telescope collects all the data it sees, the database often quickly reaches its limit without deleting old records. Because of this, we need to update the database by force. Every application has a different frequency of data refresh, but if we're talking about a small project, we can do it on a daily basis. This can be achieved by running the artisan command telescope:prune, or by setting it automatically in Console\Kernel.

Accessing the Telescope panel

By default, working with the panel is only allowed locally. To fix this, you need to add some modified logic to the Gate check in TelescopeServiceProvider and specify there, for example, your email address.

protected function gate(): void
{
   Gate::define('viewTelescope', function ($user) {
       return in_array($user->email, [
           '[email protected]'
       ]);
   });
}

As you can see in the listing - adding a rule for validation is not a difficult task.

Filters

From time to time, when working with Telescope, especially in production, there is a problem with disk space. In order to avoid this and not to disable all logs so often, Laravel Telescope provides filters. They allow us to record only important parts, such as errors or dropped jobs. To change this we need to add or remove necessary/unnecessary parts in TelescopeServiceProvider, for example like this:

Telescope::filter(function (IncomingEntry $entry) {
   if ($this->app->environment('local')) {
       return true;
   }


   return $entry->isReportableException() ||
          $entry->isFailedRequest() ||
          $entry->isFailedJob() ||
          $entry->hasMonitoredTag();
});

So the filters helped to limit the set of logs when working on production.

Tags

If you look at the previous listing, there is a method hasMonitoredTag(). It allows you to show all records that have a tag set, regardless of which watcher it belongs to. In order to set a tag on, for example, a query, you will need to add the following to the TelescopeServiceProvider:

Telescope::tag(function (IncomingEntry $entry) {
   return $entry->type === 'request'
       ? ['status:'.$entry->content['response_status']]
       : [];
});

All tracked tags can be viewed by clicking on the button in the top right corner of the admin panel interface.

Available watchers

Finally, we have observed all the formalities and come to the most interesting part. Laravel Telescope contains a huge number of integrations with different services. Let's take a look at the most popular watchers. Adding a watcher to the system is done in the config/telescope configuration file. If you need to add login data to a new watcher, the new data is written directly to the 'watchers' key. The full list is quite large and while some work with obvious entities like CacheWatcher, CommandWatcher, RequestWatcher, others need a bit more detail. BatchWatcher - this watcher keeps track of sending jobs in batches. Read more about this method here EventWatcher and ModelWatcher - it's worth noting that EventWatcher does not track changes to models that use standard model events, unlike ModelWatcher GateWatcher - records all checks of gates and policies and their results. Below, for information, are examples of how some of the pages work.

CacheWatcher

Tracks cache hits, including unsuccessful ones.

You can also see the passed arguments and options

DumpWatcher

Shows all calls to dump() function

It is worth noting that this watcher does not work when using array as a cache driver.

EventWatcher

Shows all custom events that have occurred recently. You can also track the listener that worked on a particular event.

ExceptionWatcher

One of the most useful watchers, as it allows you to see errors, including the code where the error is thrown, as well as stacktrace

Upgrade Telescope version

It cannot be ignored that upgrading the Telescope version can cause some difficulties. To solve them, you need to follow all the steps of the guide on the official website, and make a couple of points. Due to the fact that the published assets may change during the upgrade, you need to upload them again during the upgrade, either manually or by setting post-update-cmd in composer.json

Conclusion

There are a huge number of all sorts of options on the market right now for debugging and tracking the state of a project. Laravel Telescope may not be very suitable for Production solutions, but for local development the tool is almost indispensable. It is worth noting that Laravel Telescope is updated quite often, which gives hope for long term support.