Como leer los logs de errores de PrestaShop como un desarrollador profesional

Por que importan los logs de errores de PrestaShop

Toda tienda PrestaShop genera errores. Algunos son avisos inofensivos que nunca afectan a tus clientes. Otros son fallos criticos que detienen por completo tu proceso de pago. La diferencia entre un propietario de tienda que pasa dias esperando soporte y uno que resuelve problemas en minutos a menudo se reduce a una sola habilidad: saber leer los logs de errores.

Los logs de errores son la salida diagnostica de tu servidor y de tu aplicacion PrestaShop. Registran cada error PHP, cada consulta de base de datos fallida, cada problema de permisos y cada excepcion no controlada. Cuando algo sale mal, la respuesta casi siempre esta en un archivo de log. El desafio esta en saber donde buscar, que buscar y como interpretar lo que encuentras.

Esta guia cubre el panorama completo del registro de errores en PrestaShop. Aprenderas donde se encuentra cada tipo de log, como habilitar la generacion detallada de informes de errores, como leer los stack traces y como usar herramientas de linea de comandos para encontrar la aguja en el pajar. Ya sea que estes depurando una pantalla blanca de la muerte o rastreando un fallo intermitente en el proceso de pago, este es el conocimiento que necesitas.

Donde se encuentran los logs de PrestaShop

PrestaShop genera logs a multiples niveles, y cada nivel tiene sus propios archivos de log. Entender cual log revisar primero ahorra enormes cantidades de tiempo.

Logs de la aplicacion PrestaShop (var/logs)

A partir de PrestaShop 1.7, la aplicacion utiliza el framework Symfony para su back office y el enrutamiento principal. Symfony escribe sus propios logs en el directorio var/logs/ en la raiz de PrestaShop. Encontraras archivos nombrados segun el entorno actual:

var/logs/dev.log contiene los logs cuando PrestaShop se ejecuta en modo desarrollo. Este archivo es extremadamente detallado y registra todo, desde decisiones de enrutamiento hasta consultas de base de datos. Puede crecer a cientos de megabytes rapidamente.

var/logs/prod.log contiene los logs del modo produccion. Este archivo es mucho menos detallado por defecto, registrando solo advertencias y errores. Este es el archivo que deberias revisar primero cuando algo se rompe en una tienda en produccion.

Estos archivos de log siguen el formato Monolog, que es la libreria de logging estandar en Symfony. Cada linea incluye una marca de tiempo, el canal del log (como request, security o doctrine), el nivel de gravedad y el mensaje. Una entrada tipica se ve asi:

[2024-03-15 14:22:33] request.CRITICAL: Uncaught PHP Exception Symfony\Component\HttpKernel\Exception\NotFoundHttpException: "No route found for GET /admin/nonexistent" at /var/www/html/vendor/symfony/http-kernel/EventListener/RouterListener.php line 136

Los niveles de gravedad, del menos al mas severo, son: DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT y EMERGENCY. Al resolver problemas, filtra primero por ERROR y CRITICAL.

Log de errores PHP

PHP mismo mantiene un log de errores separado de los logs de la aplicacion PrestaShop. Este log captura errores que ocurren antes de que el framework de logging de PrestaShop se inicialice, o errores en codigo que no utiliza el logger de Symfony. La ubicacion de este archivo depende de la configuracion de tu servidor.

En la mayoria de los servidores Linux con Apache, el log de errores PHP se encuentra en /var/log/php_errors.log o /var/log/php/error.log. En hosting compartido con cPanel, a menudo esta en /home/nombreusuario/logs/error.log o en el directorio public_html como error_log.

Puedes encontrar la ubicacion exacta revisando tu configuracion PHP. Crea un archivo PHP temporal con phpinfo(); y busca la directiva error_log. Alternativamente, ejecuta php -i | grep error_log desde la linea de comandos.

Los logs de errores PHP capturan errores fatales, errores de parseo, advertencias y avisos. Una entrada de error fatal tipicamente se ve asi:

[15-Mar-2024 14:22:33 UTC] PHP Fatal error: Uncaught Error: Class 'SomeModule\SomeClass' not found in /var/www/html/modules/somemodule/somemodule.php:45

Logs del servidor web (Apache y Nginx)

Tu servidor web mantiene su propio conjunto de logs independientes de PHP y PrestaShop. Estos logs son esenciales para diagnosticar errores 500, errores 404 y problemas de rendimiento.

Los logs de Apache se encuentran tipicamente en:

