I am always excited when a new Laravel ecosystem product comes out. I am not a fanboy, I have always been skeptic and critic about some parts of the framework when I don’t like them, but there is something (among many others) I love about Laravel: its pragmatism.
So, every single time they release something new I am 100% sure that it’s something that can be useful, no matter if paid or not (the cure the team put in it makes nearly impossible to feel the difference).
Today I want to talk a little bit about Laravel Telescope, a debugging tool for Laravel applications. On the Telescope Github page is defined as an “elegant debugger assistant”.
You can use it to monitor a lot of stuff:
- Requests
- Commands
- Exceptions
- Logs
- Queries
- Events
… and more. In this article, I will show you how to install it and then use it in your workflow.
Installing Telescope is easy. All you have to do is to add it as a dependency of your project with Composer.
|
1 |
$ composer require laravel/telescope --dev |
Once done, you only have to run a couple of commands:
|
1 2 |
$ php artisan telescope:install $ php artisan migrate |
The first one is used to scaffold everything is necessary. Then the migrate command will take care of the database schema Telescope requires.
That’s it!
Configuration
The installation command added a new telescope.php file in your config folder. The documentation suggests spending a little time exploring it.
In the file we can count four items:
- Path: it’s just the path we will use to access Telescope. By default, its value is “telescope”. That means you will be able to access it at /telescope;
- Storage: here we can define everything about where we are going to save Telescope related metrics. By default, Telescope saves data on specific MySQL tables we created during the install procedure;
- Middleware: here you can define a list of middleware to be assigned to every single telescope route. By default, it includes the “web” group and the specific Telescope “Authorize”;
- Watches: every single item Telescope is monitoring has its own “watcher”. Exceptions? ExceptionWatcher. Queries? QueryWatcher. The list goes on following this rule. Here you can customize this list to define what you want to track and what you don’t need;
Usage
Now we know how to install Telescope and how to configure it. Let’s use it! I will assume your Laravel project is accessible at http://myapp.test.
Let’s open it by going to http://myapp.test/telescope. Here’s the main dashboard:
Right now we are in the “Requests” section of Telescope. Try to visit http://mytest.app, then come back here or refresh the page.
Yeah, it’s working! For every request, we can see the HTTP verb, the complete path (in this case we have an empty value because we requested the home page) and when the event happened. We also have an eye icon. It’s a button we can click to access more details about the request.
Let’s click on it!
For every request, we can see everything, from basic details to headers, related session data, and some metadata about the response.
One of the most useful features is also the ability to see “related” Telescope records. Example: in this request, we set a new cache item, the “a66bs…” one. We can look at its details by clicking on the eye icon again.
I like this feature. It is handy to debug in depth what can go wrong and have a better understanding of the app we are building.
Oh, talking about what can go wrong: let’s test one of my favorite ones. Exceptions!
First of all, go to the routes/web.php file and add this code.
|
1 2 3 |
Route::get('error', function() { throw new \Exception('OMG'); }); |
Great. Now go to http://myapp.test/error. You should see the classic exception screen. Let’s go back to Telescope and click on the Exceptions in the menu.
Yeah, we got it! Let’s click on the eye icon to see some details about this exception.
I love this one.
With a little effort (installing and configuring Telescope required nearly no time) we have a lot of data about this exception message, location and stack trace. Also, we can quickly check other occurrences for the same exception or access the related request!
I think this is one of the most amazing features of Telescope. Yeah, I already know that the sea is plenty of advanced software already doing this. I am thinking about Sentry because I use it in my everyday job.
However, what if are you just bootstrapping a product and you want to have an excellent debugging tool with nearly no install effort? Telescope is the perfect fit.
Huh, talking about production…
Should I Use it in Production?
By default, Telescope is visible in the local environment only. However, you can easily modify this behavior by editing the app/Providers/TelescopeServiceProvider.php file.
There is a method called “gate()”. You can edit it with your custom logic to decide if a specific authenticated user can see the Telescope dashboard or not. The documentation suggests a straightforward approach: define an email whitelist. However, you can decide to stick with it or implement your logic.
So… Should you use it in production?
Given my previous experiences, I think I will do it for my next project. Especially in a first bootstrapping phase, it could save me a lot of time.
Have you already tried it? What do you think about it? Let me know in the comments.
