Telescope en Laravel 10.x: Guía y Ejemplos

Introducción
Instalación
Actualización de Telescope
Filtrado
- Entradas
- Lotes
Etiquetado
Observadores Disponibles
Mostrar Avatares de Usuario

Introducción

Laravel Telescope es un maravilloso compañero para su entorno de desarrollo Laravel local. Telescope proporciona información sobre las solicitudes que ingresan a su aplicación, excepciones, entradas de registro, consultas de base de datos, trabajos en cola, correos electrónicos, notificaciones, operaciones de caché, tareas programadas, volcados de variables y más.

Instalación

Puede utilizar el administrador de paquetes Composer para instalar Telescope en su proyecto Laravel:

composer require laravel/telescope

Después de instalar Telescope, publique sus activos utilizando el comando Artisan telescope:install. Después de instalar Telescope, también debe ejecutar el comando migrate para crear las tablas necesarias para almacenar los datos de Telescope:

php artisan telescope:install
 
php artisan migrate

Personalización de Migración

Si no va a utilizar las migraciones predeterminadas de Telescope, debe llamar al método Telescope::ignoreMigrations en el método register de la clase App\Providers\AppServiceProvider de su aplicación. Puede exportar las migraciones predeterminadas utilizando el siguiente comando: php artisan vendor:publish --tag=telescope-migrations

Instalación Solo en Local

Si planea usar Telescope solo para ayudar en su desarrollo local, puede instalar Telescope usando la bandera --dev:

composer require laravel/telescope --dev
 
php artisan telescope:install
 
php artisan migrate

Después de ejecutar telescope:install, debe eliminar el registro del proveedor de servicios TelescopeServiceProvider de su archivo de configuración config/app.php. En su lugar, registre manualmente los proveedores de servicios de Telescope en el método register de su clase App\Providers\AppServiceProvider. Nos aseguraremos de que el entorno actual sea local antes de registrar los proveedores:

/**
 * Registrar cualquier servicio de la aplicación.
 */
public function register(): void
{
    if ($this->app->environment('local')) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

Finalmente, también debería evitar que el paquete Telescope sea descubierto automáticamente agregando lo siguiente a su archivo composer.json:

"extra": {
    "laravel": {
        "dont-discover": [
            "laravel/telescope"
        ]
    }
},

Configuración

Después de publicar los activos de Telescope, su archivo de configuración principal estará ubicado en config/telescope.php. Este archivo de configuración le permite configurar sus opciones de watcher. Cada opción de configuración incluye una descripción de su propósito, así que asegúrese de explorar a fondo este archivo.

Si lo desea, puede deshabilitar completamente la recopilación de datos de Telescope utilizando la opción de configuración enabled:

'enabled' => env('TELESCOPE_ENABLED', true),

Eliminación de Datos

Sin poda, la tabla telescope_entries puede acumular registros muy rápidamente. Para mitigar esto, debe programar el comando Artisan telescope:prune para que se ejecute diariamente:

$schedule->command('telescope:prune')->daily();

De forma predeterminada, se podarán todas las entradas con más de 24 horas de antigüedad. Puede utilizar la opción hours al llamar al comando para determinar cuánto tiempo retener los datos de Telescope. Por ejemplo, el siguiente comando eliminará todos los registros creados hace más de 48 horas:

$schedule->command('telescope:prune --hours=48')->daily();

Autorización del Panel

El panel de Telescope se puede acceder en la ruta /telescope. De forma predeterminada, solo podrá acceder a este panel en el entorno local. Dentro de su archivo app/Providers/TelescopeServiceProvider.php, hay una definición de compuerta de autorización. Esta compuerta de autorización controla el acceso a Telescope en entornos no locales. Puede modificar esta compuerta según sea necesario para restringir el acceso a su instalación de Telescope:

use App\Models\User;
 
/**
 * Registrar la compuerta de Telescope.
 *
 * Esta compuerta determina quién puede acceder a Telescope en entornos no locales.
 */
protected function gate(): void
{
    Gate::define('viewTelescope', function (User $user) {
        return in_array($user->email, [
            '[email protected]',
        ]);
    });
}

Advertencia Asegúrese de cambiar la variable de entorno APP_ENV a production en su entorno de producción. De lo contrario, su instalación de Telescope estará disponible públicamente.

Actualización de Telescope

Cuando actualice a una nueva versión principal de Telescope, es importante que revise cuidadosamente la guía de actualización.

Además, al actualizar a cualquier nueva versión de Telescope, debería republicar los activos de Telescope:

php artisan telescope:publish

Para mantener los activos actualizados y evitar problemas en futuras actualizaciones, puede agregar el comando vendor:publish --tag=laravel-assets a los scripts post-update-cmd en el archivo composer.json de su aplicación:

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
        ]
    }
}

