Sistema de Logging Estructurado

Para qué sirve este sistema

Todo proyecto Unity registra algo, pero la mayoría lo hace de la misma forma: llamadas Debug.Log dispersas, sin categoría, sin filtro de severidad y sin nada escrito en disco cuando algo falla en tiempo de ejecución. Cuando ocurre un crash en una build, la información está ausente o es imposible de analizar.

El Sistema de Logging de Serenity reemplaza eso con un servicio estructurado basado en interfaces de dominio limpias. Los logs llevan categoría, severidad, etiquetas opcionales y una excepción opcional. Cada componente obtiene su propio logger acotado. La verbosidad puede sobreescribirse por categoría en tiempo de ejecución. La salida se enruta a la consola de Unity, a un archivo, o a ambos, configurados de forma independiente.

El problema en Unity

Debug.Log funciona bien en un prototipo pequeño. En un proyecto real no escala. No hay forma de silenciar un subsistema ruidoso sin comentar sus llamadas. No hay registro en archivo para análisis post-mortem de builds. No hay estructura consistente entre los mensajes, por lo que filtrar en la consola se convierte en trabajo a ciegas. Y cuando el proyecto crece y múltiples sistemas loggean al mismo tiempo, la salida es una pared de texto ilegible sin contexto sobre qué sistema escribió qué.

Corregir eso a posteriori implica tocar cada sistema que haya llamado a Debug.Log. Hacerlo por escena o por prefab genera comportamiento inconsistente y regresiones inevitables. El problema necesita una capa de enrutado desde el principio, no un pase de limpieza al final.

Cómo lo aborda Serenity

El Sistema de Logging expone ILogService como servicio central. Escribe entradas a través de WriteLog, WriteVerboseLog, WriteInformationLog, WriteWarningLog, WriteErrorLog y WriteExceptionLog, cada uno aceptando categoría y etiquetas opcionales. La verbosidad se controla globalmente mediante la propiedad Verbosity y por categoría a través de SetCategoryVerbosity y ClearCategoryVerbosity. Llamar a For(category) devuelve un ILoggerComponent acotado a esa categoría, con su propia EffectiveVerbosity y los mismos métodos de escritura sin necesidad de pasar la categoría en cada llamada.

La salida está modelada por ILogProfile, que mapea tipos de instalador a instancias de ILogService mediante entradas ILogRoute y proporciona un logger por defecto a través de GetDefaultLogger. La definición del perfil se declara mediante ILogProfileDefinition. Cada ruta apunta a una implementación concreta de ILogService: UnityConsoleLogService para la consola de Unity y UnityFileLogService para escrituras en disco a través de IFileWriterService. Ambas se registran y conectan mediante sus propios instaladores dentro de la pipeline de inicialización, por lo que la capa de dominio nunca toca APIs de Unity directamente.

Cómo encaja en Serenity

El Logging vive en el namespace Serenity.Logging y sigue la estructura por capas del framework. La capa de Dominio define LogSeverity (Verbose, Info, Warning, Error, Exception), el value object LogEntry y LogCategoryVerbosity. La capa de Aplicación define ILogService, ILoggerComponent, ILogProfile, ILogRoute, ILogProfileDefinition y la interfaz de factoría ILogServiceFactory. La capa de Instalación registra todo mediante LogInstaller. La capa de Negocio no tiene ninguna dependencia de APIs de Unity y puede probarse sin un runtime de Unity.

La capa de Infraestructura proporciona las implementaciones específicas de Unity. ConsoleLogging contiene UnityConsoleLogService y su factoría. FileLogging contiene UnityFileLogService, que escribe a través de IFileWriterService para durabilidad en recuperación de crashes. Ambos se instalan de forma independiente, por lo que un proyecto puede habilitar solo consola, solo archivo, o ambas rutas sin modificar código de dominio o aplicación.

Flujo de trabajo práctico

1. Declara un ILogProfileDefinition que mapee los tipos de instalador a claves de logger y establezca una clave de logger por defecto.
2. Añade UnityConsoleLogInstaller, UnityFileLogInstaller o ambos a la pipeline de inicialización según las rutas de salida que necesites.
3. Deja que LogInstaller conecte ILogProfile e ILogService al localizador de servicios a través de la pipeline de instalación estándar.
4. Inyecta ILogService en cualquier sistema que necesite loggear, o llama a For(category) una vez en la construcción para obtener un ILoggerComponent acotado a ese sistema.
5. Sobreescribe la verbosidad de una categoría ruidosa en tiempo de ejecución con SetCategoryVerbosity sin tocar ninguna otra parte del proyecto.
6. Comprueba IsEnabledFor(category, severity) antes de construir mensajes de log costosos para evitar allocations cuando la entrada sería filtrada de todos modos.

Qué incluye

• Servicio central de logging ILogService con Verbosity global y sobreescrituras por categoría mediante SetCategoryVerbosity y ClearCategoryVerbosity
• Logger acotado a componente ILoggerComponent devuelto por ILogService.For(category), con su propia EffectiveVerbosity
• Value object LogEntry estructurado con timestamp UTC, LogSeverity, categoría, mensaje, etiquetas y Exception opcional
• Enum LogSeverity con cinco niveles: Verbose, Info, Warning, Error y Exception
• Perfil de log ILogProfile y mapa de rutas ILogRoute que dirigen cada tipo de instalador a la instancia correcta de ILogService
• Ruta de salida a consola mediante UnityConsoleLogService, registrada a través de UnityConsoleLogInstaller
• Ruta de salida a archivo mediante UnityFileLogService que escribe a través de IFileWriterService, registrada a través de UnityFileLogInstaller
• Sin dependencia de Unity en la capa de Negocio: el código de dominio y aplicación es completamente testeable sin un runtime de Unity

Cuándo usarlo

• Proyectos que necesitan capturar logs en disco para análisis post-mortem de builds y crashes.
• Bases de código con múltiples subsistemas donde se necesita control de verbosidad por categoría para mantener la consola legible durante el desarrollo.
• Equipos que quieren estructura de log consistente — severidad, categoría, etiquetas — en todos los sistemas desde el primer día.
• Cualquier proyecto que quiera reemplazar llamadas Debug.Log dispersas por una capa de logging enrutable, filtrable y testeable.

Sistemas relacionados

• Event Dispatcher Señales tipadas despachadas a través de un servicio, con soporte para autoregistro y sin singletons estáticos.
• Pipeline de Inicialización Una pipeline asíncrona y ordenada que ejecuta las tareas de arranque de tu proyecto Unity con niveles de criticidad, progreso ponderado y telemetría transmitida a cualquier pantalla de carga.
• Detección de hardware y configuración del sistema Un servicio por capas que captura un snapshot de hardware y SO en el arranque y lo expone a calidad adaptativa, analíticas e informes de errores.
• Capa de Persistencia de Datos Una jerarquía de puertos que desacopla los contratos de guardado de los backends de Unity para que el almacenamiento en ficheros, PlayerPrefs y el cifrado puedan cambiar sin tocar el código del juego.