Guía Completa de Laravel Telescope

Laravel Telescope es una herramienta gratuita para depurar aplicaciones en Laravel. Ofrece un panel en tiempo real accesible desde /telescope, donde puedes supervisar peticiones HTTP, consultas a bases de datos, excepciones, logs, trabajos en cola, correos, notificaciones y más. Aunque está diseñado para desarrollo local, puede configurarse para producción con medidas de seguridad.

Claves rápidas:

• Instalación sencilla: Usa Composer y ejecuta comandos básicos como php artisan telescope:install.
• Requisitos: Laravel 5.7.7 o superior, extensión PHP ext-bcmath y base de datos compatible.
• Configuración: Personaliza los "watchers" en config/telescope.php según tus necesidades.
• Producción: Protege el acceso con puertas de autorización y limita los datos registrados para optimizar el rendimiento.

Telescope detecta consultas lentas (más de 100ms por defecto), permite depurar variables sin interrumpir el flujo y ayuda a identificar problemas como consultas N+1. Además, puedes programar la limpieza de datos antiguos con php artisan telescope:prune.

Si usas Laravel, Telescope puede ahorrarte tiempo en depuración y mejorar tu flujo de trabajo.

Telescope - Herramienta de depuración para Laravel 🤗 - Curso de Laravel desde Cero

Instalación y configuración

Instalar Laravel Telescope es un proceso bastante directo que utiliza Composer y una base de datos compatible. Este paquete es compatible con Laravel 11.x, 12.x y versiones anteriores desde la 5.7.7. Antes de empezar, asegúrate de que tu servidor tiene activada la extensión PHP ext-bcmath, ya que Telescope la necesita para realizar cálculos precisos con el paquete moontoast/math. Para verificar si está instalada, ejecuta en tu terminal:

php -m | grep bcmath

Si no aparece en la lista, instálala con el siguiente comando (ajustando la versión de PHP según tu sistema operativo):

sudo apt install php8.3-bcmath

A continuación, te mostramos los requisitos esenciales para instalar Laravel Telescope.

Requisitos del sistema

Pasos de instalación

Para instalar Telescope, sigue estos pasos:

1. Instala el paquete con Composer:

   composer require laravel/telescope
   

2. Publica los archivos necesarios ejecutando:

   php artisan telescope:install
   

3. Crea las tablas requeridas:

   php artisan migrate
   

   Asegúrate de que el usuario de la base de datos tiene permisos para crear la tabla telescope_entries. Una vez hecho esto, el panel estará disponible en la ruta /telescope de tu aplicación.
4. Para mantener los recursos actualizados tras actualizaciones del paquete, añade el siguiente comando en la sección post-update-cmd de tu archivo composer.json:

   php artisan vendor:publish --tag=laravel-assets
   

Configuración para desarrollo y producción

Después de instalar Telescope, es importante ajustar su configuración según el entorno en el que se utilice: desarrollo o producción.

Entorno de desarrollo

Telescope está pensado principalmente para usarse en entornos de desarrollo local. Para evitar instalarlo en producción, utiliza el flag --dev al instalarlo:

composer require laravel/telescope --dev

Esto asegura que el paquete solo se instale en entornos de desarrollo. Además, necesitas registrar manualmente el TelescopeServiceProvider en el método register de tu AppServiceProvider, utilizando una comprobación de entorno como esta:

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

También es recomendable añadir laravel/telescope al array dont-discover en el archivo composer.json para evitar el auto-descubrimiento del paquete.

Entorno de producción

Si decides usar Telescope en producción, es fundamental proteger el acceso al panel. Configura la puerta de autorización viewTelescope en app/Providers/TelescopeServiceProvider.php para restringir el acceso a usuarios específicos, ya sea por correo electrónico o ID de usuario.

Además, utiliza el callback Telescope::filter para registrar únicamente eventos importantes, como trabajos fallidos o consultas lentas, en lugar de guardar toda la actividad. Esto optimiza el rendimiento y evita un uso innecesario de recursos.

Por último, programa el siguiente comando para eliminar entradas antiguas diariamente:

php artisan telescope:prune

Por defecto, este comando conserva 24 horas de datos, pero puedes modificarlo según tus necesidades usando la opción --hours:

php artisan telescope:prune --hours=48

Estos pasos te ayudarán a configurar Telescope de manera eficiente, adaptándolo tanto para entornos de desarrollo como para producción.

Características y Watchers

