LoggerPro 2.0 - Framework de Logging Asíncrono Moderno para Delphi con Builder Pattern

TL;DR: LoggerPro 2.0 introduce una potente API Builder pattern para logging en Delphi. Usa LoggerProBuilder.WriteToFile.Done.WriteToConsole.Done.Build para configurar appenders de forma fluent. Las nuevas características incluyen logging contextual con WithProperty(), logging de excepciones con stack traces, soporte para Windows Event Log y Shutdown() explícito para cleanup de recursos. ¿Buscas LoggerPro 1.x? Ver la guía legacy.

¿Qué es LoggerPro 2.0?

LoggerPro 2.0 es la última release mayor del framework de logging asíncrono más completo para Delphi. Esta versión introduce una API Builder pattern inspirada en Serilog, haciendo la configuración del logger más intuitiva y mantenible.

¿Buscas la documentación de LoggerPro 1.x? Haz clic aquí para la guía legacy

Características Principales en 2.0

Quick Start con la API Builder

uses
  LoggerPro,
  LoggerPro.Builder;

var
  Log: ILogWriter;
begin
  Log := LoggerProBuilder
    .WriteToFile
      .WithLogsFolder('logs')
      .WithMaxBackupFiles(5)
      .WithMaxFileSizeInKB(10000)
      .Done
    .WriteToConsole
      .Done
    .Build;

  Log.Info('Aplicación iniciada', 'main');
  Log.Debug('Info de debug', 'debug');

  // Logging contextual
  Log.WithProperty('user_id', 42)
     .WithProperty('session', 'abc123')
     .Info('Usuario logueado', 'auth');

  // Logging de excepciones
  try
    // ... código ...
  except
    on E: Exception do
      Log.LogException(E, 'Operación fallida', 'error');
  end;

  // Shutdown explícito (opcional pero recomendado)
  Log.Shutdown;
end;

Builder Pattern: Métodos WriteTo*

LoggerPro 2.0 usa un builder pattern inspirado en Serilog. Cada appender tiene un método WriteTo* dedicado:

Log := LoggerProBuilder
  // Appender de archivo con configuración
  .WriteToFile
    .WithLogsFolder('logs')
    .WithFileBaseName('myapp')
    .WithMaxBackupFiles(10)
    .WithMaxFileSizeInKB(5000)
    .WithEncoding(TEncoding.UTF8)
    .Done

  // Appender de consola
  .WriteToConsole
    .WithRenderer(TLogItemRendererNoTag.Create)
    .Done

  // Appender HTTP
  .WriteToHTTP
    .WithURL('https://logs.example.com/api/logs')
    .WithTimeout(30)
    .WithRetryCount(3)
    .Done

  // Appender genérico
  .WriteToAppender(TMyCustomAppender.Create)

  // Configuraciones globales
  .WithMinimumLevel(TLogType.Warning)  // Solo Warning+ logeados
  .WithDefaultTag('MYAPP')
  .WithStackTraceFormatter(MyStackTraceFunc)

  .Build;

Logging Contextual

LoggerPro 2.0 introduce potentes características de logging contextual:

WithProperty (Contexto Ad-hoc)

// Log individual con contexto
Log.WithProperty('order_id', 12345)
   .WithProperty('amount', 99.99)
   .Info('Pedido procesado', 'orders');

// Output: [INFO] Pedido procesado {order_id=12345, amount=99.99}

WithDefaultTag (Sub-logger)

var
  OrderLog: ILogWriter;
begin
  OrderLog := Log.WithDefaultTag('ORDERS');
  OrderLog.Info('Procesamiento iniciado');   // tag = 'ORDERS'
  OrderLog.Info('Artículo validado');        // tag = 'ORDERS'
  OrderLog.Warn('Stock bajo');               // tag = 'ORDERS'
end;

WithDefaultContext (Contexto Persistente)

var
  RequestLog: ILogWriter;
