Laravel Telescope es una plataforma completa para la depuración de proyectos Laravel. Publicada en el 2018 y creada por Taylor Otwell y Mohamed Said (si, el mismo Mohamed que creo Laravel Wink). Es gratis y su código esta publicado en GitHub para que cualquier pueda colaborar con el paquete.
En esta guía de Laravel Telescope vamos a ver como instalar, configurar y utilizar este paquete de depuración para enterarnos de todo lo que pasa en nuestra aplicación.
¿Para que sirve Laravel Telescope?
Como dijimos anteriormente, Laravel Telescope es una herramienta que «observa» todo lo que ocurre en nuestra aplicación y lo brinda en una interfaz gráfica muy intuitiva e independiente de tu aplicación. Si conoces Laravel Debugbar, entonces piensa a Telescope como lo mismo pero con esteroides. 💪
Telescope detectan y monitorea cada solicitud que llega a tu aplicación, ya sea solicitudes HTTP, excepciones, bases de datos, caché, colas, notificaciones, correos y mucho más, todo en tiempo real. Tener acceso a esta información nos da mucho más control para reducir errores e identificar oportunidades para mejorar nuestra aplicación.
Además, Laravel Telescope muestra cómo diferentes partes de tu aplicación trabajan juntas. Puedes averiguar qué páginas funcionan correctamente y qué consultas se ejecutaron cuando se realizó una solicitud a una determinada página. Realmente genial! 🤩
Cómo Instalar Laravel Telescope
Laravel Telescope se instala como cualquier paquete de Laravel ya sea, en un proyecto nuevo o en uno que tengas en uso.
Prerequisitos para la instalación de Telescope
Antes de instalar Laravel Telescope tenemos que cumplir ciertos requisitos:
- Laravel Telescope debe ser instalado sobre Laravel 5.7 en adelante.
- Debemos tener instalado la extensión bcmath de PHP (más adelante veremos como se instala).
Instalando el paquete de Laravel Telescope
Para instalar Laravel Telescope, ejecutamos el siguiente comando de Composer:
composer require laravel/telescope
Si deseas que Telescope solo este disponible para tu entorno de desarrollo y no para producción, puedes agregar la opción --dev al comando anterior.
Si no da un error relacionado con la extensión bcmath, debemos instalar la extensión de PHP con el siguiente comando.
sudo apt install php7.2-bcmath servicio sudo apache2 restart
NOTA: Si utilizas otra versión de PHP solo modifica php7.2-bcmath por tu versión.
Una vez que finalice la instalación, debes ejecutar los siguientes comando para importar los archivos del paquete:
php artisan telescope:install php artisan migrate
Cuando ejecutes la migración, se crean tres tablas que manejan las operaciones del Telescope: telescope_entries, telescope_entries_tags, y telescope_monitoring.
Y listo, ya puedes entrar a la ruta /telescope de tu aplicación.
Configurando Laravel Telescope
Para configurar los parámetros de Telescope debemos acceder al archivo config/telescope.php donde nos encontraremos con las siguientes configuraciones.
- path: Aquí va la ruta para acceder a Telescope. El valor predeterminado es
telescope. - driver: Aquí va el storage (siguiente parámetro) donde Telescope almacenará los datos.
- storage: Determina que conexión de base de datos utilizará Telescope.
- enabled: Permite habilitar o deshabilitar el paquete.
- middleware: Middlewares que se ejecutaran en las rutas de Telescope. Puedes agregar los que quieras.
- ignore_paths: Puedes agregar las URI que Telescope no tendrá en cuenta para monitorear.
- ignore_commands: Y aquí puedes agregar los comandos de tu aplicación a ser ignorados por Telescope.
- watchers: Y por ultimo tenemos los watchers. Estos son los observadores encargados de monitorear todos los puntos de tu aplicación. Como veras, todos los watchers tienen variables de entorno para habilitar o deshabilitarlos, entre otros parámetros que no entraremos en detalle para no extender el artículo.
Si bien Laravel Telescope observa los puntos mas relevantes de nuestra aplicación, también Telescope nos permite crear nuestros propios watchers y agregarlos a la matriz que describimos anteriormente para extender la funcionalidad de Telescope. En un próximo artículo veremos un ejemplo de como crear un watcher.
¿Qué se puede hacer con Laravel Telescope?
Ahora que ya hemos instalado y configurado Telescope, vamos a ver todas las funcionalidades que tiene y que podemos hacer con cada una de ellas.
Debug de Request HTTP
La primer opción que tenemos en el menú de la izquierda es Request.
Esta pestaña nos permite ver todas las solicitudes HTTP que atiende nuestra aplicación. Haciendo clic en una request HTTP podemos ver los detalles de la misma con muchas información útil. Como el header de la solicitud, los datos de sesión, la respuesta, los correos electrónicos, notificaciones y eventos que fueron disparados en la solicitud.
Estas son las funciones básicas de Laravel Debugbar, pero Telescope va mas alla.
Debug de comandos con Laravel Telescope
La siguiente sección en Telescope nos permite ver los todos los comandos que se han ejecutado y sus resultados. Permite saber si los comandos se han ejecutado correctamente y si no fue así, ver los errores que produjo.
Si ingresamos a uno de ellos haciendo clic en el «ojo» de la izquierda, podemos ver todos sus argumentos, opciones y un log en el caso que haya arrojado errores.
Revisar tareas programadas
Luego tenemos la sección de Schedule. Aquí podemos ver las tareas programadas que se han ejecutado, cada cuanto se ejecutan y cuando fue la ultima vez que se ejecutaron. Podemos ingresar al detalle de cada una para ver mas información.
Verificando los Jobs con Laravel Telescope
La cuarta opción pertenece a los Jobs de nuestra aplicación. Nos permite verificar todos los jobs en ejecución y los que se han ejecutado. Es parecido Horizon, pero con la diferencia de que Horizon es solo para Redis. Telescope funciona para todos los drivers. Brinda información importante en cada una de sus pestañas.
Controlando las Excepciones con Telescope
Cuando nuestra aplicación produzca una excepción, Laravel Telescope la capturara y la presenta en esta sección de una excelente forma. Enumera todas las excepciones y la cantidad de veces que ocurrieron.
Y eso no es todo, si miramos el detalle de una excepción podemos ver el mensaje de error exacto, qué línea del código lo provocó e incluso el seguimiento completo hasta llegar al error. Todo perfectamente formateado y en una linda vista 👏.
Consultar Logs con Laravel Telescope
La pestaña de Logs nos muestra cada mensajes, nivel y hora en que ocurrió. Como las demás secciones, también podemos ver el detalle de cada una de ellas, incluidos los datos de contexto que pueda haber transmitido. Esto es mucho mejor que estar mirando los archivos de texto en storage/logs, no?
Utilizando los dump de una nueva forma
Muchas veces se utiliza la función dump() para ver el contenido de variables por pantalla. Lo «molesto» de esto es que nos modifica la vista de nuestra pagina. Pero si tienes la sección de Dumps de Laravel Telescope en una pestaña y ejecutas el método dump()en tu aplicación, tu página aparecerá normal y la salida de los datos aparecerán automáticamente en la página de Dumps de Telescope, simplemente genial 👏.
Si sales de la pantalla de Dumps y actualizas la pagina de tu aplicación, los resultados se mostrarán nuevamente en tu aplicación web.
Consultas de Base de Datos con Telescope
Como en Laravel Debugbar, en Telescope podemos ver todas las consultas a la base de datos que se ejecutaron.
Lo mejor de todo es que puedes establecer un límite para que Telescope nos informe que una consulta es lenta. Cuando pones un limite, Telescope agrega una etiqueta slow en el listado de consultas y la remarca en color rojo.
Monitorear los Modelos Eloquent con Laravel Telescope
La sección de Models rastrea todas las actividades que se llevan a cabo con los modelos de Eloquent. Por ejemplo, cada acción realizada en el modelo User se mostrará en esta página. Desde que creas un nuevo usuario o incluso actualizas el perfil de usuario, todo aparece aquí.
Debug de Eventos con Laravel Telescope
Telescope registra todos los eventos que produce nuestra aplicación, con información detallada para que podamos hacer debug de eventos que siempre es una tarea difícil para este tipo de operaciones.
Correo, notificaciones, políticas, caché y Redis con Laravel Telescope
Vamos a resumir estas secciones porque me imagino que ya te habrás dado cuenta que hace Telescope en cada una de ellas. Pero básicamente cada una de ellas muestra:
- Mail: muestra una lista de todos los correos electrónicos enviados, a quién se envió, la hora en que se envió, el asunto e incluso la vista previa del correo electrónico.
- Notifications: muestra una lista de notificaciones, los canales en los que se crearon, la hora y quién fue el destinatario de la notificación.
- Gates: muestra una lista de todos los gates y politicas que se ejecutaron en la aplicación.
- Cache: muestra una lista de aciertos, errores, actualizaciones, etc. Puedes ver la solicitud que la activó y mucho más.
- Redis: también es bastante similar a la página de caché. Muestra cuánto tiempo tomó, cuándo sucedió y la solicitud que lo activó.
¿Se puede usar Laravel Telescope en producción?
Claro que puedes usar Telescope en producción. Como vimos anteriormente, puedes cambiar la ruta de acceso a otra que tu quieras. Cuenta con herramientas de autorización integradas para proteger los datos privados. También puedes programar jobs que eliminen entradas antiguas y elegir cuál de las funcionalidades deseas monitorear.
Recomendación para Laravel Telescope en producción
Si vas a utilizar Laravel Telescope en producción te recomiendo que no utilices la misma base de datos de tu aplicación para Telescope. Crea una nueva base de datos (si es posible, en otro servidor) y configura Telescope para que la utilice.
¿Se puede utilizar Telescope para mas de una aplicación?
Por supuesto, debes instalar Telescope en cada uno de tus proyectos y configurar la misma base de datos para cada Telescope. De esta forma, las aplicaciones registraran todo en una única base de datos.
Versión disponible en Laravel
Como dijimos anteriormente, para utilizar Telescope tu proyecto debe disponer de Laravel 5.7, mas precisamente, Laravel 5.7.7 en adelante.
Espero que te haya gustado esta Guía de Laravel Telescope. Cualquier consulta que tengas la puedes dejar en los comentarios de este artículo y con gusto la responderé.
Excelente material
Quisiera agregar una nota y es que acabo de instalar el paquete con –dev y cuando trato de acceder al Panel de Telescope me devuelve error 403.
Hay que configurar el email del usuario autenticado en TelescopeServiceProvider en el metodo gate().
No se si es porque lo instalae como –dev, pero asi me funciona.
Hola.
Gran tutorial.
Hay que hacer alguna configuración adicional para que funcione en producción? al subir el proyecto y poner mi url/telescope, me indica que no existe la ruta. Tampoco me registra nada en las tablas…
Al final he solucionado el tema de las rutas, las ponía mal en el index.php… pero ahora me muestra el siguiente mensaje cuando pongo la ruta /telescope:
The Mix manifest does not exist
Alguna idea?
corre php artisan view:clear y npm run dev
Ya está Matias. Lo que me faltaba era indicar la ruta correcta del root de la aplicación en el método register() del AppSErviceProvider. Yo indicaba la URL y hay que indicar toda la ruta del servidor, por ejemplo en plesk con servidor compartido es algo parecido a /var/www/vhosts/nombre del dominio.
Fallo de principiante… 😉
Gracias !
Barbaro! gracias por comentar la solución porque seguramente les servirá a muchos mas que tengan el mismo problema. Saludos
Que tal, tengo Telescope en produccion, pero quisiera que me registre lo que son los mails y notificaciones, que se envian desde el sistema… quisiera saber que tipo configuracion debería de realizar en el TelescopeServiceProvider, ya que he visto en varios lados que debo de configurar este archivo, pero no sé exactamente que debo agregar, espero me puedas ayudar.
Gracias.
Excelente toda tu documentación gracias por el conocimiento, una consulta laravel telescope puede bajar el redimiendo de un aplicación con muchas peticiones y colas
Excelente gracias por todo el conocimiento impartido, una consulta en una aplicación con muchas peticiones y colas de trabajo laravel telescope puede bajar el rendimiento de dichas de aplicaciones
Como estas Miguel? Si, se le suma un poco de tiempo en la request porque estas agregando una capa de monitoreo. Pero todas las aplicaciones tienen monitoreo para controlar producción. Tampoco es tan significativo el tiempo que se agrega.