Log4Xojo: Una forma más potente de gestionar tus logados

A continuación encontrarás traducido al Castellano el artículo escrito por Gabriel Ludosanu y publicado originalmente en el Blog oficial de Xojo.

El logado es una parte esencial en el desarrollo de software. Tanto si estás depurando algún problema durante el proceso de desarrollo o bien mirando el rendimiento de una aplicación ya en producción, contar con un sistema de logado robusto es crítico. Xojo proporciona dos excelentes métodos para ello: System.DebugLog y System.Log. Estos métodos son fáciles de usar, muy eficaces y convenientes para la mayoría de los proyectos.

Sin embargo, a medida que tus aplicaciones crecen en complejidad puedes encontrarte con escenarios en los que se requieren de las capacidades proporcionadas por un sistema de logado más avanzado. Los desarrolladores que trabajan con otros lenguajes de programación utilizan con frecuencia para ello frameworks como Log4J o Log4Net con el objeto de contar soluciones de logado más potentes y flexibles. Inspirado por estas herramientas, crearemos Log4Xojo, una utilidad de logado potente y flexible diseñada específicamente para el lenguaje Xojo.

Con Log4Xojo podrás:

• Guardar los logs en archivos para su almacenamiento análisis a largo plazo.
• Rotar automáticamente los archivos de logado en el caso de que se tornen demasiado grandes.
• Logar mensajes a múltiples destinos simultáneamente (por ejemplo, el Depurador, logs del sistema y archivos).
• Filtar los mensajes de log por severidad para reducir el ruido en entornos de producción.

Log4Xojo complementa a los métodos de logado incluidos en Xojo y amplía sus capacidades haciendo que resulte más sencillo gestionar los logs de aplicaciones más grandes o complejas. Tanto si eres un desarrollador Xojo experimentado o bien llegas desde otras herramientas como Log4J o Log4Net, Log4Xojo proporciona una solución familiar y robusta para las necesidades de logado avanzadas.

Métodos de logado incluidos de serie

Xojo proporciona dos métodos para el logado: System.DebugLog y System.Log.

• System.DebugLog. Haz clic aquí para acceder a la documentación.
• System.Log. Haz clic aquí para acceder a la documentación.

Estos métodos son muy fáciles de usar y proporcionan una forma eficaz de localizar problemas durante el desarrollo o bien para monitorizar el comportamiento de la aplicación en entornos de producción.

1. System.DebugLog

El método System.DebugLog imprime los mensajes en el panel de Mensajes de Xojo durante el desarrollo de la aplicación. Esto permite a los desarrolladores generar sus propios mensajes de logado para ayudarles durante el proceso de depuración y pruebas. Adicionalmente, System.DebugLog escribe su salida en el log del sistema haciendo que se puedan consultar con herramientas como:

• Consola en macOS
• DebugView en Windows
• StdErr en Linux

Ejemplo:

System.DebugLog("Este es un mensaje de depuración.")

Principales características:

• La salida se produce directamente en el panel Mensajes del IDE de Xojo durante la depuración, proporcionando información en tiempo real sobre tu aplicación.
• También vuelca el logado en el log del sistema, el cual resulta accesible desde fuera del IDE para realizar un análisis futuro.

Limitaciones:

Si bien System.DebugLog es versátil, su salida no puede dirigirse a archivos de logado personalizados desde la aplicación sin realizar programación adicional.

2. System.Log

El método System.Log escribe los mensajes de logado sobre los mecanismos de logado del sistema. Esto resulta particularmente útil para monitorizar el comportamiento de la aplicación en entornos de producción, dado que se integra a la perfección con las herramientas de logado al nivel del sistema.

Cómo funciona:

• En macOS y Linux: los mensajes se escriben en el logado del sistema, generalmente ubicados en /var/log. Se puede acceder a estos logs mediante herramientas como Console (macOS) o Syslog (Linux).
• En Windows: los mensajes se envían al Event Logger, el cual puede inspeccionarse utilizando la utilidad Event Viewer de Windows.

Ejemplo:

System.Log(System.LogLevelNotice, "Este es un mensaje de advertencia.")

Principales características:

