Logs y depuración

El kit escribe un log diario, limita los reportes de una excepción repetida para que una página rota no lo llene, y puede publicar cada error nuevo en Slack. En desarrollo suma la debugbar, un detector de consultas N+1 y un seguimiento en vivo del log. Esta guía cubre las variables detrás de cada uno y las dos cosas que hacer antes de desplegar: proteger el visor de logs y poner el token de Slack.

El visor de logs en /logs

routes/web.php registra GET /logs con el LogViewerController del paquete rap2hpoutre/laravel-log-viewer. Lista los archivos de storage/logs/, te deja leerlos, descargarlos y borrarlos, y el kit no le agrega ningún middleware: la ruta es pública. Protégela antes de desplegar, ya sea envolviéndola:

Route::get('logs', LogViewerController::class . '@index')->middleware(['auth', 'role:admin']);

o moviendo la línea a routes/admin.php, donde se convierte en /admin/logs detrás del rol de administrador.

Canales y variables

config/logging.php conserva los canales de Laravel más uno del kit, slack_api.

El canal slack estándar es un canal normal de Laravel: nada en el kit escribe en él salvo que lo agregues a LOG_STACK. Las alertas de error del kit pasan por slack_api.

Alertas de error en Slack

slack_api es un SlackHandler de Monolog que habla con la API de Slack con un token de bot. Publica como Laravel Logs con el icono :boom:, en nivel error y superiores, como un adjunto que incluye el contexto de la excepción salvo el objeto de la excepción, la URL y el id de usuario.

Para activarlo:

1. Crea una app de Slack con un token de bot que tenga chat:write, e invita al bot al canal.
2. Define las variables:

SLACK_BOT_TOKEN=xoxb-tu-token
SLACK_LOG_CHANNEL=#errores

Nada más cambia: el manejador de excepciones en bootstrap/app.php revisa si slack_api tiene token y, cuando lo tiene, publica cada excepción que pasa el límite de abajo. Dos mensajes nunca llegan a Slack ni así, porque son ruido que la siguiente petición arregla: una conexión a la base de datos rechazada, SQLSTATE[HY000] [2002], y el Cannot update locked property de Livewire.

Con qué frecuencia se reporta una excepción

bootstrap/app.php decide, en withExceptions, si una excepción se escribe siquiera. En el entorno local cada excepción se reporta, todas las veces. En los demás:

• El mensaje se normaliza, reemplazando números y fechas por marcadores, y se convierte en un hash junto con el nombre de la clase. El conteo de esa firma se guarda en caché 30 días.
• La excepción se reporta cuando el conteo llega a 1, 10, 25, 50, 100, 300, 500 o 1000, y después cada 1000.
• Incluso en esos conteos, la misma firma se reporta a lo más una vez cada 5 minutos.
• Una excepción lanzada dentro del componente anfitrión de modales, wire-elements-modal, nunca se reporta.
• Los mensajes listados en ignoredExceptionMessages(), hoy sólo el activeComponent must not be accessed before initialization del paquete de modales, no se reportan en ningún entorno.

Cada reporte lleva contexto extra: la última URL no Livewire que la persona abrió, la ruta de la petición, el user agent, el entorno, el componente Livewire que corría y cuántas veces se ha visto esta excepción. Ese es el conteo que el botón Limpiar caché de logs de La devzone reinicia, cuando el almacén de caché es database, para que un error corregido se reporte de nuevo desde 1.

El detector de consultas N+1

beyondcode/laravel-query-detector observa cada petición y reporta una relación cargada dentro de un ciclo. config/querydetector.php:

Su salida es la debugbar: los hallazgos aparecen en una pestaña Messages de la barra. Pon en la lista blanca una relación que se carga a propósito en el arreglo except de la configuración, con la clase del modelo y el nombre de la relación:

'except' => [
    App\Models\Order::class => [
        App\Models\OrderLine::class,
        'lines',
    ],
],

La debugbar

barryvdh/laravel-debugbar es una dependencia de desarrollo; muestra consultas, vistas, la sesión y la línea de tiempo de la petición al pie de cada página. config/debugbar.php:

Nunca la actives en producción: expone consultas y datos de sesión a cualquiera que cargue una página.

Sigue el log mientras desarrollas

composer dev arranca el servidor, el worker de la cola, Vite y php artisan pail, que imprime cada entrada del log en la terminal conforme ocurre. Corre php artisan pail solo para seguir el log de un sitio en marcha, y php artisan pail --filter="QueryException" para ver un solo tipo de entrada. En un servidor, sigue el archivo diario:

tail -f storage/logs/laravel-$(date +%F).log

Las variables que definir en un servidor, estas entre ellas, están listadas en Despliega tu proyecto.