/var/log/apache2/error.log para el log de errores en sistemas Debian y Ubuntu.
/var/log/httpd/error_log para el log de errores en sistemas CentOS y RHEL.
/var/log/apache2/access.log para el log de accesos, que registra cada solicitud HTTP.

Los logs de Nginx se encuentran tipicamente en:

/var/log/nginx/error.log para el log de errores.
/var/log/nginx/access.log para el log de accesos.

Si tu sitio utiliza una configuracion de virtual host, los logs podrian estar en una ubicacion especifica del sitio definida por la directiva ErrorLog (Apache) o error_log (Nginx) en tu archivo de virtual host.

Los logs de errores del servidor web capturan problemas como errores de permiso denegado cuando PHP intenta escribir en un directorio, errores de sintaxis en la configuracion despues de un cambio en .htaccess, y errores de timeout del proxy si estas ejecutando PHP-FPM detras de Nginx. Estos son los logs que debes revisar cuando ves un error generico 500 Internal Server Error sin detalles en los logs de PHP o PrestaShop.

Logs legacy de PrestaShop (Back Office)

PrestaShop tambien mantiene un visor de logs dentro del back office en Parametros avanzados > Logs. Esta interfaz muestra las entradas de log almacenadas en la tabla de base de datos ps_log. Estos logs capturan eventos que PrestaShop registra explicitamente, como intentos de inicio de sesion fallidos, errores de instalacion de modulos y fallos en el envio de correos electronicos.

Aunque el visor de logs del back office es conveniente, tiene limitaciones significativas. No captura errores PHP, errores del servidor web, ni la mayoria de los errores fatales que impiden que la pagina se cargue. Consideralo un complemento de los logs basados en archivos, no un reemplazo.

Habilitar el modo debug en PrestaShop

Por defecto, PrestaShop se ejecuta en modo produccion y oculta los mensajes de error detallados a los visitantes. Esto es correcto para una tienda en produccion, pero hace que la depuracion sea casi imposible. Cuando algo se rompe, tu primer paso deberia ser habilitar el modo debug.

Metodo 1: el archivo defines.inc.php

Abre el archivo config/defines.inc.php y busca la linea que establece _PS_MODE_DEV_. Cambiala de false a true:

define('_PS_MODE_DEV_', true);

Este unico cambio tiene varios efectos. El reporte de errores PHP se establece en su nivel maximo, mostrando todos los errores, advertencias y avisos. El almacenamiento en cache de plantillas Smarty se desactiva, por lo que los cambios en las plantillas aparecen inmediatamente. La barra del profiler de Symfony aparece en la parte inferior de las paginas del back office. Y lo mas importante, los detalles de los errores se muestran en pantalla en lugar de mostrar una pagina de error generica.

Metodo 2: el modo Debug Profiling

Para un analisis mas profundo, tambien puedes habilitar el profiling. En el mismo archivo, establece:

define('_PS_DEBUG_PROFILING_', true);

Esto agrega informacion detallada de tiempos y uso de memoria al final de cada pagina, mostrandote que hooks toman mas tiempo, que modulos consumen mas memoria y cuantas consultas de base de datos genera cada pagina. Esto es invaluable para la depuracion de rendimiento pero nunca debe dejarse activado en produccion.

Advertencia de seguridad

El modo debug expone informacion sensible incluyendo rutas de archivos, credenciales de base de datos en los stack traces y la estructura interna de la aplicacion. Nunca dejes el modo debug habilitado en una tienda en produccion accesible al publico. Si necesitas depurar una tienda en produccion, considera restringir el modo debug a tu direccion IP envolviendo el define en una verificacion de IP, o utiliza un entorno de staging.

Leer stack traces

Cuando PrestaShop encuentra un error fatal o una excepcion no controlada en modo debug, muestra un stack trace. Un stack trace es una instantanea de la cadena de llamadas que condujo al error, que se lee desde el punto de fallo hasta el punto de entrada original. Aprender a leer stack traces es la habilidad de depuracion mas valiosa que puedes desarrollar.

Anatomia de un stack trace

Un stack trace tipico de PrestaShop se ve asi:

PHP Fatal error: Uncaught TypeError: Argument 1 passed to Product::getProductProperties() must be of the type int, null given, called in /var/www/html/classes/Product.php on line 4523

Stack trace:
#0 /var/www/html/classes/Product.php(4523): Product::getProductProperties(NULL, Array)
#1 /var/www/html/modules/somemodule/somemodule.php(127): Product::getProductProperties(1, Array)
#2 /var/www/html/classes/Hook.php(523): SomeModule->hookDisplayHome(Array)
#3 /var/www/html/classes/Hook.php(460): Hook::coreCallHook(Object(SomeModule), 'hookDisplayHome', Array)
#4 /var/www/html/classes/Hook.php(408): Hook::exec('displayHome', Array)