Laravel Telescope opera mediante componentes llamados "watchers", que se encargan de recopilar datos de manera automática cada vez que se ejecuta una petición o un comando de consola. Gracias a estos watchers, no es necesario recurrir al uso manual de dd(), ya que proporcionan una vista centralizada de toda la actividad en la ruta /telescope.

De acuerdo con la documentación oficial, "Laravel Telescope proporciona información sobre las peticiones que llegan a tu aplicación, excepciones, entradas de registro, consultas de base de datos, trabajos en cola, correos, notificaciones, operaciones de caché, tareas programadas, volcados de variables y más". Los watchers pueden activarse o desactivarse desde el archivo config/telescope.php, y muchos de ellos incluyen opciones de configuración específicas. Por ejemplo, el Query Watcher clasifica automáticamente como "lentas" las consultas que tardan más de 100 milisegundos, mientras que el Request Watcher limita el tamaño de las respuestas almacenadas a 64 KB para evitar saturar la base de datos. A continuación, se detallan los principales watchers y sus configuraciones clave.

Peticiones HTTP

Este watcher captura el ciclo completo de cada petición HTTP, incluyendo el método, la ruta, las cabeceras, los datos de sesión y la respuesta completa. Es especialmente útil para el desarrollo de APIs, ya que permite inspeccionar los payloads JSON y las cabeceras sin necesidad de recurrir a herramientas externas. Además, cuenta con una opción configurable llamada size_limit, que determina el tamaño máximo de las respuestas almacenadas.

Consultas de base de datos

Registra cada consulta SQL ejecutada por la aplicación, mostrando el SQL completo, los parámetros vinculados y el tiempo de ejecución. Una de sus funcionalidades más útiles es la detección de consultas N+1, que identifica llamadas redundantes a la base de datos que podrían optimizarse mediante eager loading. También es posible ajustar el umbral para clasificar una consulta como "lenta", lo que ayuda a identificar problemas de rendimiento antes de que afecten al entorno de producción. Este watcher es esencial para depurar consultas y mejorar el rendimiento general de la aplicación.

Trabajos en cola y comandos

Este watcher monitoriza los trabajos en cola, registrando información como los datos del trabajo, su estado (pendiente, completado o fallido), el número de reintentos y la cola o conexión utilizada. También registra la ejecución de comandos Artisan, incluyendo los argumentos, opciones, códigos de salida y el resultado en consola. Además, permite configurar un array ignore para excluir comandos específicos que no se necesiten monitorizar.

Registros y excepciones

Este watcher se encarga de supervisar las entradas de registro de la aplicación. De forma predeterminada, solo registra logs de nivel error o superior, aunque se puede configurar para capturar niveles más bajos como debug o info. También registra cada excepción, incluyendo el mensaje, la línea y el stack trace completo y formateado. Esta información detallada simplifica enormemente la depuración en comparación con la lectura de logs en texto plano.

Tareas programadas

Este watcher está diseñado específicamente para monitorizar las tareas definidas en el programador de Laravel. Registra el comando ejecutado y la salida resultante. A diferencia de otros watchers, se enfoca exclusivamente en las tareas cron programadas, proporcionando visibilidad sobre su ejecución y si se completaron correctamente.

Configuración y personalización

Para sacarle el máximo partido a Telescope, es crucial ajustar cada detalle según las necesidades de tu proyecto y tu entorno de desarrollo. Laravel Telescope permite modificar su funcionamiento desde el archivo config/telescope.php. Aquí puedes activar o desactivar watchers específicos, definir umbrales de rendimiento y decidir qué datos se registran. Por ejemplo, puedes cambiar el límite de tamaño de las respuestas HTTP almacenadas con la opción size_limit del Request Watcher o ajustar el umbral de consultas lentas en el Query Watcher, pasando de los 100 milisegundos predeterminados a un valor que se adapte mejor a tu proyecto.

Configuración de Telescope

El archivo de configuración también te da control sobre aspectos clave como la ruta del dashboard y el middleware aplicado. Si algunos watchers no son necesarios, como el Queue Watcher en proyectos que no utilizan trabajos en cola, puedes desactivarlos para reducir el volumen de datos. Además, algunos watchers ofrecen opciones avanzadas. Por ejemplo, el Log Watcher permite ajustar el nivel mínimo de registro, cambiándolo de error a debug si necesitas más detalles. El Model Watcher, por su parte, puede configurarse para registrar eventos específicos de Eloquent, como created o updated.

Configuración de permisos

