Sistema de Logging Estructurat

Per a què serveix aquest sistema

Tot projecte Unity registra alguna cosa, però la majoria ho fa de la mateixa manera: crides Debug.Log disperses, sense categoria, sense filtre de severitat i sense res escrit a disc quan alguna cosa falla en temps d'execució. Quan es produeix un crash en una build, la informació és absent o impossible d'analitzar.

El Sistema de Logging de Serenity substitueix això amb un servei estructurat basat en interfícies de domini netes. Els logs porten categoria, severitat, etiquetes opcionals i una excepció opcional. Cada component obté el seu propi logger acotat. La verbositat es pot sobreescriure per categoria en temps d'execució. La sortida s'encamina a la consola de Unity, a un fitxer, o a tots dos, configurats de manera independent.

El problema a Unity

Debug.Log funciona bé en un prototip petit. En un projecte real no escala. No hi ha manera de silenciar un subsistema sorollós sense comentar les seves crides. No hi ha registre en fitxer per a l'anàlisi post-mortem de builds. No hi ha estructura consistent entre els missatges, de manera que filtrar a la consola es converteix en treball a cegues. I quan el projecte creix i múltiples sistemes escriuen logs alhora, la sortida és una paret de text il·legible sense context sobre quin sistema ha escrit què.

Corregir-ho a posteriori implica tocar cada sistema que hagi cridat Debug.Log. Fer-ho per escena o per prefab genera comportament inconsistent i regressions inevitables. El problema necessita una capa d'encaminament des del principi, no una passada de neteja al final.

Com ho aborda Serenity

El Sistema de Logging exposa ILogService com a servei central. Escriu entrades a través de WriteLog, WriteVerboseLog, WriteInformationLog, WriteWarningLog, WriteErrorLog i WriteExceptionLog, cadascun acceptant categoria i etiquetes opcionals. La verbositat es controla globalment mitjançant la propietat Verbosity i per categoria a través de SetCategoryVerbosity i ClearCategoryVerbosity. Cridar For(category) retorna un ILoggerComponent acotat a aquella categoria, amb la seva pròpia EffectiveVerbosity i els mateixos mètodes d'escriptura sense necessitat de passar la categoria a cada crida.

La sortida està modelada per ILogProfile, que mapeja tipus d'instal·lador a instàncies d'ILogService mitjançant entrades ILogRoute i proporciona un logger per defecte a través de GetDefaultLogger. La definició del perfil es declara mitjançant ILogProfileDefinition. Cada ruta apunta a una implementació concreta d'ILogService: UnityConsoleLogService per a la consola de Unity i UnityFileLogService per a escriptures a disc a través d'IFileWriterService. Tots dos es registren i connecten mitjançant els seus propis instal·ladors dins de la pipeline d'inicialització, de manera que la capa de domini mai toca APIs de Unity directament.

Com encaixa a Serenity

El Logging viu al namespace Serenity.Logging i segueix l'estructura per capes del framework. La capa de Domini defineix LogSeverity (Verbose, Info, Warning, Error, Exception), el value object LogEntry i LogCategoryVerbosity. La capa d'Aplicació defineix ILogService, ILoggerComponent, ILogProfile, ILogRoute, ILogProfileDefinition i la interfície de factoria ILogServiceFactory. La capa d'Instal·lació registra tot mitjançant LogInstaller. La capa de Negoci no té cap dependència d'APIs de Unity i es pot provar sense un runtime de Unity.

La capa d'Infraestructura proporciona les implementacions específiques de Unity. ConsoleLogging conté UnityConsoleLogService i la seva factoria. FileLogging conté UnityFileLogService, que escriu a través d'IFileWriterService per a durabilitat en recuperació de crashes. Tots dos s'instal·len de manera independent, de manera que un projecte pot habilitar només consola, només fitxer, o les dues rutes sense modificar codi de domini o aplicació.

Flux de treball pràctic

1. Declara un ILogProfileDefinition que mapegi els tipus d'instal·lador a claus de logger i estableixi una clau de logger per defecte.
2. Afegeix UnityConsoleLogInstaller, UnityFileLogInstaller o tots dos a la pipeline d'inicialització segons les rutes de sortida que necessitis.
3. Deixa que LogInstaller connecti ILogProfile i ILogService al localitzador de serveis a través de la pipeline d'instal·lació estàndard.
4. Injecta ILogService a qualsevol sistema que necessiti escriure logs, o crida For(category) una vegada a la construcció per obtenir un ILoggerComponent acotat a aquell sistema.
5. Sobreescriu la verbositat d'una categoria sorollosa en temps d'execució amb SetCategoryVerbosity sense tocar cap altra part del projecte.
6. Comprova IsEnabledFor(category, severity) abans de construir missatges de log costosos per evitar allocations quan l'entrada seria filtrada de totes maneres.

Què inclou

• Servei central de logging ILogService amb Verbosity global i sobreescriptures per categoria mitjançant SetCategoryVerbosity i ClearCategoryVerbosity
• Logger acotat a component ILoggerComponent retornat per ILogService.For(category), amb la seva pròpia EffectiveVerbosity
• Value object LogEntry estructurat amb timestamp UTC, LogSeverity, categoria, missatge, etiquetes i Exception opcional
• Enum LogSeverity amb cinc nivells: Verbose, Info, Warning, Error i Exception
• Perfil de log ILogProfile i mapa de rutes ILogRoute que dirigeixen cada tipus d'instal·lador a la instància correcta d'ILogService
• Ruta de sortida a consola mitjançant UnityConsoleLogService, registrada a través de UnityConsoleLogInstaller
• Ruta de sortida a fitxer mitjançant UnityFileLogService que escriu a través d'IFileWriterService, registrada a través de UnityFileLogInstaller
• Cap dependència de Unity a la capa de Negoci: el codi de domini i aplicació és completament testejable sense un runtime de Unity

Quan fer-lo servir

• Projectes que necessiten capturar logs a disc per a l'anàlisi post-mortem de builds i crashes.
• Bases de codi amb múltiples subsistemes on cal control de verbositat per categoria per mantenir la consola llegible durant el desenvolupament.
• Equips que volen estructura de log consistent — severitat, categoria, etiquetes — a tots els sistemes des del primer dia.
• Qualsevol projecte que vulgui substituir crides Debug.Log disperses per una capa de logging encaminable, filtrable i testejable.

Sistemes relacionats

• Event Dispatcher Senyals tipades despatxades a través d'un servei, amb suport per a autoregistre i sense singletons estàtics.
• Pipeline d'Inicialització Una pipeline asíncrona i ordenada que executa les tasques d'arrencada del teu projecte Unity amb nivells de criticitat, progrés ponderat i telemetria transmesa a qualsevol pantalla de càrrega.
• Detecció de maquinari i configuració del sistema Un servei per capes que captura un snapshot de maquinari i SO en l'arrencada i l'exposa a qualitat adaptativa, analítiques i informes d'errors.
• Capa de Persistència de Dades Una jerarquia de ports que desacobla els contractes de desat dels backends de Unity perquè l'emmagatzematge en fitxers, PlayerPrefs i el xifratge puguin canviar sense tocar el codi del joc.