• Se integra con la infraestructura de logado del sistema, permitiendo que los mensajes de logado persistan más allá del IDE de Xojo.
• Útil en los entornos de producción, donde los logs se pueden recuperar utilizando las herramientas del sistema como Consola (macOS), Event Viewer (Windows), o bien Syslog (Linux).

Limitaciones:

• Los mensajes no son portables entre plataformas debido a las ubicaciones específicas de logado en cada sistema.
• No está soportado en proyectos móviles.
• En macOS, los mensajes logados con los siguientes niveles no aparecen en el log del sistema debido a limitaciones de macOS:
  • LogLevelDebug
  • LogLevelInformation
  • LogLevelSuccess

¿Por qué utilizar los métodos incorporados?

Los métodos de logado incluidos son excelentes para la mayoría de los proyectos. Son sencillos, eficientes y se integran a la perfección con Xojo. Si tu proyecto no requiere de logado sobre archivos, rotación de logs, o bien soporte para múltiples destinos, entonces estos métodos serán todo lo que necesites.

Presentando nuestra clase personalizada: Log4Xojo

Si bien los métodos incluidos en Xojo son excelentes para la mayoría de los proyectos, algunas aplicaciones precisan de capacidades de logado más avanzadas. Log4Xojo está diseñado para complementar a los métodos incluidos de serie con Xojo, ampliando sus capacidades para manejar requerimientos más avanzados.

¿Qué es Log4Xojo?

Log4Xojo es una clase personalizada de logado que amplía las capacidades de logado de Xojo con características como:

• Logado sobre Archivo: guarda los logs en archivos para su posterior análisis.
• Rotación de logs: gestiona de forma automática el tamaño de los archivos de logado y crea copias de seguridad.
• Logado sobre múltiples destinos: realiza la salida de los mensajes sobre el Depurador, los logs del sistema y archivos de forma simultánea.
• Filtrado por nivel de logado: controla qué mensajes se envían basándose en su severidad (por ejemplo, logar sólo mensajes de advertencia y errores en producción).
• Logs con nombre: asigna a cada instancia de logado un nombre único, haciendo que sea más sencillo organizar y diferenciar los archivos de logado.
• Logado multi-hilo: utiliza un hilo en segundo plano para procesar los logs de forma eficiente sin bloquear tu aplicación.

Estas características hacen que Log4Xojo sea una opción excelente para proyectos más complejos, como por ejemplo aplicaciones con requerimientos de monitorización o informes más estrictos.

¿Cuándo utilizar Log4Xojo?

Considera utilizar Log4Xojo si tu proyecto requiere:

• Logs persistentes sobre archivos para su almacenamiento y análisis a largo plazo.
• Gestión automática de logs para evitar que los archivos sean excesivamente grandes.
• Logar simultáneamente sobre múltiples destinos (por ejemplo el Depurador, logs del sistema y archivos).
• Filtrar los log por severidad para reducir el ruido en los entornos de producción.
• Logado asíncrono y seguro en apps multi-hilo para mejorar el rendimiento en este tipo de soluciones.
• Al procesar los log de forma asíncrona en un hilo en segundo plano, Log4Xojo asegura que el rendimiento de tu app sea excelente, incluso cuando se gestionan grandes volúmenes de mensajes.

Log4Xojo no está pensado para sustituir los métodos incluidos de serie en Xojo, sino que los complementa. Se construye sobre los pilares de System.DebugLog y System.Log, añadiendo capacidades avanzadas para aquellos desarrolladores que precisen una mayor flexibilidad y control.

Cómo utilizar Log4Xojo

¡El uso de Log4Xojo es sencillo! Sigue estos pasos para empezar.

Paso 1: Añade Log4Xojo a tu proyecto

• Descarga el archivo de clase Log4Xojo (haz clic aquí para descargar el proyecto de ejemplo Xojo).
• Arrastra la clase Log4Xojo sobre tu proyecto Xojo.

Paso 2: Crea una instancia de Log

Crea una instancia de la clase Log4Xojo. Cada log requiere de un nombre, el cual se utiliza para identificar y organizar los archivos de log.

Var l4x As New Log4Xojo("AppLog")

Paso 3: Configura el Log

Configura los destinos del log, la ruta de archivo, nivel de log, y otros ajustes. Por ejemplo:

// Set destinations (Debugger and File)
l4x.SetLogDestinations(Log4Xojo.LogDestination.DebugLog, Log4Xojo.LogDestination.FileLog)
 
// Set the base folder for the log file
l4x.SetLogFilePath(SpecialFolder.Desktop)
 
// Set the log level to Warning and above
l4x.SetLogLevel(Log4Xojo.LogLevel.Warning)
 
// Configure log rotation
l4x.SetMaxBackupFiles(5)
l4x.SetMaxLogFileSize(1024)

Paso 4: Mensajes de Log

Imprime mensajes de log con diferentes niveles de severidad:

l4x.Log("Application started.", Log4Xojo.LogLevel.Info, CurrentMethodName)
l4x.Log("This is a debug message.", Log4Xojo.LogLevel.Debug, CurrentMethodName)
l4x.Log("Warning: Low disk space.", Log4Xojo.LogLevel.Warning, CurrentMethodName)
l4x.Log("Error: File not found.", Log4Xojo.LogLevel.Error, CurrentMethodName)

El parámetro de ubicación opcional (CurrentMethodName en el ejemplo anterior) te permite incluir el contexto del mensaje de logado, como por ejemplo el método o bien la clase en la cual se ha originado. Hace que resulte más sencillo dar con la fuente del problema cuando estás revisando los logs.

Paso 5: Detén el logado

Cuando tu aplicación finalice, asegúrate de detener el logado para que se procese el resto de todos los mensajes encolados:

l4x.StopLogging()

Casos de uso para Log4Xojo

Para entender mejor la forma en la que Log4Xojo puede mejorar tus aplicaciones Xojo, estos son algunos casos de uso prácticos:

1. Monitorizar Rendimiento de la Aplicación en Producción

En un entorno de producción es esencial realizar un seguimiento del rendimiento de tu aplicación sin que impacte en su rendimiento, Con Log4Xojo puedes:

• Logar eventos importantes de la aplicación (por ejemplo, actividad del usuario, llamadas a APIs).
• Usar logado sobre archivo para almacenarlos de forma persistente para un posterior análisis.
• Filtrar los log por nivel de severidad para evitar ruido innecesario (por ejemplo, sólo advertencias, errores y problemas críticos).

Ejemplo:

Var l4x As New Log4Xojo("ProductionLog")
l4x.SetLogDestinations(Log4Xojo.LogDestination.FileLog)
l4x.SetLogLevel(Log4Xojo.LogLevel.Warning)
 
// Log application events
l4x.Log("User logged in", Log4Xojo.LogLevel.Info) // Ignored (below warning level)
l4x.Log("Database connection failed", Log4Xojo.LogLevel.Error) // Logged
l4x.Log("Critical: Payment gateway unreachable", Log4Xojo.LogLevel.Critical) // Logged

Resultado: Sólo se logarán sobre un archivo las advertencias, errores y mensajes críticos para su análisis posterior, sin tener que lidiar con los mensajes de log que tengan una prioridad más baja.

2. Crear una herramienta de diagnóstico para tus usuarios

Cuando se trata de analizar los problemas reportados por tus usuarios, el hecho de contar con logs detallados puede resultar tremendamente valioso. Con Log4Xojo puedes:

• Logar mensajes a un archivo sobre el equipo del usuario.
• Incluir etiquetas opcionales de ubicación para resaltar en qué punto de tu código tienen lugar los problemas.
• Usar la rotación de logs para evitar que los archivos de logado consuman una cantidad excesiva de espacio en disco.

Ejemplo:

Var l4x As New Log4Xojo("UserDiagnostics")
l4x.SetLogDestinations(Log4Xojo.LogDestination.FileLog)
l4x.SetLogFilePath(SpecialFolder.Documents)
l4x.SetMaxLogFileSize(1 * 1024 * 1024) // 1 MB
l4x.SetMaxBackupFiles(3)
 
// Log diagnostic information
l4x.Log("Application launched", Log4Xojo.LogLevel.Info, CurrentMethodName)
l4x.Log("Error: File not found", Log4Xojo.LogLevel.Error, "FileManager.LoadFile")
l4x.Log("User clicked 'Submit'", Log4Xojo.LogLevel.Debug, "MainWindow.HandleSubmit")