El acceso al dashboard de Telescope se controla mediante un gate de Laravel llamado viewTelescope, que se define en el método gate() del archivo app/Providers/TelescopeServiceProvider.php. En entornos locales, el acceso suele ser público, pero en producción es fundamental restringirlo solo a usuarios autorizados. Una práctica común es limitar el acceso verificando el correo electrónico del usuario, como en este ejemplo: return in_array($user->email, ['admin@ejemplo.com']);.

Una vez configurados los permisos, puedes ajustar el comportamiento de cada watcher según las necesidades de tu aplicación.

Configuración personalizada de watchers

Con la configuración básica lista, puedes personalizar aún más cada watcher. Por ejemplo, el Command Watcher permite ignorar comandos específicos mediante la opción ignore, ideal para excluir tareas rutinarias como schedule:run. De manera similar, el Gate Watcher tiene la opción ignore_abilities, que permite excluir comprobaciones de autorización concretas. También puedes aplicar filtros programáticos con los métodos Telescope::filter y Telescope::filterBatch en el TelescopeServiceProvider. Estos filtros te permiten decidir qué entradas se almacenan en función de criterios personalizados, como el entorno o las propiedades de cada entrada.

Modo oscuro y opciones de interfaz

Para hacer más cómodas las sesiones de depuración prolongadas, Telescope incluye un modo oscuro que puedes activar añadiendo Telescope::night() en el método register del TelescopeServiceProvider. Este modo ofrece una interfaz de alto contraste que ayuda a reducir la fatiga visual. Además, puedes personalizar los avatares de usuario con el método Telescope::avatar(), sustituyendo los iconos predeterminados de Gravatar por imágenes personalizadas de perfil. Estas opciones no solo mejoran la experiencia del desarrollador, sino que también permiten adaptar la interfaz a tus preferencias personales.

Usar Laravel Telescope de forma eficaz

Laravel Telescope no solo brilla en el desarrollo, sino que también puede integrarse en entornos de producción de manera eficiente. Su diseño permite recopilar información clave sin comprometer el rendimiento de tu aplicación.

Uso en entorno de producción

Cuando se implementa en producción, Telescope requiere un manejo cuidadoso. Aunque puede ser tentador activar todos los watchers, hacerlo puede impactar negativamente en el rendimiento. Como advierte Célien Boillat, desarrollador web full stack:

"Ejecutar Telescope en producción puede afectar el rendimiento de tu aplicación. Se recomienda desactivar los watchers que no sean absolutamente necesarios".

En producción, enfócate en registrar solo eventos esenciales, como excepciones, trabajos fallidos, tareas programadas y consultas lentas. Usa Telescope::filter y, si necesitas un contexto más amplio, Telescope::filterBatch, para limitar los datos recopilados a lo estrictamente necesario. Además, protege información sensible con el método hideSensitiveRequestDetails, evitando que contraseñas o cabeceras confidenciales se almacenen en la base de datos. Asegúrate también de que el valor de APP_ENV sea production para activar el gate de autorización y evitar que el dashboard quede accesible públicamente.

Con estas configuraciones, Telescope se convierte en una herramienta segura y eficiente, ayudándote a mantener un equilibrio entre monitorización y rendimiento.

Monitorización y depuración

Una vez configurado correctamente, Telescope puede ser una herramienta poderosa para identificar y resolver problemas en tiempo real. Su pestaña "Queries" es especialmente útil para detectar consultas N+1. Si observas que una consulta se ejecuta repetidamente en una sola petición, es un claro indicativo de que necesitas implementar eager loading. Además, el Query Watcher marca automáticamente como "lentas" las consultas que tardan más de 100 milisegundos, aunque puedes modificar este umbral en el archivo config/telescope.php. Para análisis más detallados, considera reducir este límite a 50 milisegundos durante las fases de optimización.

El Dump Watcher también es una herramienta valiosa, permitiéndote usar dump() en producción. Su salida se redirige al dashboard de Telescope, siempre que la pestaña "Dumps" esté habilitada. Para rastrear problemas específicos, aprovecha Telescope::tag, etiquetando entradas con identificadores personalizados como user_id o order_id. Esto facilita el seguimiento de incidencias relacionadas con usuarios o pedidos concretos.

Gestión de datos

La tabla telescope_entries puede crecer rápidamente, por lo que es crucial gestionar su tamaño de manera proactiva. Programa el comando php artisan telescope:prune para ejecutarse diariamente desde el kernel de consola de tu aplicación. Este comando elimina automáticamente las entradas con más de 24 horas de antigüedad. Si necesitas conservar los registros por más tiempo, puedes usar la opción --hours para ajustar el período, por ejemplo: php artisan telescope:prune --hours=48.

