El registro es una parte esencial y valiosa del desarrollo de software. Se convierte en algo “imprescindible” en cualquier biblioteca o aplicación. El registro puede ayudar a encontrar problemas y cuestiones en cualquier paso del desarrollo de software, pero especialmente en los casos en los que no se puede utilizar la depuración de la forma habitual.
Por ejemplo, cuando despliega su aplicación en producción, y no hay forma de ver cómo va su código, puede simplemente leer la información registrada y averiguar si todo va bien. Por último, el registro puede ayudar en las últimas etapas, después del lanzamiento del producto. Si algo va mal después de un largo tiempo de trabajo estable, puede simplemente comprobar la información de registro, y en la mayoría de los casos, será suficiente para entender lo que salió mal.
Este artículo se ha escrito para los desarrolladores de .NET que quieren implementar el registro en sus proyectos y no están familiarizados con los diferentes marcos de registro de terceros y las características que pueden proporcionar. Describe los principales pasos de la implementación del registro, desde la instalación y configuración del marco hasta la escritura de los primeros registros de la aplicación. En este artículo, aprenderá sobre el registro de datos estructurados en diferentes marcos, las ventajas y desventajas de cada uno de ellos. Los ejemplos de este artículo se han escrito utilizando el framework .NET Core.
¿Qué es el registro estructurado?
Para obtener todas las ventajas del registro, debe implementar una función de registro de la manera correcta. Cuanta más información útil y necesaria pueda proporcionar el registro, más fácil será obtener respuestas a la pregunta “qué ha ido mal”. Esto no significa que deba registrar todo, sólo necesita encontrar los casos en los que el registro debe ser. Pero sólo registrar los mensajes de excepción puede ser inútil. Por ejemplo, si obtiene en los registros algo como ‘Referencia nula del objeto’ sin ningún contexto, nombre del parámetro, o incluso nombre de la función, donde se lanzó la excepción. Debe proporcionar suficiente información para facilitar el proceso de búsqueda de errores. Para conseguir esto de forma sencilla, puede utilizar marcos de registro especiales de .Net que pueden proporcionar muchas características como el registro estructurado.
Un registro simple significa que todos los registros se almacenan como cadenas. Pero muchos problemas no pueden ser transmitidos claramente en unas pocas palabras. En este caso, debemos utilizar el registro estructurado – almacenando objetos enteros en los registros. Por ejemplo, el cuerpo de la solicitud, el modelo de usuario, la consulta de la transacción, etc. Puede ayudar a reproducir un error y averiguar qué ha ido mal.
Además, el registro estructurado puede proporcionar cierta ordenación y capacidad de búsqueda en los archivos de registro. Por ejemplo, puede proporcionar el modelo del usuario en las solicitudes fallidas y luego sólo buscar por ClientId en los registros. Con la ayuda de los marcos de registro, puede pasar cualquier objeto que desee en sus registros de forma sencilla.
Por ejemplo, si utilizamos el registro simple, nuestros registros serán como:
| 1 2 3 | 2019-02-04T12:23:34Z INFO Completado 200 OK en 79ms (Vistas: 78,8ms | ActiveRecord: 0,0ms) |
No será realmente útil si obtenemos un error, por lo que podemos mejorar este registro con la ayuda del registro estructurado. En este caso, podemos obtener algo como
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | { "dt": "2020-04-07T12:23:34Z", "level": "info", "message": "Completed 200 OK in 79ms (Views: 78.8ms | ActiveRecord: 0.0ms)", "context": { "host": "34.225.155.83", "user_id": 5, "path": "/welcome", "method": "GET" }, "http_response_sent": { "status": 200, "duration_ms": 79.0, "view_ms": 78.8, "active_record_ms": 0.0 } } |
Se ve mejor y tenemos algunos beneficios:
- Datos bien estructurados en formato de codificación oficial (JSON).
- Sin reglas especiales de análisis sintáctico.
- Trabajo con los datos de forma sencilla (búsqueda, filtro, ordenación, vista legible para el ser humano, etc.).
Pero antes de empezar con los registros estructurados, necesitamos implementar el registro de forma general.
API de registro incorporada
Para empezar a trabajar con la API de registro, necesita un proveedor que muestre o almacene los registros. Puede elegir el proveedor Console para ver los registros en la consola de su aplicación, o el proveedor Azure Application Insights para almacenarlos en Azure. Por cierto, puede utilizar varios proveedores para almacenar los registros en diferentes lugares. Si utiliza una aplicación con Generic Host, sólo debe llamar al método AddConsole (o cualquier otro nombre de proveedor). Vamos a probar en la plantilla de proyecto de la API Web por defecto.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 | public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .ConfigureLogging(configureLogging => { configureLogging.ClearProviders(); configureLogging.AddConsole(); }) .ConfigureWebHostDefaults(webBuilder => { webBuilder.UseStartup(); }); |
El método ClearProviders se utiliza para borrar cualquier proveedor ya añadido (por defecto). Así que puede reemplazar los predeterminados por los proveedores que desee
Después de añadir proveedores de registro, puede crear registros. Esto se puede hacer utilizando el objeto ILogger<>, que se puede obtener a partir de la inyección de dependencia. Entonces debe crear un logger con la categoría específica (cadena), puede ser un controlador o el nombre de una clase:
| 1 2 3 4 5 6 7 8 9 10 | public class WeatherForecastController : ControllerBase { private readonly ILogger _logger; public WeatherForecastController(ILogger logger) { _logger = logger; } |
Entonces está listo para escribir registros. Se puede hacer con los métodos LogInformation, LogError, LogWarning, etc. Por ejemplo:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 | public IEnumerable Get() { _logger.LogInformation("Method 'Get' called at {0}", DateTime.UtcNow); var rng = new Random(); return Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateTime.Now.AddDays(index), TemperatureC = rng.Next(-20, 55), Summary = Summaries[rng.Next(Summaries.Length)] }) .ToArray(); } |
Entonces, si añade Console como proveedor, después de cualquier llamada de este método podrá ver en la consola de salida algo como
| 1 2 3 | Method `Get` called 04/07/2020 09:58:06 |
Para escribir registros, puede utilizar uno de los siguientes niveles de registro, que proporciona .NET Core:
- Rastreo= 0. Normalmente se utiliza sólo para el desarrollo, deshabilitado por defecto para evitar que los datos sensibles pasen a producción.
- Depuración= 1. Cualquier información de depuración (por ejemplo, el valor de un parámetro en algún paso de la ejecución del código), puede habilitarse en producción para la resolución de problemas.
- Información= 2. Información general utilizada para proporcionar algunos mensajes sobre el paso actual o el estado del sistema.
- Advertencia= 3. Utilizado para proporcionar cualquier evento inesperado, que no bloquea la ejecución de la aplicación.
- Error= 4. Utilizado para errores y excepciones que no fueron manejados y pueden indicar una falla en la operación actual.
- Crítico= 5. Se utiliza para proporcionar información sobre cualquier error que requiera atención inmediata. Por ejemplo, poca memoria de disco, etc.
marcos de registro de .NET
El uso de un marco de trabajo de terceros es muy similar al uso de proveedores incorporados. Sólo tiene que añadir un paquete NuGet a su proyecto y, a continuación, llamar a un método de extensión ILoggerFactory que el marco de registro proporciona. Estos marcos pueden proporcionarle más habilidades y características para mejorar su proceso de registro, realizar un registro semántico y mejorar la vista de los registros creados.
En este artículo, echaremos un vistazo a tres marcos de registro diferentes para .NET: NLog, Serilog y Log4Net.
Marco de registro NLog
NLog es una plataforma de registro gratuita para plataformas .NET. NLog admite el cambio de la configuración de registro sobre la marcha, el registro estructurado y puede escribir fácilmente en varios objetivos. Las principales ventajas de utilizar NLog son: facilidad de uso, ampliación, configuración y alto rendimiento.
Para empezar a utilizar el marco de trabajo NLog es necesario instalar la última versión de los paquetes NLog y NLog.Web.AspNetCore a través del gestor de paquetes NuGet
A continuación, debe crear el archivo nlog.config en la raíz del proyecto. Este archivo describe los objetivos en los que se escribirán los registros y algunas reglas adicionales para iniciar el registro.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | <!-- enable asp.net core layout renderers --> <!-- the targets to write to --> <!-- write logs to file --> <!-- another file log, only own logs. Uses some ASP.NET core renderers --> <!-- rules to map from logger name to target --> <!--All logs, including from Microsoft--> <!--Skip non-critical Microsoft logs and so log only own logs--> <!-- BlackHole without writeTo --> |
El siguiente paso es habilitar la copia de la carpeta bin para nlog.config. Se puede hacer de la siguiente manera:
En el explorador de soluciones, abra las propiedades del archivo nlog.config y, a continuación, establezca el parámetro “Copiar en el directorio de salida” en “Copiar si es nuevo”.
A continuación, debe actualizar el archivo Program.cs para iniciar el NLog.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | public class Program { public static void Main(string[] args) { var logger = NLog.Web.NLogBuilder.ConfigureNLog("nlog.config").GetCurrentClassLogger(); try { logger.Debug("init main"); CreateHostBuilder(args).Build().Run(); } catch (Exception exception) { //NLog: catch setup errors logger.Error(exception, "Stopped program because of exception"); throw; } finally { // Ensure to flush and stop internal timers/threads before application-exit (Avoid segmentation fault on Linux) NLog.LogManager.Shutdown(); } } public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .ConfigureLogging(configureLogging => { configureLogging.ClearProviders(); configureLogging.SetMinimumLevel(Microsoft.Extensions.Logging.LogLevel.Trace); }) .ConfigureWebHostDefaults(webBuilder => { webBuilder.UseStartup(); }) .UseNLog(); // NLog: Setup NLog for Dependency injection } |
El siguiente paso es configurar appsettings.json. Es necesario eliminar “Default” o poner los valores correctos. De lo contrario, anulará cualquier llamada a SetMinimumLevel. Puede configurar el registro de esta manera:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 | { "Logging": { "IncludeScopes": false, "LogLevel": { "Default": "Trace", "Microsoft": "Warning", "Microsoft.Hosting.Lifetime": "Information" } }, "AllowedHosts": "*" } |
En caso de que tenga diferentes entornos y utilice diferentes archivos de configuración, recuerde especificar estos parámetros en cada uno de ellos.
Ahora, cuando complete todos los pasos anteriores, puede intentar escribir registros. Por ejemplo, puede escribir registros en su controlador de la siguiente manera:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | public class WeatherForecastController : ControllerBase { private readonly ILogger _logger; public WeatherForecastController(ILogger logger) { _logger = logger; _logger.LogDebug(1, "NLog injected into WeatherForecastController"); } private static readonly string[] Summaries = new[] { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }; [HttpGet] public IEnumerable Get() { _logger.LogInformation("Method 'Get' called at {0}", DateTime.UtcNow); var rng = new Random(); return Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateTime.Now.AddDays(index), TemperatureC = rng.Next(-20, 55), Summary = Summaries[rng.Next(Summaries.Length)] }) .ToArray(); } } |
Como puede ver, el uso de NLog es bastante similar al registro por defecto de .NET Core. Ahora puede comprobar sus registros en el lugar que configuró en el archivo nlog.config. Será así:
| 1 2 3 4 5 6 7 | 2020-04-07 14:31:58.4400||DEBUG|LoggingSample.Program|init main 2020-04-07 14:31:59.1861||INFO|Microsoft.Hosting.Lifetime|Application started. Press Ctrl+C to shut down. 2020-04-07 14:31:59.1861||INFO|Microsoft.Hosting.Lifetime|Hosting environment: Development 2020-04-07 14:31:59.1979||INFO|Microsoft.Hosting.Lifetime|Content root path: C:UsersAdminsourcereposLoggingSampleLoggingSample 2020-04-07 14:31:59.2970||INFO|LoggingSample.Controllers.WeatherForecastController|Method 'Get' called at 07-Apr-20 11:31:59 |
Para utilizar el registro estructurado en NLog puede simplemente controlar el formato precediendo a @. Por ejemplo:
| 1 2 3 4 5 6 7 8 | var order = new Order { OrderId = 2, Status = OrderStatus.Processing }; logger.Info("Order updated: {@value1}", order); |
Resultado de la salida:
| 1 2 3 | Order updated: {"OrderId":2, "Status":"Processing"} |
Si utilizamos esta declaración sin el símbolo @, como
| 1 2 3 | logger.Info("Order updated: {value1}", order); |
Así que, como puede ver, utilizar el registro estructurado en el framework NLog es realmente fácil. Sólo un símbolo le permite dar a sus registros más contexto, lo que puede ayudar en el proceso de gestión de errores.
Resumiendo el marco NLog, es realmente similar al registro por defecto y realmente fácil de configurar y empezar a trabajar con él. Por cierto, sólo hay una cosa que debe saber antes de usar este framework: no obtendrá ninguna pista si algo va mal con NLog. Por ejemplo, si falla el archivo de configuración, NLog no empezará a funcionar. No recibirá ninguna notificación al respecto. Se hizo para evitar que cualquier aplicación se caiga a causa del registro. Pero puede no ser una buena sorpresa si algo va mal, y descubrirá que los registros están vacíos debido a un archivo de configuración incorrecto.
Marco de registro Serilog
Serilog es otra biblioteca que proporciona el registro a la consola, a los archivos o a cualquier otro lugar. Tiene una API limpia y es fácil de configurar. Está construida pensando en datos de eventos potentes y estructurados.
Para empezar a trabajar con Serilog necesita instalar dos paquetes usando NuGet – Serilog y Serilog.Sinks.Console. Para crear el registrador, sólo tiene que escribir el código siguiente:
| 1 2 3 4 5 | var logger = new LoggerConfiguration() .WriteTo.Console() .CreateLogger(); |
Después de esto puede utilizar fácilmente el logger de la misma manera que el logger incorporado:
| 1 2 3 | log.Information("Hello, Serilog!"); |
Además, puede cambiar el proveedor por cualquier otro que desee utilizando el método de extensión WriteTo. Por ejemplo, para utilizar la salida de archivos puede probar el código siguiente:
| 1 2 3 4 5 6 7 8 | Log.Logger = new LoggerConfiguration() .MinimumLevel.Debug() .WriteTo.File("logs\myapp.txt", rollingInterval: RollingInterval.Day) .CreateLogger(); Log.Information("Hello, world!"); |
Serilog soporta el registro estructurado. Si necesita registrar algún objeto, puede utilizar la siguiente sentencia:
| 1 2 3 4 5 6 | var position = new { Latitude = 25, Longitude = 134 }; var elapsedMs = 34; log.Information("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs); |
Este operador ‘@’ le dice a Serilog que serialice el objeto y lo convierta utilizando el método ToString
Otra característica interesante de Serilog es el enriquecimiento. Se trata de una parte de código que se ejecuta con cada solicitud de registro y proporciona información adicional a la solicitud. Con la ayuda del enriquecedor, puede proporcionar más información sin ningún movimiento especial en cada solicitud. Simplemente puede añadir cualquier propiedad adicional a la solicitud. Esto ayuda a que los rastros de pila sean más comprensibles.
Si comprueba los registros, obtendrá algo así:
| 1 2 3 4 5 6 | [15:46:03 INF] Hello, world! [15:46:03 INF] Processed { Latitude: 25, Longitude: 134 } in 034 ms. [15:46:03 DBG] Dividing 10 by 0 [15:46:03 ERR] Something went wrong |
Como puede ver, el registro estructurado proporciona todo el modelo de objetos en formato JSON en los registros. Así que permite todas las características del registro estructurado sin ningún problema, y es realmente fácil de implementar en su aplicación.
Resumiendo, Serilog es una herramienta relativamente fácil de usar. El soporte de registro estructurado es bastante bueno, y los registros pueden ser enviados a un gran número de destinos.
Marco de registro Apache log4net
Log4net es una biblioteca que proporciona la capacidad de mostrar la salida del registro a cualquiera de los destinos de salida. Log4net proporciona una función para activar o desactivar el registro en tiempo de ejecución sin modificar el código de la aplicación. Las principales ventajas son la velocidad y la flexibilidad.
Para empezar a trabajar con lo4net es necesario instalarlo a través de NuGet. Luego hay que crear un archivo de configuración. Tiene formato XML y debe contener algo así:
| 1 2 3 | <!-- Pattern to output the caller's file name and line number --> |
Después de eso, podemos empezar a trabajar con log4net. Los registros estructurados en log4net se pueden crear sin una sintaxis especial, simplemente pasando un objeto como parámetro. El código siguiente muestra un ejemplo de uso de log4net para crear registros simples y estructurados:
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | class Program { private static readonly ILog log = LogManager.GetLogger(typeof(Program)); static void Main(string[] args) { var logRepository = LogManager.GetRepository(Assembly.GetEntryAssembly()); XmlConfigurator.Configure(logRepository, new FileInfo("log4net.config")); log.Debug("Starting up"); log.Debug(new { color = "red", num = 1 }); log.Debug("Shutting down"); Console.ReadLine(); } } |
Si ejecutamos esta aplicación y luego comprobamos la salida, podemos ver
| 1 2 3 4 5 | 2018-08-18 18:57:37,278 DEBUG 1 LoggingDemo.Log4Net.Program - Starting up 2018-08-18 18:57:37,298 DEBUG 1 LoggingDemo.Log4Net.Program - { color = red, int1 = 1 } 2018-08-18 18:57:37,298 DEBUG 1 LoggingDemo.Log4Net.Program - Shutting down |
Resumiendo log4net, tengo que prestar atención a algunas cosas importantes. No está en absoluto bien documentado, y puede ser difícil empezar a trabajar con él. El archivo de configuración por defecto no es la opción adecuada. Debe configurarlo usted mismo. Así que si necesita un comienzo rápido y quiere tener una documentación adecuada, tal vez deba probar otra cosa.
Conclusión
Vamos a comparar algunos pasos básicos para implementar el registro estructurado y las características que se pueden proporcionar.
| log4net | NLog | Serilog | |
| Documentación | Tiene documentación general y muestras | Está bien documentada y tiene muchos ejemplos | Está bien documentado y tiene muchas muestras y tutoriales |
| compatibilidad con .NET | .NET Framework 2.0 o superior .NET Core 1.0 o superior | marcos .NET 3.5 – 4.8 .NET Core 1.0 o superior | .NET Framework 4.5 o superior .NET Core 1.0 o superior |
| Pasar el objeto completo a los registros | Pasar simplemente un objeto como parámetro | Marcar un objeto con @ | Marcar un objeto con @ |
| Configuración | Es necesario personalizar el archivo de configuración para obtener una mejor vista de los registros | No se requiere ninguna configuración especial para el registro estructurado | No se requiere ninguna configuración especial para el registro estructurado |
| Complejidad de la implementación | Similar a la API de registro por defecto, pero es necesario personalizar el archivo de configuración | Similar a la API de registro por defecto, fácil de implementar, pero no hay pistas si la implementación no fue exitosa y no funciona | Similar a la API de registro por defecto, fácil de implementar |
Como puede ver, estos tres frameworks de registro de .NET son similares, y no es un gran problema cambiar a cualquiera de ellos, porque tienen declaraciones similares, y pueden ser fácilmente instalados y utilizados. Además, podemos utilizar cualquiera de estos marcos para implementar el registro estructurado en su aplicación. Todos ellos proporcionan características similares.
Pero si tenemos que tomar algunas decisiones y seleccionar sólo uno, yo recomendaría probar Serilog debido a su moderna API, su fácil configuración y mantenimiento, y su sencillo soporte de registro estructurado desde dentro de la caja. Por cierto, está muy bien documentado y es fácil de usar, en general. Sin embargo, como todos son bastante similares, puede probar a utilizar cada uno de ellos sin ninguna dificultad y tomar su propia decisión.
Vea cómo adaptamos la aplicación de recomendación de música de Facebook para su lanzamiento en el mercado estadounidense utilizando marcos .NET