begin
  RequestLog := Log.WithDefaultContext([
    LogParam.S('request_id', 'req-123'),
    LogParam.S('client_ip', '192.168.1.100')
  ]);

  RequestLog.Info('Petición recibida');    // incluye request_id, client_ip
  RequestLog.Info('Procesando');           // incluye request_id, client_ip
  RequestLog.Info('Respuesta enviada');    // incluye request_id, client_ip
end;

Logging de Excepciones

LoggerPro 2.0 añade logging dedicado de excepciones con soporte opcional para stack traces:

try
  // Código que puede lanzar excepciones
except
  on E: Exception do
  begin
    Log.LogException(E);                           // Básico
    Log.LogException(E, 'Query de base de datos falló'); // Con mensaje
    Log.LogException(E, 'Query falló', 'db');      // Con mensaje y tag
  end;
end;

Formateador de Stack Trace

Integra con JCL, madExcept, EurekaLog o cualquier librería de stack trace:

Log := LoggerProBuilder
  .WithStackTraceFormatter(
    function(E: Exception): string
    begin
      Result := JclLastExceptStackListToString;  // ejemplo JCL
    end)
  .WriteToFile.Done
  .Build;

Filtro de Nivel Mínimo

Filtra mensajes globalmente antes de que se encolen (zero overhead para mensajes filtrados):

Log := LoggerProBuilder
  .WithMinimumLevel(TLogType.Warning)  // Debug e Info filtrados
  .WriteToFile.Done
  .Build;

Log.Debug('No logeado');   // Filtrado - ningún TLogItem creado
Log.Info('No logeado');    // Filtrado - ningún TLogItem creado
Log.Warn('Logeado');       // OK
Log.Error('Logeado');      // OK

Método Shutdown

LoggerPro 2.0 introduce Shutdown() explícito para cleanup determinístico:

procedure TMyApp.Finalize;
begin
  Log.Shutdown;  // Flush de todos los logs pendientes, stop del thread
  Log := nil;    // Libera la referencia
end;

Comportamientos clave:

• Idempotente: Seguro de llamar múltiples veces
• Hace flush de todos los mensajes pendientes
• Termina el thread del logger
• Después del shutdown, las llamadas de log se ignoran silenciosamente (Release) o Assert (Debug)

Retrocompatibilidad

LoggerPro 2.0 es completamente retrocompatible con el código 1.x. El Builder pattern y las nuevas características son adiciones, no reemplazos.

Tu código existente sigue funcionando:

// Este código 1.x funciona perfectamente en 2.0
uses LoggerPro, LoggerPro.FileAppender, LoggerPro.ConsoleAppender;

Log := BuildLogWriter([
  TLoggerProFileAppender.Create(5, 1024, 'logs'),
  TLoggerProConsoleAppender.Create
]);
Log.Info('Mensaje', 'tag');

Nueva alternativa Builder 2.0 (recomendada para nuevos proyectos):

uses LoggerPro, LoggerPro.Builder;

Log := LoggerProBuilder
  .WriteToFile
    .WithLogsFolder('logs')
    .WithMaxBackupFiles(5)
    .WithMaxFileSizeInKB(1024)
    .Done
  .WriteToConsole.Done
  .WithDefaultTag('tag')
  .Build;

Log.Info('Mensaje');  // Usa el tag por defecto

Nota: Mientras que BuildLogWriter() y la creación directa de appenders siguen funcionando, el Builder pattern es el enfoque recomendado para nuevos proyectos. Proporciona mejor descubribilidad, configuración más limpia y acceso a nuevas características como WithMinimumLevel() y WithStackTraceFormatter().

Appenders Disponibles

Todos los appenders están disponibles vía Builder con configuración fluent:

Appenders de Archivo

Appenders de Consola & Debug

Appenders de Red

Appenders VCL (Solo Windows)

Appenders Específicos de Windows

Appenders de Base de Datos & Memoria

Appenders de Callback

Avanzados

Ejemplo: Múltiples Appenders

