Estamos actualizando el sitio. Durante unos días es posible que veas fallos de diseño o de traducción. La documentación sigue disponible: si una página se ve mal, recárgala más tarde.

Documentación
L Laravel ✓ L intervention/image ✓
10.x ✓
🇷🇺 Русский ✓🇪🇸 Español ✓🇯🇵 日本語 ✓
Iniciar sesión
Inicio Laravel 10.x Laravel Telescope

Laravel Telescope

10.x 7 de mar. de 2026

#Introducción

Laravel Telescope es un excelente complemento para su entorno local de desarrollo Laravel. Telescope proporciona información sobre las solicitudes que llegan a su aplicación, excepciones, entradas de log, consultas a la base de datos, jobs en cola, correos, notificaciones, operaciones de caché, tareas programadas, dumps de variables y más.

#Instalación

Puede usar el gestor de paquetes Composer para instalar Telescope en su proyecto Laravel:

composer require laravel/telescope

Después de instalar Telescope, publique sus assets usando el comando Artisan telescope:install. 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

Finalmente, puede acceder al panel de Telescope a través de la ruta /telescope.

#Personalización de migraciones

Si no va a usar 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 con el siguiente comando: php artisan vendor:publish --tag=telescope-migrations

#Instalación solo 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 del archivo de configuración config/app.php de su aplicación. 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 debe evitar que el paquete Telescope sea auto-descubierto agregando lo siguiente a su archivo composer.json:

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

#Configuración

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

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

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

#Poda 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();

Por defecto, se podarán todas las entradas con más de 24 horas. Puede usar la opción hours al llamar al comando para determinar cuánto tiempo conservar 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 puede accederse a través de la ruta /telescope. Por defecto, solo podrá acceder a este panel en el entorno local. En su archivo app/Providers/TelescopeServiceProvider.php hay una definición de gate de autorización. Este gate controla el acceso a Telescope en entornos no locales. Puede modificar este gate según sea necesario para restringir el acceso a su instalación de Telescope:

use App\Models\User;

/**
 * Registrar el gate de Telescope.
 *
 * Este gate 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, [
            'taylor@laravel.com',
        ]);
    });
}
Внимание

Debe asegurarse de cambiar su 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

Al actualizar a una nueva versión mayor de Telescope, es importante que revise cuidadosamente la guía de actualización.

Además, al actualizar a cualquier nueva versión de Telescope, debe volver a publicar los assets de Telescope:

php artisan telescope:publish

Para mantener los assets 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 mediante la clausura filter que se define en su clase App\Providers\TelescopeServiceProvider. Por defecto, esta clausura registra todos los datos en el entorno local y excepciones, jobs 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 la clausura filter filtra datos para entradas individuales, puede usar el método filterBatch para registrar una clausura que filtre todos los datos para una solicitud o comando de consola dado. Si la clausura devuelve true, todas las entradas serán 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 IDs de usuarios autenticados que Telescope agrega automáticamente a las entradas. Ocasionalmente, puede querer adjuntar sus propias etiquetas personalizadas a las entradas. Para lograr esto, puede usar el método Telescope::tag. El método tag acepta una clausura que debe devolver un arreglo de etiquetas. Las etiquetas devueltas por la clausura se combinarán con cualquier etiqueta que Telescope adjuntaría automáticamente a la entrada. Normalmente, 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']]
                    : [];
    });
 }

#Watchers 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 desea habilitar en el archivo de configuración config/telescope.php:

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

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

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

#Watcher de lotes

El watcher de lotes registra información sobre los batches en cola, incluyendo información del job y la conexión.

#Watcher de caché

El watcher de caché registra datos cuando una clave de caché es accedida, no encontrada, actualizada o eliminada.

#Watcher 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 especificarlos 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'],
    ],
    ...
],

#Watcher de dump

El watcher de dump registra y muestra sus dumps de variables en Telescope. Al usar Laravel, las variables pueden ser dumpadas usando la función global dump. La pestaña del watcher de dump debe estar abierta en el navegador para que el dump sea registrado; de lo contrario, los dumps serán ignorados por el watcher.

#Watcher de eventos

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

#Watcher de excepciones

El watcher de excepciones registra los datos y el stack trace de cualquier excepción reportable que sea lanzada por su aplicación.

#Watcher de gate

El watcher de gate registra los datos y resultados de las comprobaciones de gate y policy realizadas por 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'],
    ],
    ...
],

#Watcher de cliente HTTP

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

#Watcher de jobs

El watcher de jobs registra los datos y el estado de cualquier job despachado por su aplicación.

#Watcher de logs

El watcher de logs registra los datos de log para cualquier log escrito por su aplicación.

Por defecto, Telescope solo registrará logs en 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 cambiar este comportamiento:

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

    // ...
],

#Watcher de mail

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

#Watcher de modelos

El watcher de modelos registra los cambios en modelos cada vez que se despacha un evento de modelo de Eloquent. Puede especificar qué eventos de modelo deben ser registrados 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 dada, active la opción hydrations:

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

#Watcher de notificaciones

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

#Watcher de consultas

El watcher de consultas registra el SQL crudo, los bindings 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 slow. Puede personalizar el umbral de consultas lentas usando la opción slow del watcher:

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

#Watcher de Redis

El watcher de Redis registra todos los comandos Redis ejecutados por su aplicación. Si usa Redis para caché, los comandos de caché también serán registrados por el watcher de Redis.

#Watcher de solicitudes

El watcher de solicitudes registra la solicitud, encabezados, sesión y datos de respuesta asociados con cualquier solicitud manejada 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),
    ],
    ...
],

#Watcher de programación

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

#Watcher de vistas

El observador de vistas registra el nombre de la vista, la ruta, los datos y los "compositores" empleados al renderizar las vistas.

#Mostrar avatares de usuario

El panel de Telescope muestra el avatar del usuario que estaba autenticado cuando se guardó una entrada dada. Por defecto, Telescope obtiene los avatares usando el servicio web Gravatar. Sin embargo, puede personalizar la URL del avatar registrando un callback en su clase App\Providers\TelescopeServiceProvider. El callback recibirá el ID y correo electrónico del usuario y debe 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;
    });
}
← Anterior
Laravel Socialite