Laravel Telescope es un asistente de depuración para el framework Laravel creado por Mohamed Said y Taylor Otwell. Es de código abierto y está disponible en GitHub de forma gratuita. En este tutorial te enseñaremos cómo instalar y comenzar a usar esta herramienta.
¿Para qué sirve Telescope?
Piensa en Telescope como un completo entorno de depuración con interfaz de usuario. Telescope está compuesto de una serie de watchers que observan cada solicitud entrante a tu aplicación, ya sean estas solicitudes HTTP, de la terminal etc. Estos watchers capturan toda la información sobre estas solicitudes y sus datos, como por ejemplo: solicitudes a la base de datos, información sobre la cache, eventos ejecutados y correos enviados.
En la interfaz gráfica de Telescope hay pestañas para inspeccionar cada una de las siguientes opciones, en las que cada una representa un watcher u observador: Requests, Commands, Schedule, Jobs, Exceptions, Logs, Dumps, Queries, Models, Events, Mail, Notifications, Cache y Redis.
Instalación de Telescope
Instalar Laravel Telescope en nuestra aplicación es bastante sencillo, como mencionamos anteriormente solo necesitamos usar Composer:
composer require laravel/telescope
Ten en cuenta que Telescope requiere Laravel 5.7.7 o superior y la extensión de PHP bcmath.
Si deseas instalar Telescope solo en el entorno de desarrollo debes usar la opción --dev:
composer require laravel/telescope --dev
Luego de instalar Telescope publica sus assets usando el siguiente comando en la terminal:
php artisan telescope:install
Si has instalado Telescope solo para el entorno de desarrollo, elimina el Service Provider de config/app.php y agrégalo de manera condicional desde app/Providers/AppServiceProvider.php:
<?php
namespace App\Providers;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
// ...
public function register()
{
if ($this->app->environment('local')) {
$this->app->register(TelescopeServiceProvider::class);
}
}
// ...
}
Por último debes ejecutar las migraciones, ya que el paquete requiere algunas tablas para su funcionamiento, para esto ejecuta el comando:
php artisan migrate
Luego de publicar los assets de Telescope su archivo de configuración principal estará ubicado en config/telescope.php.
El archivo de configuración telescope.php te permite cambiar las opciones de tu observador y cada una incluye una descripción de su propósito.
Finalmente podemos hacer algunas peticiones de prueba e ingresar a la dirección /telescope:
Usando Telescope
elescope expone su interfaz gráfica en /telescope, a la que sólo puedes acceder desde el entorno local.
En app/Providers/TelescopeServiceProvider.php hay un método gate. Este gate controla el acceso a Telescope fuera del entorno local. Eres libre de modificar este gate para restringir el acceso a Telescope como lo prefieras:
<?php
namespace App\Providers;
use Illuminate\Support\Facades\Gate;
//...
class TelescopeServiceProvider extends TelescopeApplicationServiceProvider
{
//...
protected function gate()
{
Gate::define('viewTelescope', function ($user) {
return in_array($user->email, [
'[email protected]',
]);
});
}
}
En el ejemplo anterior se otorga acceso solamente al usuario cuyo email sea [email protected].
Explorando las opciones de Telescope
- Requests: La opción Requests del menú de Laravel Telescope te permite ver todas las solicitudes HTTP que ocurren en tu aplicación. Al hacer clic sobre una solicitud puedes ver todos los detalles e información de la misma.
- Commands: muestra todos los comandos que han sido ejecutados en tu aplicación y su valor de salida. Al hacer clic en un comando puedes ver todos los argumentos y opciones del mismo.
- Schedule: Muestra las tareas programadas que han sido ejecutadas.
- Jobs: Muestra todos los jobs que han sido ejecutados o están siendo ejecutados en la aplicación, así como su estado y detalles. Al hacer click sobre el job puedes ver toda la información de éste.
- Exceptions: En Exceptions se registran y muestran todas las excepciones que han ocurrido en tu aplicación.
- Logs: Logs muestra una lista básica de los registros o logs de tu aplicación. Al hacer clic sobre un registro en específico puedes ver toda la información sobre éste.
- Dumps: Permite ver capturas de los valores retornados al ejecutar el comando
dump()en tu aplicación. - Queries: Muestra todas las consultas realizadas a la base de datos así como la duración de las mismas y el momento en que sucedieron.
- Models: Muestra una lista de los modelos de tu aplicación y las acciones realizadas con estos.
- Events: Muestra una lista de eventos así como sus listeners e información adicional.
- Mail: Mail permite ver una lista de todos los correos enviados, a donde fueron enviados y en qué momento, así como información adicional.
- Notifications: En Notifications puedes ver todas las notificaciones que ocurren en tu aplicación.
- Cache: Muestra todos los registros de caché.
- Redis: Muestra información sobre los registros de Redis en tu aplicación.
Reducción de datos
La tabla telescope_entries puede acumular muchos registros rápidamente. Para evitar esto debes configurar el comando telescope:prune para que se ejecute diariamente:
<?php
$schedule->command('telescope:prune')->daily();
Filtrado
Puedes filtrar los datos recolectados por Telescope mediante el callback filter, el cual se encuentra registrado en tu TelescopeServiceProvider:
<?php
namespace App\Providers;
// ...
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
// ...
class TelescopeServiceProvider extends TelescopeApplicationServiceProvider
{
// ...
public function register()
{
// ...
Telescope::filter(function (IncomingEntry $entry) {
if ($this->app->environment('local')) {
return true;
}
return $entry->isReportableException() ||
$entry->isFailedRequest() ||
$entry->isFailedJob() ||
$entry->isScheduledTask() ||
$entry->hasMonitoredTag();
});
}
// ...
}
Watchers disponibles
Los Watchers u «observadores» de Telescope recolectan información de la aplicación cuando ocurre una petición o cuando un comando en la consola es ejecutado. Puedes personalizar la lista de observadores habilitados dentro de tu archivo de configuración config/telescope.php:
<?php
// config/telescope.php
return [
// ...
'watchers' => [
Watchers\CacheWatcher::class => true,
Watchers\CommandWatcher::class => true,
// ...
],
];
Algunos watchers te permiten agregar opciones adicionales de personalización:
<?php
// config/telescope.php
Watchers\QueryWatcher::class => [
'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
'slow' => 100,
],
Laravel Telescope Toolbar
Luego de instalar Telescope, podemos instalar su Toolbar no oficial con el comando:
# composer require fruitcake/laravel-telescope-toolbar --dev
¡Esto es todo! El componente quedará registrado automáticamente gracias a la característica de Package Discovery disponible a partir de Laravel 5.5, por lo tanto al recargar el navegador deberías ver el toolbar en la parte inferior de la página, como el ejemplo a continuación:
Laravel Telescope Toolbar: el puntero del ratón está posicionado sobre el enlace de consultas, el cual se muestra en naranja como advertencia por la gran cantidad de consultas SQL duplicadas.
Material relacionado
- Clockwork, una herramienta para depurar tus aplicaciones de PHP y Laravel
- Integra una barra de depuración a Laravel
- Laravel Telescope en GitHub
No olvides seguirnos en Twitter y suscribirte a nuestro boletín:
Regístrate hoy en Styde y obtén acceso a todo nuestro contenido.