Resultado: puedes pedir a tus usuarios que te envíen los archivos de log almacenados en su carpeta de documentos para su posterior revisión.

3. Registrar la Actividad del Usuario en Aplicaciones Empresariales

En las aplicaciones empresariales el logado de la actividad del usuario es un requisito habitual a efectos de auditoría. Con Log4Xojo puedes:

• Utilizar logado con múltiples destinos para enviar los log de actividad tanto a los log del sistema como a un archivo de logado central.
• Incluir información relevante de contexto para cada entrada del log (por ejemplo, el ID de usuario, método).

Ejemplo:

Var l4x As New Log4Xojo("AuditLog")
l4x.SetLogDestinations(Log4Xojo.LogDestination.SystemLog, Log4Xojo.LogDestination.FileLog)
l4x.SetLogFilePath(SpecialFolder.Documents)
 
// Log user activity
Var userID As String = "User123"
l4x.Log(userID + " logged in", Log4Xojo.LogLevel.Info, "AuthManager.Login")
l4x.Log(userID + " updated profile", Log4Xojo.LogLevel.Info, "ProfileManager.UpdateProfile")
l4x.Log(userID + " attempted unauthorized access", Log4Xojo.LogLevel.Warning, "SecurityManager.CheckPermissions")

Resultado: Se actualizarán tanto un log del sistema con un archivo de log persistente con las actividades del usuario, garantizando así una trazabilidad sencilla.

4. Gestión de Errores y Cuelgues

Cuando una aplicación se cuelga, los log suponen con frecuencia el único modo de comprender qué ha ocurrido. Log4Xojo puede:

• Capturar logs de error y críticos hasta el cuelgue.
• Rotar los logs para evitar perder logs relevantes que son antiguos.
• Guardar los logs a archivo para su recuperación tras un cuelgue.

Ejemplo:

Var l4x As New Log4Xojo("CrashLogs")
l4x.SetLogDestinations(Log4Xojo.LogDestination.FileLog)
l4x.SetMaxBackupFiles(5)
l4x.SetMaxLogFileSize(1 * 1024 * 1024) // 1 MB
 
Try
  // Simulate application logic
  Raise New RuntimeException("Simulated crash")
Catch e As RuntimeException
  l4x.Log("Critical error: " + e.Message, Log4Xojo.LogLevel.Critical, CurrentMethodName)
End Try

Resultado: Los archivos de log pueden utilizarse para investigar la causa del cuelgue.

Estructura de la Clase Log4Xojo

Log4Xojo incluye varias constantes, enumerandos, propiedades y métodos que pueden proporcionar esta capacidad avanzada. Veámoslos con detalle:

Constantes

MaxQueueSize: Define el número máximo de mensajes de logado que pueden almacenarse en la cola de logado antes de su procesado.
Default: 10,000.

Enumerandos

LogDestination: Especifica dónde deberán de enviarse los mensajes de logado:

• DebugLog: se imprimen el Depurador de Xojo utilizando System.DebugLog.
• SystemLog: utiliza el sistema de logado utilizando System.Log.
• FileLog: imprime a archivo.
• All: imprime sobre todos los destinos.

LogLevel: Define los niveles de severidad para los mensajes de logado:

• Debug: información de depuración detallada.
• Info: mensajes con información general.
• Warning: problemas potenciales que no interrumpen el flujo del programa.
• Error: errores que requieren de atención.
• Critical: problemas críticos que pueden causar el fallo de la aplicación.

Propiedades

mLogName: El nombre del log. Se requiere durante la inicialización y se utiliza para identificar los log y organizar los archivos de log.

mCurrentLogLevel: El nivel mínimo de severidad de los mensajes. Se ignorarán los mensajes con un nivel de logado inferior.

mLogDestinations: Un array de valores LogDestination indicando dónde deberían de enviarse los logs.

mLogFilePath: La ruta de archivo para los log. Este se genera automáticamente basándose en el nombre del log y la fecha actual, pero también puede personalizarse.

mMaxBackupFiles: La cantidad máxima de copias de seguridad de los log que se realizarán. Por omisión: 10.