Log := LoggerProBuilder
  // Archivo con formato JSON Lines
  .WriteToJSONLFile
    .WithLogsFolder('logs')
    .WithMaxBackupFiles(10)
    .Done
  // ElasticSearch
  .WriteToElasticSearch
    .WithHost('localhost')
    .WithPort(9200)
    .WithIndex('myapp-logs')
    .Done
  // Syslog
  .WriteToUDPSyslog
    .WithHost('syslog.example.com')
    .WithApplication('MyApp')
    .Done
  // Consola para desarrollo
  .WriteToConsole.Done
  .Build;

Usar Appenders Sin Soporte Builder

Algunos appenders especializados (Redis, Email, NSQ, etc.) pueden añadirse vía .WriteToAppender():

uses LoggerPro.RedisAppender, LoggerPro.EmailAppender;

Log := LoggerProBuilder
  .WriteToAppender(TLoggerProRedisAppender.Create('localhost', 6379))
  .WriteToAppender(TLoggerProEmailAppender.Create(...))
  .Build;

Integración con Windows Event Log

LoggerPro 2.0 soporta Windows Event Log tanto para aplicaciones normales como para Windows Services:

Aplicaciones Normales

Log := LoggerProBuilder
  .WriteToWindowsEventLog
    .WithSourceName('MyApplication')
    .WithLogLevel(TLogType.Warning)  // Solo warnings y errores
    .Done
  .Build;

Windows Services

Para Windows Services, usa la instancia TService para una integración correcta:

// En tu descendiente de TService
procedure TMyService.ServiceCreate(Sender: TObject);
begin
  FLog := LoggerProBuilder
    .WriteToWindowsEventLogForService(Self)  // Pasa la instancia TService
      .Done
    .WriteToFile
      .WithLogsFolder('C:\ProgramData\MyService\Logs')
      .Done
    .Build;
end;

Esto usa internamente TService.LogMessage, asegurando un logging de eventos correcto para Windows Service.

Niveles de Log

Log.Debug('Información de debug detallada');  // TLogType.Debug
Log.Info('Información general');              // TLogType.Info
Log.Warn('Condiciones de warning');           // TLogType.Warning
Log.Error('Condiciones de error');            // TLogType.Error
Log.Fatal('Fallos críticos');                 // TLogType.Fatal (nuevo en 2.0)

Compatibilidad de Versiones Delphi

Instalación

Opción 1: Descargar Release (Recomendada)

Descarga la última release estable desde GitHub:

Descargar LoggerPro 2.0.0

1. Extrae el ZIP en una carpeta (ej. C:\Libraries\LoggerPro)
2. En el IDE de Delphi, ve a Tools > Options > Language > Delphi > Library
3. Añade esta ruta al Library Path para tu plataforma objetivo:
   • C:\Libraries\LoggerPro (unidades principales)
   • C:\Libraries\LoggerPro\contrib (opcional, solo necesario para appenders Redis y Email)
4. Añade uses LoggerPro, LoggerPro.Builder; a tu código

Todas las releases están disponibles en github.com/danieleteti/loggerpro/releases

Opción 2: Delphinus Package Manager

Busca “LoggerPro” en el package manager Delphinus e instala.

Opción 3: Clonar Repositorio (Solo Contribuidores)

Clona el repositorio solo si quieres probar características no lanzadas o contribuir al proyecto:

git clone https://github.com/danieleteti/loggerpro.git

Luego añade la carpeta raíz y la subcarpeta contrib a tu Library Path como se describe arriba.

Nota: La rama master puede contener código inestable. Para uso en producción, siempre prefiere la Opción 1.

Proyectos Relacionados

Enlaces

• GitHub: github.com/danieleteti/loggerpro
• Guía Legacy 1.x: Documentación LoggerPro 1.x
• Soporte: Grupo de Facebook

FAQ

¿Qué hay de nuevo en LoggerPro 2.0?

