Habilitación del modo de depuración WP_DEBUG y registro en archivo

WP_DEBUG es la herramienta nativa para identificar errores, avisos y deprecated notices en WordPress. En esta guía técnica y práctica explicaré cómo activar WP_DEBUG, redirigir los registros a un archivo (WP_DEBUG_LOG), configurar permisos seguros, interpretar los logs y aplicar buenas prácticas operativas para entornos de producción y desarrollo.

¿Qué hace WP_DEBUG y por qué es importante?

WP_DEBUG activa el modo de depuración en WordPress, lo que incrementa la visibilidad de errores PHP, avisos y prácticas obsoletas. Por sí solo muestra mensajes; combinado con WP_DEBUG_LOG y WP_DEBUG_DISPLAY permite capturar y controlar dónde van esos mensajes —en pantalla o a un archivo—. La depuración es esencial para:

• Detectar errores de plugins/temas y conflictos.
• Corregir llamadas a funciones obsoletas (deprecated).
• Reproducir y diagnosticar fallos en entornos controlados.

Cómo habilitar WP_DEBUG y registrar en archivo (paso a paso)

Los cambios se realizan en el archivo wp-config.php. Edita siempre con un usuario que pueda restaurar el archivo si algo sale mal (SFTP o SSH). Añade las siguientes líneas justo antes del comentario «/* That’s all, stop editing! Happy publishing. */»:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
@ini_set('display_errors', 0);

Explicación rápida:

• WP_DEBUG: activa el modo debug global.
• WP_DEBUG_LOG: cuando es true crea o añade en wp-content/debug.log.
• WP_DEBUG_DISPLAY: false evita mostrar errores en pantalla (recomendado en producción).
• @ini_set(‘display_errors’, 0): refuerza la directiva PHP para no emitir errores en HTML.

Registrar en una ruta personalizada

Para entornos con separación de logs o cuando no deseas escribir en wp-content:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', '/var/log/wordpress/debug.log');
define('WP_DEBUG_DISPLAY', false);
@ini_set('display_errors', 0);

Si usas una ruta personalizada, asegúrate de que el usuario del proceso web (www-data, nginx, apache) tenga permisos de escritura y que el directorio exista.

Permisos, propiedad y rotación de logs

Un error común es que debug.log no se crea por permisos. Recomendaciones operativas:

• Propietario: chown con el usuario del servidor web. Ejemplo: chown www-data:www-data /var/log/wordpress -R.
• Permisos: 0640 o 0600 sobre el archivo para evitar lectura pública. Ejemplo: chmod 0640 /var/log/wordpress/debug.log.
• Rotación: configura logrotate para evitar crecimiento infinito del archivo; rota diariamente o cuando supere un tamaño razonable.

Ejemplo mínimo de regla logrotate (/etc/logrotate.d/wordpress):

/var/log/wordpress/debug.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    create 0640 www-data www-data
}

Ejemplos reales de uso y comandos útiles

Cómo monitorizar y filtrar el archivo de logs desde SSH:

• Ver en tiempo real: tail -f /var/log/wordpress/debug.log
• Buscar errores de un plugin: grep -i "plugin-folder" /var/log/wordpress/debug.log
• Exportar las últimas 200 líneas: tail -n 200 /var/log/wordpress/debug.log > reporte.txt

Uso de error_log() en código propio para crear entradas explícitas (útil para probar):

error_log('Depuración: función mi_funcion() ejecutada con valores: '. print_r($args, true));

La función error_log (PHP) permite enviar mensajes directamente al sistema de logs o al archivo configurado.

Buenas prácticas de seguridad y operaciones

La depuración expone información sensible si se muestra en pantalla. Sigue estas reglas:

• Nunca dejes WP_DEBUG o WP_DEBUG_DISPLAY activos en producción mostrando errores públicamente.
• Utiliza WP_DEBUG_LOG con un archivo protegido y rotación configurada.
• Registra solo mientras dure la investigación y revierte la configuración tras resolver el problema.
• Revisa logs y sanitiza cualquier dato sensible antes de compartirlos (p. ej. tokens, rutas internas).

Para riesgos de exposición y manejo seguro de información sensible, consulta las guías de seguridad de la comunidad en OWASP.

Depuración avanzada y alternativas

WP_DEBUG es excelente para PHP/WordPress, pero a veces necesitas herramientas adicionales:

• Plugins como Query Monitor para observar consultas SQL, hooks y tiempos en un entorno de desarrollo (no recomendado en producción).
• Uso de Xdebug para depuración paso a paso y perfiles de rendimiento.
• Logs del servidor web (Nginx/Apache) para complementar el analysis: errores 500, timeouts o problemas de proxy. Ver documentación en NGINX para configuración de logs y rendimiento.
• WP-CLI para ejecutar tests y comandos automáticos que generan logs reproducibles.

Ejemplo de flujo de depuración

• Habilitar WP_DEBUG y WP_DEBUG_LOG en un entorno staging.
• Reproducir error o flujo problemático.
• Obtener extracto con tail/grep, filtrar por timestamp/plugin/función.
• Corregir código, reutilizar error_log() para validar entrada/salida de funciones.
• Rotación y respaldo de logs para auditoría si el problema impactó producción.

Errores comunes y soluciones rápidas

• debug.log no se crea: revisar permisos y propietario del directorio, o usar una ruta absoluta y existente.
• Errores no se muestran ni en archivo: comprobar que PHP no tenga display_errors deshabilitado a nivel de php.ini y que las directivas no sean sobreescritas por .htaccess o configuración del servidor.
• Información sensible en logs: limpiar y rotar, revocar tokens o credenciales si fueron expuestos y regenerar claves.

Conclusión

WP_DEBUG y WP_DEBUG_LOG son herramientas fundamentales para cualquier desarrollador o administrador que gestione sitios WordPress. Activarlos correctamente, redirigir los registros a un archivo protegido, configurar permisos y rotación, y adoptar un flujo controlado de depuración minimiza riesgos y acelera la resolución de problemas. Complementa estas prácticas con herramientas de profiling y supervisión del servidor para obtener una visibilidad completa. Para llamadas específicas de logging y funciones de PHP consulta la documentación en PHP.net y para políticas de seguridad de información revisa OWASP. Mantén siempre la depuración desactivada en producción y documenta cambios en tu repositorio o runbook operativo.