mMaxLogFileSize: El tamaño máximo del archivo de log en bytes antes de que se produzca su rotación. Por omisión: 1 MB.

mLogQueue: Una cola para el almacenamiento temporal de los mensajes de log antes de que se procesen.

mLogQueueMutex: Un mutex utilizado para garantizar la seguridad del hilo cuando se accede a la cola del log. Consulta la documentación sobre Mutex aquí.

mLogThread: Un thread en segundo plano que procesa los mensajes de log. Consulta la documentación sobre Thread aquí.

mRunning: Una bandera que indica si el thread de logado está en funcionamiento.

Métodos

La clase Log4Xojo proporciona varios métodos para configurar el comportamiento del logado y gestionar los mensajes de log. Estos son algunos de ellos en detalle:

1. Constructor(Name As String)

Propósito: El Constructor inicializa una nueva instancia de la clase Log4Xojo con el nombre de log requerido. Este nombre se puede utilizar para identificar la instancia de log y organizar los archivos de logado.

Uso:

Var l4x As New Log4Xojo("AppLog")

Detalles:

• El parámetro Name es requerido. Si se pasa una cadena vacía, la clase lanzará una excepción del tipo InvalidArgumentException.
• El nombre de log se utiliza para generar los nombres de archivo (por ejemplo, AppLog_2024-11-01.txt).

2. Log(message As String, level As LogLevel, Optional location As String = “”)

Propósito: registra un mensaje con un nivel de logado específico y la ubicación opcional como cadena.

Uso:

l4x.Log("This is an informational message.", Log4Xojo.LogLevel.Info)
l4x.Log("Warning: Low disk space.", Log4Xojo.LogLevel.Warning, CurrentMethodName)

Detalles:

• message: el mensaje de log que quieres registrar.
• level: el nivel de severidad del mensaje. Este determina si el mensaje será logado, basándose para ello en el actual nivel de log (mCurrentLogLevel).
• location (opcional): una cadena que proporciona contexto para el mensaje de logado, como por ejemplo el método o la clase donde se ha originado. Esto resulta especialmente útil para trazar la fuente de los problemas. El uso de CurrentMethodName es más que suficiente, salvo que necesites indicar algo más.
• Si el nivel de logado está por debajo de lo configurado en mCurrentLogLevel, entonces el mensaje se ignorará.

Salida de ejemplo:

[2023-10-01 12:34:56] [INFO] This is an informational message.
[2023-10-01 12:35:00] [WARNING] [Code-Location] Warning: Low disk space.

3. SetLogDestinations(ParamArray destinations As LogDestination)

Propósito: indica donde deberán de enviarse los mensajes de logado (por ejemplo, el depurador, los log del sistema, archivos, o bien todos los destinos).

Uso:

l4x.SetLogDestinations(Log4Xojo.LogDestination.DebugLog, Log4Xojo.LogDestination.FileLog)

Detalles:

• Acepta uno o más valores de LogDestination como parámetros.
• Destinos soportados:
  • LogDestination.DebugLog: realiza la salida sobre el Depurador de Xojo usando System.DebugLog.
  • LogDestination.SystemLog: utiliza el framework de logado del sistema usando System.Log.
  • LogDestination.FileLog: realiza la salida sobre un archivo.
  • LogDestination.All: realiza la salida simultáneamente sobre todos los destinos.
• Puedes combinar los destinos para que se ajusten a tus necesidades.

Ejemplo:

• Para logar mensajes sólo sobre un archivo:
  • l4x.SetLogDestinations(Log4Xojo.LogDestination.FileLog)
• Para logar mensajes tanto al Depurador como sobre el sistema:
  • l4x.SetLogDestinations(Log4Xojo.LogDestination.DebugLog, Log4Xojo.LogDestination.SystemLog)

4. SetLogFilePath(baseLocation As FolderItem)

Propósito: configura la carpeta sobre la cual se almacenarán los archivos de log.

Uso:

Var folder As FolderItem = SpecialFolder.Desktop
l4x.SetLogFilePath(folder)

Detalles:

• baseLocation: un FolderItem que representa la carpeta donde se guardarán los archivos de log.
• La carpeta ha de existir y tener permisos de escritura. Si la carpeta no es válida, el método lanzarán una excepción del tipo InvalidArgumentException.
• El nombre del archivo se generará automáticamente basándose en el nombre del log y la fecha actual (por ejemplo, AppLog_2024-11-01.txt).

Ejemplo:

Para almacenar logs en la carpeta Documents:

l4x.SetLogFilePath(SpecialFolder.Documents)

5. SetLogLevel(level As LogLevel)

Propósito: define el nivel de severidad mínimo para logar los mensajes.

Uso:

l4x.SetLogLevel(Log4Xojo.LogLevel.Warning)

Detalles:

• level: el valor de LogLevel que determina qué mensajes de logado han de registrarse.
• Los mensajes con un nivel inferior se ignorarán.

Niveles de logado soportados:

• Log4Xojo.LogLevel.Debug: información de depuración detallada.
• Log4Xojo.LogLevel.Info: mensajes con información general.
• Log4Xojo.LogLevel.Warning: problemas potenciales que no interrumpen el flujo del programa.
• Log4Xojo.LogLevel.Error: errores que requieren de atención.
• Log4Xojo.LogLevel.Critical: problemas críticos que pueden causar el fallo de la aplicación.

Ejemplo: si configuras el nivel de logado a LogLevel.Warning, entonces sólo se logarán los mensajes con nivel Warning, Error y Critical:

l4x.SetLogLevel(Log4Xojo.LogLevel.Warning)
l4x.Log("This is a debug message.", Log4Xojo.LogLevel.Debug) // Ignored
l4x.Log("This is a warning message.", Log4Xojo.LogLevel.Warning) // Logged

6. SetMaxBackupFiles(max As Integer)

Propósito: configura el número máximo de copias de archivo que se conservarán.

Uso:

l4x.SetMaxBackupFiles(5)

Detalles:

• max: el número máximo de archivos de copia de seguridad a mantener. Las copias más antiguas se borrarán automáticamente cuando se alcance el límite.
• Cuando el archivo de logado actual exceda el tamaño límite (definido mediante SetMaxLogFileSize), se renombrará como copia de seguridad (por ejemplo, AppLog_Date_1.txt), y se creará un nuevo archivo de log.

Ejemplo: Si max = 5, entonces las copias de seguridad tendrán el siguiente aspecto:

AppLog_Date_1.txt
AppLog_Date_2.txt
AppLog_Date_3.txt
AppLog_Date_4.txt
AppLog_Date_5.txt

Una vez se ha creado la sexta copia de seguridad, AppLog_Date_1.txt se borrará.

7. SetMaxLogFileSize(sizeInBytes As Integer)

Propósito: define el tamaño máximo del archivo de logado antes de rotarlo.

Uso:

l4x.SetMaxLogFileSize(1 * 1024 * 1024) // 1 MB

Detalles:

• sizeInBytes: el tamaño máximo del archivo de logado en bytes.
• Cuando el archivo de log supere este tamaño se renombrará como copia de seguridad y se creará un nuevo archivo de log.

8. StopLogging()

Propósito: detiene el hilo de logado y procesa cualquier mensaje restante de la cola.

Uso:

l4x.StopLogging()

Detalles:

• Usa este método cuando tu aplicación esté finalizando para garantizar que todos los mensajes del log se escriban sobre los destinos seleccionados.
• Este método espera durante un breve periodo de tiempo para procesar los mensajes restantes en la cola antes de finalizar el hilo de logado.

Conclusión

Los métodos de logado incluidos en Xojo, System.DebugLog y System.Log, son herramientas excelentes para la depuración y monitorización del comportamiento de la aplicación. Son sencillos, eficaces y suficientes para la mayoría de los proyectos.

Para las aplicaciones con requerimientos más avanzados, la clase Log4Xojo supone un complemento perfecto sobre estos métodos. Con características como el logado, el rotado de logs, el soporte de múltiples destinos, y el filtrado del nivel de log, Log4Xojo es la solución para proyectos más grandes y/o complejos.

Descarga Log4Xojo ahora y empieza a mejorar tu flujo de trabajo con los logs.

¡Estamos deseando conocer el modo en el que utilizas Log4Xojo en tus proyectos!