LoggerPro 2.0 introduce: API Builder pattern, logging contextual con WithProperty(), logging de excepciones con stack traces, filtro de nivel mínimo, método Shutdown() explícito y thread safety mejorado.

¿Es LoggerPro 2.0 retrocompatible?

Sí, LoggerPro 2.0 es completamente retrocompatible. Tu código 1.x existente usando BuildLogWriter() sigue funcionando sin cambios. La nueva API Builder pattern es una adición, no un reemplazo. Puedes adoptar las nuevas características incrementalmente.

¿Necesito migrar mi código existente?

No se requiere migración. Tu código 1.x funciona tal cual en 2.0. Cuando estés listo, puedes opcionalmente adoptar la nueva API Builder para código nuevo o durante el refactoring.

¿Cómo añado contexto a mis logs?

Usa Log.WithProperty('clave', valor).Info('mensaje') para contexto ad-hoc, o Log.WithDefaultContext([...]) para contexto persistente en múltiples llamadas.

¿Debo llamar a Shutdown()?

Sí, llama a Log.Shutdown en la finalización de tu aplicación para asegurar que todos los logs pendientes se escriban antes de salir. Es seguro llamarlo múltiples veces.

¿Cuál es la diferencia entre WithProperty y WithDefaultContext?

WithProperty() añade contexto a una sola llamada de log (fluent, encadenable). WithDefaultContext() crea un sub-logger que automáticamente incluye el contexto en todas las llamadas de log posteriores.

¿Cómo logeo a múltiples destinos?

Usa el Builder para añadir múltiples appenders:

Log := LoggerProBuilder
  .WriteToFile.Done
  .WriteToConsole.Done
  .WriteToAppender(TLoggerProRedisAppender.Create(...))
  .Build;

¿Soporta LoggerPro logging asíncrono?

Sí, todos los appenders de LoggerPro son asíncronos por defecto. Las llamadas de logging retornan inmediatamente mientras un thread en segundo plano procesa la cola de logs.

¿Es LoggerPro thread-safe?

Sí, LoggerPro es completamente thread-safe. Múltiples threads pueden logear simultáneamente sin sincronización. La cola interna usa algoritmos lock-free para alto rendimiento.

¿Qué versiones de Delphi están soportadas?

LoggerPro 2.0 soporta desde Delphi 10 Seattle hasta Delphi 13 Florence. El soporte de Linux está disponible desde Delphi 10.2 Tokyo.

¿Cómo filtro logs por nivel?

Usa WithMinimumLevel() en el Builder para establecer un filtro global. Los mensajes por debajo del nivel mínimo se descartan antes del encolamiento (zero overhead).

¿Puedo usar LoggerPro en una DLL?

Sí, pero llama a Log.Shutdown antes de descargar la DLL para asegurar que el thread del logger termine correctamente. Esto es especialmente importante para DLLs ISAPI.

¿Cómo logeo a Windows Event Log?

Usa .WriteToWindowsEventLog para aplicaciones normales o .WriteToWindowsEventLogForService(Self) para Windows Services:

// Aplicación normal
Log := LoggerProBuilder
  .WriteToWindowsEventLog
    .WithSourceName('MyApp')
    .Done
  .Build;

// Windows Service
Log := LoggerProBuilder
  .WriteToWindowsEventLogForService(Self)
    .Done
  .Build;

¿Qué appenders tienen soporte Builder nativo?

Todos los appenders principales: File, JSONL File, Time Rotating File, Console, Simple Console, OutputDebugString, HTTP, ElasticSearch, UDP Syslog, FireDAC (base de datos), Memory, Callback, VCL (Memo, ListBox, ListView) y Windows Event Log. Otros appenders (Redis, Email, NSQ) pueden añadirse vía .WriteToAppender().

LoggerPro 2.0 - Logging asíncrono moderno para Delphi con Builder pattern. Logging contextual. Manejo de excepciones. 20+ appenders. Multiplataforma. Open-source.