En situaciones más extremas, el comando php artisan telescope:clear elimina todas las entradas de inmediato, pero úsalo con precaución. Además, revisa regularmente el tamaño de la tabla telescope_entries y considera desactivar watchers que generen grandes volúmenes de datos, como ModelWatcher o RedisWatcher, si no son esenciales para tus necesidades de depuración actuales.

Conclusión

Laravel Telescope reúne en una sola herramienta la monitorización, depuración y análisis, convirtiéndose en un aliado imprescindible para cualquier desarrollador que trabaje con Laravel. Su capacidad para ofrecer un panorama completo de las peticiones HTTP, consultas a la base de datos, excepciones, trabajos en cola y tareas programadas lo posiciona como un recurso clave para depurar de manera efectiva. Como lo explica Adewale Abati, desarrollador de software:

"Telescope gives us great insight and overview of what goes on in Laravel applications and you should definitely start using it for all of your projects."

Entre sus puntos fuertes destaca su habilidad para detectar consultas ineficientes y señalar aquellas que son más lentas, permitiendo analizar los detalles sin interrumpir el flujo de trabajo. Estas características no solo ahorran tiempo, sino que también mejoran la eficiencia en el desarrollo de aplicaciones.

Aunque Telescope está pensado principalmente para entornos locales, también puede utilizarse en producción si se configura adecuadamente. Al implementar gates de autorización y habilitar la poda automática de datos, es posible monitorizar la salud de la aplicación sin comprometer el rendimiento. Además, programar la tarea telescope:prune diariamente y desactivar los watchers que no sean necesarios ayuda a mantener un equilibrio ideal entre rendimiento y monitorización.

Si aún no has incorporado Telescope en tus proyectos Laravel, ahora es un excelente momento para hacerlo. Esta herramienta gratuita y de código abierto no solo facilita la depuración, sino que también te proporciona la claridad necesaria para construir aplicaciones más sólidas y eficientes.

FAQs

¿Cómo puedo proteger el acceso a Laravel Telescope en un entorno de producción?

Para asegurar el acceso a Laravel Telescope en un entorno de producción, es importante establecer un sistema de autorización para su panel de control. Esto se logra configurando un gate, que limite el acceso exclusivamente a usuarios autenticados, o bien restringiendo su uso a ciertos entornos específicos.

Así, puedes asegurarte de que solo usuarios autorizados tengan acceso a las herramientas de monitoreo y depuración de tu aplicación.

¿Cuáles son los requisitos para instalar Laravel Telescope?

Para instalar Laravel Telescope, necesitas cumplir con algunos requisitos previos. Primero, asegúrate de tener PHP 8.0 o una versión superior con la extensión json habilitada. También necesitas Laravel 8.37 o superior, compatible con las versiones 9 a 12. Además, es imprescindible contar con los paquetes Symfony Console (≥ 5.3) y Symfony Var-Dumper (≥ 5.0).

Si deseas aprovechar funciones adicionales, puedes instalar de manera opcional ext-gd, Guzzle o Octane. Antes de comenzar con la instalación, verifica que tu entorno cumpla con todas estas condiciones.

¿Cómo puedo personalizar los watchers en Laravel Telescope?

Para ajustar los watchers en Laravel Telescope, necesitas modificar el archivo config/telescope.php. Dentro de este archivo, encontrarás un array llamado watchers, que te permite activar o desactivar cada watcher simplemente cambiando su valor entre true y false. Por ejemplo:

'watchers' => [
    \Laravel\Telescope\Watchers\CacheWatcher::class => true,
    \Laravel\Telescope\Watchers\QueryWatcher::class => false,
],

Algunos watchers también ofrecen configuraciones adicionales, como establecer límites de consultas o ajustar parámetros específicos según tus necesidades. Una vez que hayas realizado los cambios, asegúrate de guardar el archivo y ejecutar el comando php artisan config:clear para que los ajustes se apliquen correctamente.

Este proceso te permitirá ajustar Telescope para que se adapte mejor a los requerimientos de tu proyecto.

Publicaciones de blog relacionadas

• Cascading Soft Deletes en Laravel: Ejemplo Práctico
• Cómo Identificar Problemas N+1 en Laravel
• Qué es Laravel Boost
• ¿Qué es Query Caching y Cómo Funciona en Laravel?