NLog para C# (.NET): guía completa con ejemplos prácticos

Bienvenido a la guía detallada de la librería NLog para la plataforma .NET. NLog es un sistema de logging potente, flexible y de alto rendimiento que se ha convertido en el estándar de facto para muchos proyectos .NET. En este artículo cubriremos todo: desde la instalación hasta técnicas avanzadas, con ejemplos de código reales y consejos de optimización.

1. ¿Qué es NLog y por qué usarlo?

NLog (abreviatura de ".NET Logging") es una librería gratuita y de código abierto para la plataforma .NET, diseñada para un logging flexible y eficiente. Permite a los desarrolladores registrar información de diagnóstico (logs) en múltiples destinos: archivos, consola, bases de datos, sockets de red, sistemas de monitoreo (como Seq, Elasticsearch, Sentry) y muchos más.

¿Por qué es importante el logging? En el desarrollo de software moderno, los logs son la "caja negra" de la aplicación. Sin ellos, es imposible saber por qué falló un servidor, dónde ocurrió un error o qué datos se estaban procesando en el momento del fallo. NLog resuelve este problema ofreciendo:

Flexibilidad de enrutamiento: Puedes configurar diferentes niveles de logging (Trace, Debug, Info, Warn, Error, Fatal) para distintas partes de la aplicación.
Rendimiento: Escritura asíncrona, inicialización diferida e impacto mínimo en la velocidad de ejecución.
Extensibilidad: Cientos de targets (destinos) listos para usar y la posibilidad de crear los tuyos propios.
Configuración sin recompilar: Los ajustes se pueden modificar en caliente mediante XML, JSON o código.

NLog es ideal para: aplicaciones web (ASP.NET Core), utilidades de consola, microservicios, aplicaciones de escritorio (WPF/WinForms) y servicios en segundo plano (Windows Services, Worker Services).

2. Instalación

La instalación de NLog se realiza a través del gestor de paquetes NuGet. Ejecuta uno de los siguientes comandos en la consola del administrador de paquetes de Visual Studio o en la terminal de .NET CLI:

// Mediante .NET CLI (recomendado)
dotnet add package NLog

// Mediante Package Manager Console
Install-Package NLog

// Para ASP.NET Core también se recomienda instalar la integración:
dotnet add package NLog.Web.AspNetCore

Después de la instalación, deberás crear un archivo de configuración nlog.config en la raíz del proyecto (o configurar NLog mediante código).

3. Inicio rápido — ejemplo mínimo funcional

Crea una aplicación de consola y agrega el archivo nlog.config (clic derecho en el proyecto → Add → New Item → XML File → nómbralo nlog.config). Pega el siguiente contenido:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!-- Destino: dónde escribir los logs -->
    <targets>
        <target name="console" xsi:type="Console" layout="${longdate} | ${level:uppercase=true} | ${message} ${exception:format=ToString}" />
        <target name="file" xsi:type="File" fileName="${basedir}/logs/app-${shortdate}.log"
                layout="${longdate} | ${level:uppercase=true} | ${logger} | ${message} ${exception:format=ToString}" />
    </targets>

    <!-- Reglas de enrutamiento -->
    <rules>
        <logger name="*" minlevel="Debug" writeTo="console,file" />
    </rules>
</nlog>

Ahora escribimos el código en Program.cs:

using NLog;

public class Program
{
    // Creamos un logger para la clase actual
    private static readonly Logger Logger = LogManager.GetCurrentClassLogger();

    public static void Main(string[] args)
    {
        Logger.Info("Aplicación iniciada");
        
        try
        {
            var result = Divide(10, 0);
            Logger.Debug($"Resultado: {result}");
        }
        catch (Exception ex)
        {
            Logger.Error(ex, "Error al realizar la división");
        }
        
        Logger.Info("Aplicación finalizada");
    }

    private static int Divide(int a, int b)
    {
        Logger.Debug($"Dividiendo {a} entre {b}");
        return a / b;
    }
}

Al ejecutar la aplicación, verás los logs en la consola y también se guardarán en un archivo dentro de la carpeta logs/ de tu proyecto. ¡Así de fácil!

4. Configuración avanzada de targets

NLog ofrece una amplia variedad de targets (destinos) para enviar tus logs. Veamos algunos de los más utilizados:

4.1. Target de archivo con rotación

Para evitar que los archivos de log crezcan indefinidamente, puedes configurar la rotación automática:

<target name="fileRotated" xsi:type="File"
        fileName="${basedir}/logs/app.log"
        layout="${longdate} | ${level} | ${message}"
        archiveFileName="${basedir}/logs/archives/app.{#}.log"
        archiveEvery="Day"
        archiveNumbering="Rolling"
        maxArchiveFiles="7" />

4.2. Target de base de datos

Para almacenar logs en SQL Server u otras bases de datos:

<target name="database" xsi:type="Database"
        connectionString="Server=localhost;Database=LogsDB;Integrated Security=true;"
        commandText="INSERT INTO Logs (Date, Level, Logger, Message) VALUES (@date, @level, @logger, @message)">
    <parameter name="@date" layout="${date}" />
    <parameter name="@level" layout="${level}" />
    <parameter name="@logger" layout="${logger}" />
    <parameter name="@message" layout="${message}" />
</target>

4.3. Target para Seq (sistema de logging estructurado)

Seq es una herramienta popular para centralizar y analizar logs:

<target name="seq" xsi:type="Seq"
        serverUrl="http://localhost:5341"
        apiKey="tu-api-key"
        compact="true" />

5. Niveles de logging y filtrado

NLog soporta seis niveles de logging, de menor a mayor severidad:

Trace (0) — Información de depuración muy detallada
Debug (1) — Información de depuración general
Info (2) — Mensajes informativos del flujo normal
Warn (3) — Advertencias sobre posibles problemas
Error (4) — Errores recuperables
Fatal (5) — Errores críticos que detienen la aplicación

Puedes filtrar qué niveles se registran en cada target:

<rules>
    <!-- Solo errores y fatales a la base de datos -->
    <logger name="*" minlevel="Error" writeTo="database" />
    
    <!-- Todos los niveles desde Debug al archivo -->
    <logger name="*" minlevel="Debug" writeTo="file" />
    
    <!-- Solo Info y superiores a la consola -->
    <logger name="*" minlevel="Info" writeTo="console" />
</rules>

6. Buenas prácticas y consejos de optimización

Para aprovechar NLog al máximo, ten en cuenta estas recomendaciones:

Usa logging asíncrono en aplicaciones de alto rendimiento: <target name="async" xsi:type="AsyncWrapper" queueLimit="5000" overflowAction="Discard">
Evita el logging excesivo en bucles o métodos críticos para el rendimiento
Utiliza niveles adecuados: no uses Error para mensajes informativos ni viceversa
Incluye contexto útil: IDs de transacción, nombres de usuario, etc.
Configura la rotación de archivos para evitar llenar el disco
Centraliza los logs en producción usando herramientas como Seq, Elastic Stack o Azure Monitor

7. Conclusión

NLog es una herramienta indispensable para cualquier desarrollador .NET que quiera implementar un sistema de logging robusto y flexible. Con su fácil instalación, configuración intuitiva y amplia gama de destinos, te permite tener visibilidad total sobre el comportamiento de tus aplicaciones.

¿Listo para implementar NLog en tu próximo proyecto? ¡Comienza hoy y lleva el monitoreo de tus aplicaciones al siguiente nivel!