Filtrado

Entradas

Puede filtrar los datos que registra Telescope a través del cierre filter que se define en su clase App\Providers\TelescopeServiceProvider. De forma predeterminada, este cierre registra todos los datos en el entorno local y excepciones, trabajos fallidos, tareas programadas y datos con etiquetas monitoreadas en todos los demás entornos:

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
 
/**
 * Registrar cualquier servicio de la aplicación.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();
 
    Telescope::filter(function (IncomingEntry $entry) {
        if ($this->app->environment('local')) {
            return true;
        }
 
        return $entry->isReportableException() ||
            $entry->isFailedJob() ||
            $entry->isScheduledTask() ||
            $entry->isSlowQuery() ||
            $entry->hasMonitoredTag();
    });
}

Lotes

Mientras que el cierre filter filtra datos para entradas individuales, puede utilizar el método filterBatch para registrar un cierre que filtra todos los datos para una solicitud o comando de consola específicos. Si el cierre devuelve true, todas las entradas son registradas por Telescope:

use Illuminate\Support\Collection;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
 
/**
 * Registrar cualquier servicio de la aplicación.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();
 
    Telescope::filterBatch(function (Collection $entries) {
        if ($this->app->environment('local')) {
            return true;
        }
 
        return $entries->contains(function (IncomingEntry $entry) {
            return $entry->isReportableException() ||
                $entry->isFailedJob() ||
                $entry->isScheduledTask() ||
                $entry->isSlowQuery() ||
                $entry->hasMonitoredTag();
            });
    });
}

Etiquetado

Telescope le permite buscar entradas por "etiqueta". A menudo, las etiquetas son nombres de clases de modelos Eloquent o identificaciones de usuario autenticadas que Telescope agrega automáticamente a las entradas. Ocasionalmente, es posible que desee adjuntar sus propias etiquetas personalizadas a las entradas. Para lograr esto, puede utilizar el método Telescope::tag. El método tag acepta un cierre que debería devolver un array de etiquetas. Las etiquetas devueltas por el cierre se fusionarán con cualquier etiqueta que Telescope adjuntaría automáticamente a la entrada. Por lo general, debe llamar al método tag dentro del método register de su clase App\Providers\TelescopeServiceProvider:

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
 
/**
 * Registrar cualquier servicio de la aplicación.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();
 
    Telescope::tag(function (IncomingEntry $entry) {
        return $entry->type === 'request'
                    ? ['status:'.$entry->content['response_status']]
                    : [];
    });
 }

Observadores Disponibles

Los "watchers" de Telescope recopilan datos de la aplicación cuando se ejecuta una solicitud o comando de consola. Puede personalizar la lista de watchers que le gustaría habilitar dentro de su archivo de configuración config/telescope.php:

'watchers' => [
    Watchers\CacheWatcher::class => true,
    Watchers\CommandWatcher::class => true,
    ...
],

Algunos watchers también le permiten proporcionar opciones de personalización adicionales:

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 100,
    ],
    ...
],

Observador de Lotes

El watcher de lotes registra información sobre lotes en cola, incluida la información del trabajo y la conexión.

Observador de Caché

El watcher de caché registra datos cuando se golpea, se pierde, se actualiza y se olvida una clave de caché.

Observador de Comandos

El watcher de comandos registra los argumentos, opciones, código de salida y salida cada vez que se ejecuta un comando Artisan. Si desea excluir ciertos comandos de ser registrados por el watcher, puede especificar el comando en la opción ignore dentro de su archivo config/telescope.php:

'watchers' => [
    Watchers\CommandWatcher::class => [
        'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
        'ignore' => ['key:generate'],
    ],
    ...
],

Observador de Volcado

El watcher de volcado registra y muestra los volcados de variables en Telescope. Al usar Laravel, las variables se pueden volcar con la función global dump. La pestaña del watcher de volcado debe estar abierta en un navegador para que el volcado se registre; de lo contrario, los volcados serán ignorados por el watcher.

Observador de Eventos

El watcher de eventos registra la carga útil, los escuchadores y los datos de difusión para cualquier evento enviado por su aplicación. Los eventos internos del framework Laravel son ignorados por el watcher de eventos.

Observador de Excepciones

El watcher de excepciones registra los datos y la traza de pila para cualquier excepción reportable lanzada por su aplicación.

Observador de Compuertas

El watcher de compuertas registra los datos y el resultado de las verificaciones de compuertas y políticas de su aplicación. Si desea excluir ciertas habilidades de ser registradas por el watcher, puede especificarlas en la opción ignore_abilities en su archivo config/telescope.php:

'watchers' => [
    Watchers\GateWatcher::class => [
        'enabled' => env('TELESCOPE_GATE_WATCHER', true),
        'ignore_abilities' => ['viewNova'],
    ],
    ...
],

Observador de Cliente HTTP

El watcher de clientes HTTP registra las solicitudes de cliente HTTP salientes realizadas por su aplicación.

Observador de Trabajos

El watcher de trabajos registra los datos y el estado de cualquier trabajo enviado por su aplicación.

Observador de Registros

El watcher de registros registra los datos de registro para cualquier registro escrito por su aplicación.

De forma predeterminada, Telescope solo registrará registros en el nivel error y superior. Sin embargo, puede modificar la opción level en el archivo de configuración config/telescope.php de su aplicación para modificar este comportamiento:

'watchers' => [
    Watchers\LogWatcher::class => [
        'enabled' => env('TELESCOPE_LOG_WATCHER', true),
        'level' => 'debug',
    ],
 
    // ...
],

Observador de Correos

El watcher de correos electrónicos le permite ver una vista previa en el navegador de correos electrónicos enviados por su aplicación junto con sus datos asociados. También puede descargar el correo electrónico como un archivo .eml.

Observador de Modelos

El watcher de modelos registra los cambios de modelo cada vez que se envía un evento de modelo Eloquent. Puede especificar qué eventos de modelo deben registrarse mediante la opción events del watcher:

'watchers' => [
    Watchers\ModelWatcher::class => [
        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
        'events' => ['eloquent.created*', 'eloquent.updated*'],
    ],
    ...
],

Si desea registrar la cantidad de modelos hidratados durante una solicitud específica, habilite la opción hydrations:

'watchers' => [
    Watchers\ModelWatcher::class => [
        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
        'events' => ['eloquent.created*', 'eloquent.updated*'],
        'hydrations' => true,
    ],
    ...
],

Observador de Notificaciones

El watcher de notificaciones registra todas las notificaciones enviadas por su aplicación. Si la notificación desencadena un correo electrónico y tiene habilitado el watcher de correo electrónico, el correo electrónico también estará disponible para su vista previa en la pantalla del watcher de correos electrónicos.

Observador de Consultas

El watcher de consultas registra el SQL sin procesar, las vinculaciones y el tiempo de ejecución para todas las consultas ejecutadas por su aplicación. El watcher también etiqueta cualquier consulta más lenta que 100 milisegundos como lenta. Puede personalizar el umbral de consulta lenta utilizando la opción slow del watcher:

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 50,
    ],
    ...
],

Observador de Redis

El watcher de Redis registra todos los comandos de Redis ejecutados por su aplicación. Si está utilizando Redis para el almacenamiento en caché, los comandos de caché también se registrarán mediante el watcher de Redis.

Observador de Solicitudes

El watcher de solicitudes registra la solicitud, las cabeceras, la sesión y los datos de respuesta asociados con cualquier solicitud gestionada por la aplicación. Puede limitar los datos de respuesta registrados mediante la opción size_limit (en kilobytes):

'watchers' => [
    Watchers\RequestWatcher::class => [
        'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
        'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
    ],
    ...
],

Observador de Programaciones

El watcher de programación registra el comando y la salida de cualquier tarea programada ejecutada por su aplicación.

Observador de Vistas

El watcher de vistas registra el nombre, la ruta, los datos y los "compositores" de vistas utilizados al representar vistas.

Mostrar Avatares de Usuario

El panel de Telescope muestra el avatar del usuario que estaba autenticado cuando se guardó una entrada específica. De forma predeterminada, Telescope recuperará avatares utilizando el servicio web Gravatar. Sin embargo, puede personalizar la URL del avatar registrando una devolución de llamada en su clase App\Providers\TelescopeServiceProvider. La devolución de llamada recibirá el ID y la dirección de correo electrónico del usuario y debería devolver la URL de la imagen del avatar del usuario:

use App\Models\User;
use Laravel\Telescope\Telescope;
 
/**
 * Registrar cualquier servicio de la aplicación.
 */
public function register(): void
{
    // ...
 
    Telescope::avatar(function (string $id, string $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}