Lee el stack trace de arriba hacia abajo. La primera linea te dice que salio mal: una funcion esperaba un entero pero recibio null. La linea #0 te dice donde ocurrio el error. La linea #1 te dice que llamo al codigo en #0. La linea #2 te dice que llamo a #1, y asi sucesivamente.

En este ejemplo, la cadena es clara: PrestaShop ejecuto el hook displayHome, que llamo al metodo hookDisplayHome en SomeModule, que llamo a Product::getProductProperties() con un valor null donde se esperaba un entero. El error esta en el modulo en la linea 127, donde pasa un valor incorrecto.

Encontrar el frame relevante

Los stack traces en PrestaShop pueden ser largos, a veces de 20 o 30 frames de profundidad. La clave es encontrar el frame que contiene tu codigo o el modulo que causa el problema. Busca rutas que contengan /modules/ o /themes/ porque estas son las fuentes mas probables de bugs. Los frames que hacen referencia a /classes/, /src/ o /vendor/ son codigo del nucleo de PrestaShop o librerias de terceros, que tienen menos probabilidad de ser la fuente del problema a menos que hayas modificado archivos del nucleo.

Patrones de error comunes en PrestaShop

Despues de leer miles de logs de errores de PrestaShop, ciertos patrones emergen repetidamente. Reconocer estos patrones te permite diagnosticar problemas en segundos en lugar de horas.

Errores Class Not Found

PHP Fatal error: Uncaught Error: Class 'ModuleName\ClassName' not found

Esto significa que el autoloader no puede encontrar la clase especificada. Las causas comunes incluyen: un archivo vendor/autoload.php faltante (el modulo necesita composer install), una declaracion de namespace que no coincide, un archivo que no fue incluido en el ZIP del modulo durante la instalacion, o un problema de sensibilidad a mayusculas y minusculas en servidores Linux donde ClassName.php y classname.php son archivos diferentes.

Errores Permission Denied

Warning: file_put_contents(/var/www/html/var/cache/prod/some_file): failed to open stream: Permission denied

Estos ocurren cuando el usuario del servidor web (generalmente www-data en Debian/Ubuntu o apache en CentOS) no tiene permisos de escritura sobre un archivo o directorio. Corrigelo ajustando la propiedad: chown -R www-data:www-data var/cache/ y los permisos: chmod -R 775 var/cache/.

Errores de limite de memoria

PHP Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 65536 bytes)

El numero 134217728 bytes equivale a 128MB, que es el limite de memoria PHP predeterminado. PrestaShop recomienda al menos 256MB. Aumentalo en tu archivo php.ini: memory_limit = 512M. Si el error persiste incluso con limites de memoria altos, el codigo probablemente tiene una fuga de memoria, a menudo causada por cargar demasiados productos o categorias en una sola consulta sin paginacion.

Errores de conexion a la base de datos

Link to database cannot be established: SQLSTATE[HY000] [2002] Connection refused

Esto significa que PrestaShop no puede conectarse al servidor MySQL. Verifica que el servidor de base de datos este en ejecucion, que las credenciales en app/config/parameters.php sean correctas y que el host de la base de datos sea accesible desde el servidor web.

Errores de plantillas Smarty

SmartyException: Unable to load template file 'module:somemodule/views/templates/hook/display.tpl'

El archivo de plantilla falta, esta mal escrito o esta en el directorio equivocado. Verifica que el archivo exista en la ruta esperada y que el nombre del archivo coincida exactamente, incluyendo mayusculas y minusculas.

Errores de token CSRF

Invalid token. Please try to log in again.

Esto aparece en el back office cuando el envio de un formulario incluye un token de seguridad caducado o faltante. Tipicamente ocurre cuando una sesion expira durante una larga sesion de edicion, cuando multiples pestanas estan abiertas en la misma pagina de administracion, o cuando un modulo genera sus URLs de formulario incorrectamente.

Usar grep para encontrar errores

Cuando los archivos de log son grandes, desplazarse por ellos manualmente es poco practico. El comando grep es tu mejor aliado para encontrar rapidamente las entradas relevantes.

Busqueda basica de errores

Para encontrar todos los errores fatales en el log de errores PHP:

grep 'Fatal error' /var/log/php_errors.log

Para encontrar errores de un modulo especifico:

grep 'somemodule' /var/www/html/var/logs/prod.log

Para encontrar errores solo de hoy (asumiendo el formato de fecha en el log):

grep '2024-03-15' /var/www/html/var/logs/prod.log | grep 'ERROR\|CRITICAL'

Filtrado avanzado

Para ver errores con contexto circundante (3 lineas antes y despues de cada coincidencia):

grep -C 3 'Fatal error' /var/log/php_errors.log

Para contar cuantas veces ocurre cada error unico:

grep 'Fatal error' /var/log/php_errors.log | sort | uniq -c | sort -rn | head -20

Esta pipeline ordena los errores, cuenta los duplicados, ordena por recuento en orden descendente y muestra los 20 primeros. Esto es increiblemente util para identificar los errores mas frecuentes que necesitan atencion prioritaria.

Para buscar en multiples archivos de log simultaneamente:

grep -r 'Fatal error' /var/log/ --include='*.log'

El flag -r busca recursivamente y --include limita la busqueda a archivos con extension .log.

Monitoreo de logs en tiempo real con tail -f

Cuando estas depurando activamente un problema, necesitas ver los errores en el momento en que ocurren. El comando tail -f sigue un archivo de log en tiempo real, mostrando nuevas entradas a medida que se escriben.

Monitoreo basico en tiempo real

Para monitorear el log de produccion de PrestaShop en tiempo real:

tail -f /var/www/html/var/logs/prod.log

Para monitorear el log de errores PHP:

tail -f /var/log/php_errors.log

Para monitorear multiples archivos de log a la vez:

tail -f /var/www/html/var/logs/prod.log /var/log/php_errors.log /var/log/apache2/error.log

Monitoreo filtrado en tiempo real

Para monitorear solo las entradas de nivel error en tiempo real, combina tail con grep:

tail -f /var/www/html/var/logs/prod.log | grep --line-buffered 'ERROR\|CRITICAL'

El flag --line-buffered es importante aqui. Sin el, grep almacena en buffer su salida y podrias no ver las coincidencias inmediatamente.

Para resaltar palabras clave especificas mientras muestras toda la salida:

tail -f /var/www/html/var/logs/prod.log | grep --color=always -E 'ERROR|CRITICAL|$'

Esto resalta ERROR y CRITICAL en color mientras sigue mostrando todas las lineas.

El flujo de trabajo de depuracion

El flujo de trabajo de depuracion mas efectivo combina el monitoreo en tiempo real con las pruebas activas. Abre una ventana de terminal con tail -f ejecutandose sobre los archivos de log relevantes. En tu navegador, reproduce la accion que causa el error. Observa el terminal para las nuevas entradas de log que aparecen en el momento exacto en que activas el problema. Este enfoque elimina las conjeturas y te muestra precisamente que sucede cuando ocurre el error.

Rotacion y gestion de logs

Los archivos de log crecen continuamente y pueden consumir todo el espacio en disco disponible si se dejan sin gestion. La mayoria de los servidores Linux utilizan logrotate para gestionar esto automaticamente, pero los propios logs de PrestaShop en var/logs/ podrian no estar incluidos en la configuracion predeterminada de logrotate.

Entender Logrotate

La utilidad logrotate se ejecuta diariamente (generalmente via cron) y gestiona la rotacion, compresion y eliminacion de archivos de log. Los archivos de configuracion se encuentran en /etc/logrotate.d/. La rotacion de logs de Apache y Nginx esta tipicamente configurada por defecto.

Para el directorio var/logs de PrestaShop, podrias necesitar crear una configuracion personalizada de logrotate:

/var/www/html/var/logs/*.log {
  daily
  missingok
  rotate 14
  compress
  delaycompress
  notifempty
  create 0640 www-data www-data
}

Esta configuracion rota los logs diariamente, mantiene 14 dias de historial, comprime los logs antiguos y crea nuevos archivos de log con los permisos correctos.

Limpieza manual de logs

Si un archivo de log ha crecido excesivamente y necesitas vaciarlo sin perder el descriptor de archivo (importante si un proceso esta escribiendo activamente en el):

truncate -s 0 /var/www/html/var/logs/prod.log

No elimines el archivo y lo recrees, porque cualquier proceso que tenga el archivo abierto continuara escribiendo en el inodo del archivo eliminado hasta que se reinicie. El enfoque con truncate vacia los contenidos mientras preserva el inodo.

Entender los contextos de error especificos de PrestaShop

Los errores de PrestaShop a menudo vienen con un contexto unico de la plataforma. Entender este contexto te ayuda a localizar y corregir problemas mas rapido.

Errores relacionados con hooks

Cuando un error ocurre dentro de un hook, el stack trace incluira referencias a Hook::exec() y Hook::coreCallHook(). El nombre del hook te dice exactamente en que momento del proceso de renderizado de la pagina ocurre el error. Por ejemplo, los errores de displayHome ocurren en la pagina de inicio, los errores de actionValidateOrder ocurren durante el proceso de pago, y los errores de displayBackOfficeHeader ocurren al cargar cualquier pagina del back office.

Si un error en un hook hace que una pagina falle, puedes desactivar temporalmente el modulo responsable desde la base de datos:

UPDATE ps_module SET active = 0 WHERE name = 'somemodule';

Esto te permite acceder al back office para diagnosticar y corregir el problema adecuadamente.

Conflictos de overrides

El sistema de overrides de PrestaShop permite a los modulos extender las clases del nucleo, pero surgen conflictos cuando dos modulos hacen override de la misma clase. El error tipicamente aparece como un conflicto en la firma del metodo o un cambio de comportamiento inesperado. Revisa el directorio override/ para ver que overrides estan activos, y revisa el archivo cache/class_index.php que mapea las clases a sus archivos de override. Eliminar este archivo de cache obliga a PrestaShop a regenerar el mapa de overrides.

Errores relacionados con la cache

Muchos errores de PrestaShop son causados por archivos de cache obsoletos. Si ves errores que no coinciden con el codigo actual (por ejemplo, un error que hace referencia a un numero de linea que no existe en el archivo), la cache probablemente esta desactualizada. Limpiala eliminando el contenido de var/cache/prod/ y var/cache/dev/. En PrestaShop 1.6, limpia cache/smarty/compile/ y cache/smarty/cache/ en su lugar.

Errores de instalacion y actualizacion de modulos

Las instalaciones de modulos pueden fallar silenciosamente, dejando el modulo en un estado parcialmente instalado. Revisa var/logs/prod.log para las entradas durante la marca de tiempo de la instalacion. Los problemas comunes incluyen tablas de base de datos faltantes (el SQL del metodo install() del modulo fallo), hooks faltantes (la llamada registerHook() fallo) y errores de entrada duplicada en la tabla ps_authorization_role al reinstalar un modulo que no fue completamente desinstalado.

Construir una lista de verificacion de depuracion

Cuando encuentras un error en PrestaShop, sigue esta lista de verificacion sistematica para encontrar la causa eficientemente:

Primero, identifica el tipo de error. Es una pantalla blanca (error 500), un mensaje de error especifico, un diseno roto o un comportamiento inesperado? Cada tipo apunta a archivos de log diferentes.

Segundo, revisa primero el log mas especifico. Para errores PHP, revisa el log de errores PHP. Para errores HTTP, revisa el log de errores del servidor web. Para errores de la aplicacion, revisa var/logs/prod.log.

Tercero, habilita el modo debug si los logs no revelan informacion suficiente. Cambia _PS_MODE_DEV_ a true y reproduce el error.

Cuarto, usa tail -f en los logs relevantes y reproduce el error en tu navegador. Esto te da una vista en tiempo real de exactamente lo que sucede.

Quinto, lee el stack trace de arriba hacia abajo. Encuentra el frame que hace referencia al codigo de tu modulo o tema. Ahi es donde debe aplicarse la correccion.

Sexto, busca el mensaje de error en los issues de GitHub de PrestaShop y en los foros. Es muy probable que alguien haya encontrado y resuelto el mismo problema antes.

Septimo, despues de aplicar una correccion, limpia todas las caches y monitorea los logs para confirmar que el error ha desaparecido. Una correccion que no produce un log limpio no es una correccion completa.

Resumen

Leer los logs de errores de PrestaShop no es un arte misterioso reservado para desarrolladores senior. Es una habilidad practica construida sobre saber donde se encuentran los logs, como filtrarlos y como interpretar lo que contienen. Los logs en var/logs/, el log de errores PHP y el log del servidor web sirven cada uno un proposito diferente y juntos proporcionan una imagen completa de cualquier problema. Habilitar el modo debug te proporciona mensajes de error detallados. Los stack traces te muestran la cadena exacta de llamadas de funcion que condujeron al fallo. Herramientas como grep y tail -f hacen posible encontrar y monitorear errores eficientemente incluso en archivos de log grandes y con mucha actividad. Domina estas tecnicas y resolveras problemas mas rapido, con menos frustracion y con mucha menos dependencia del soporte externo.