Introducción
Cada vez que ocurre un problema en producción, lo primero que hacemos es abrir los logs. Pero ¿cuántas veces te has encontrado con algo así?
| |
Sin OrderId. Sin CustomerId. Sin saber en qué instancia ocurrió ni en qué versión de la aplicación. Este tipo de log existe en miles de aplicaciones — y no ayuda absolutamente a nadie.
El problema no es la falta de logs. Es la falta de contexto, la falta de estructura y la falta de control. Cuando la aplicación necesita más detalle, tienes que cambiar la configuración, hacer deploy, esperar el reinicio — y cruzar los dedos para capturar el error antes de revertir.
En este artículo, voy a mostrar una estrategia completa de logging para .NET 8 que resuelve estos tres problemas de una vez:
- Estructurado: cada entrada de log lleva propiedades tipadas, no solo texto plano
- Contextual: cada línea de log incluye automáticamente información de la aplicación, del host y del request
- Dinámico: el nivel de log se puede cambiar en producción con un timer de reversión automática — sin deploy, sin reinicio
Todo esto usando el ILogger<T> nativo, sin crear wrappers innecesarios, cumpliendo con SonarQube e integrado con Azure Application Insights.
La implementación completa está disponible en el repositorio blog-zocateli-sample en GitHub. A lo largo del artículo, voy a mostrar los fragmentos clave y explicar el razonamiento detrás de cada decisión. Si quieres ver el contexto completo en cualquier momento, consulta las fuentes en el repositorio.
📦 Código fuente: La implementación completa de este artículo está en el repositorio blog-zocateli-sample en GitHub. Clónalo, explóralo y adáptalo a tu contexto.
💡 Este artículo complementa el Pipeline de Configuración de .NET 8+, que explica cómo funcionan el sistema de configuración,
IOptions<T>y los secrets. La estrategia de logging descrita aquí depende directamente de esos conceptos.
El Problema: Por Qué tus Logs No Ayudan
Considera estos dos escenarios reales de log en producción:
Antes — log sin contexto:
| |
Un analista de soporte mira esto y no puede responder ninguna pregunta: ¿qué pedido? ¿De qué cliente? ¿En qué instancia? ¿Era la versión nueva o la antigua? ¿Este error se reproduce o fue puntual?
Después — log estructurado con contexto:
| |
Con este segundo formato, el analista puede:
- Filtrar por
OrderIdpara ver todo lo que le ocurrió a ese pedido - Agrupar por
HostNamepara identificar si el problema es de una instancia específica - Usar el
CorrelationIdpara rastrear todo el pipeline de un único request - Comparar
ApplicationVersionpara saber si el bug es de la versión nueva
El costo del troubleshooting cae drásticamente. En lugar de horas rebuscando en logs genéricos, encuentras la causa en minutos con una query en Application Insights.
💡 Un log sin contexto en producción es como buscar un error en Google sin escribir el mensaje de error — técnicamente estás buscando, pero no vas a encontrar nada útil.
Logging Estructurado: Qué Es y Por Qué Importa
Logging estructurado significa que cada entrada de log lleva propiedades tipadas e indexables, no solo un string concatenado.
En .NET, la diferencia es sutil en el código pero enorme en el resultado:
| |
Cuando usas la plantilla con {OrderId}, ILogger preserva el valor como una propiedad separada. En Application Insights, aparece en customDimensions y se puede filtrar, agregar y correlacionar con queries KQL. Cuando usas string interpolation con $, el valor queda embebido en el mensaje — Application Insights recibe solo texto y no puede indexarlo.
Las consecuencias prácticas son directas:
- Con propiedades estructuradas:
customDimensions["OrderId"] == "3fa85f64..."— filtrable - Con un string interpolado: necesitas usar
containso una regex sobre el mensaje — lento e impreciso
Además de la cuestión funcional, SonarQube marca la string interpolation en logs como la regla S6664 (Log message template should be compile-time constant), ya que puede afectar el rendimiento y se pierde la capacidad de agrupar mensajes similares.
⚠️ Nunca uses
$"Pedido {orderId}"en llamadas de log. Eso crea un string nuevo en cada llamada (incluso cuando el nivel de log está deshabilitado) y pierde la propiedad estructurada. Usa siempre la plantilla:"Pedido {OrderId}".
Enriquecimiento Automático: Contexto de la Aplicación en Cada Log
Si cada desarrollador tiene que acordarse de incluir ApplicationName, HostName y CorrelationId en cada llamada de log, eso no va a suceder. La solución es enriquecer automáticamente.
Middleware con ILogger.BeginScope()
ILogger admite scopes — un bloque que agrega propiedades a todas las entradas de log hechas dentro de él. Combinando esto con un middleware, garantizamos que todo log de cualquier request lleve el contexto de la aplicación:
| |
El middleware se registra como singleton (por implementar IMiddleware) y se activa en el pipeline:
| |
Las propiedades ApplicationName y Version vienen de una sección dedicada del appsettings.json:
| |
ℹ️ La clase
LoggingOptionsse configura mediante el patrónIOptions<T>. Si quieres entender en profundidad cómo funciona este mecanismo, consulta el artículo sobre el Pipeline de Configuración de .NET 8+.
TelemetryInitializer para Application Insights
BeginScope() enriquece los logs de ILogger, pero la telemetría que Application Insights captura automáticamente (requests HTTP, dependencias, exceptions) no pasa por ILogger. Para garantizar que toda la telemetría lleve las mismas propiedades, usamos un ITelemetryInitializer:
| |
Registrado en el DI como:
| |
Con estas dos piezas tienes cobertura completa: LogEnrichmentMiddleware para los logs de ILogger y ApplicationTelemetryInitializer para request traces, dependency calls y exceptions capturadas automáticamente por el SDK.
Nivel de Log Dinámico con Timer Automático
Escenario real: tu aplicación en producción tiene un comportamiento extraño. Necesitas ver logs de nivel Debug para entender qué está pasando. Pero el appsettings.json de producción está configurado con Information.
El camino tradicional sería: cambiar la configuración, hacer deploy (o reiniciar), capturar los logs detallados y después deshacerlo todo para no ahogar a Application Insights en volumen (y costo). Este proceso puede llevar de minutos a horas dependiendo de tu pipeline.
La solución propuesta aquí es un endpoint administrativo que cambia el nivel de log en runtime, con un timer de reversión automática:
| |
Después de 15 minutos, el nivel vuelve automáticamente al configurado en el appsettings.json. Sin deploy. Sin reinicio. Sin riesgo de olvidar el Debug encendido.
El Mecanismo: ConfigurationProvider Personalizado
El sistema de logging de .NET lee los niveles de log del pipeline de configuración. La clave que define el nivel por defecto es Logging:LogLevel:Default, y por categoría es Logging:LogLevel:{CategoryName}.
La estrategia es crear un ConfigurationProvider personalizado que pueda actualizarse en runtime y que, al cambiar, dispare OnReload() para notificar al framework:
| |
El punto crítico es el registro: este provider debe agregarse al final del pipeline de configuración, para que su valor sobrescriba el del appsettings.json:
| |
El Servicio con Timer
DynamicLogLevelService orquesta la lógica de cambio y de reversión automática:
| |
Puntos importantes de esta implementación:
- El
Timerse crea conTimeout.InfiniteTimeSpancomo period — se ejecuta una única vez después deldueTime - Si se vuelve a llamar a
SetLogLevelantes de que el timer expire, el timer anterior se descarta y se crea uno nuevo - El
lockgarantiza thread safety entre el timer (que se ejecuta en un hilo del ThreadPool) y las llamadas simultáneas - Se implementa
IDisposablepara la limpieza correcta delTimer
💡 Protege este endpoint con la autorización adecuada — en producción, solo los administradores deberían cambiar el nivel de log. Consulta el artículo sobre Autenticación y Autorización: JWT, OAuth2 y OpenID Connect para ver estrategias de protección.
ILogger Nativo: Sin Reinventar la Rueda
Un patrón que veo con una frecuencia preocupante es la creación de un ICustomLogger o LogService que encapsula el ILogger<T>:
| |
Este wrapper rompe varios mecanismos:
- La categoría del log pasa a ser siempre
CustomLoggeren lugar de la clase real que originó el log - Los filtros por namespace (
Logging:LogLevel:MiNamespace) dejan de funcionar - La trazabilidad en Application Insights se ve perjudicada
- Los tests se vuelven más complejos (hay que mockear el wrapper y no el ILogger)
El enfoque correcto en el .NET moderno es usar ILogger<T> directamente y el atributo [LoggerMessage] para generar los métodos de log mediante un source generator:
| |
Beneficios del Source Generator [LoggerMessage]
- Rendimiento: el source generator crea código que verifica el nivel de log antes de construir el mensaje — cero asignaciones cuando el log está deshabilitado
- AOT-friendly: compatible con Native AOT, sin reflection en runtime
- Cumplimiento con SonarQube: resuelve las reglas S6664 (plantilla constante en tiempo de compilación), S2629 (logging guard) y S6667 (structured logging)
- EventId: cada mensaje tiene un ID numérico fijo, lo que facilita alertas y dashboards
- Testeable: como son métodos estáticos con
ILoggercomo parámetro, pasar un mock en los tests es trivial
El uso es directo en cualquier endpoint o servicio:
| |
⚠️ Crear un
ICustomLoggerque encapsulaILogger<T>añade una capa sin valor, rompe la trazabilidad y dificulta los tests. UsaILogger<T>directamente con[LoggerMessage]— es la abstracción correcta.
Integración con Azure Application Insights
Application Insights es el APM (Application Performance Management) de Azure que captura automáticamente requests HTTP, dependencias (bases de datos, HTTP clients, colas) y exceptions. El logging estructurado que implementamos complementa esa telemetría automática con el contexto de negocio.
Setup
La configuración es mínima — una línea en Program.cs y la connection string en la configuración:
| |
| |
⚠️ Nunca pongas la connection string directamente en el código fuente ni en el
appsettings.jsonversionado. Usa variables de entorno, Azure Key Vault o User Secrets para el desarrollo local. Consulta cómo configurarlo en el artículo Pipeline de Configuración de .NET 8+.
Cómo Aparece el Log Estructurado en Application Insights
Cuando haces un log usando [LoggerMessage] con propiedades estructuradas, cada propiedad aparece en customDimensions en Application Insights. Combinado con las propiedades inyectadas por LogEnrichmentMiddleware y por ApplicationTelemetryInitializer, el resultado es:
| Columna | Valor |
|---|---|
message | Order 3fa85f64… created for customer C-1234, total: 150.00 |
customDimensions.OrderId | 3fa85f64-5717-4562-b3fc-2c963f66afa6 |
customDimensions.CustomerId | C-1234 |
customDimensions.Total | 150.00 |
customDimensions.ApplicationName | SampleApi |
customDimensions.ApplicationVersion | 1.0.0 |
customDimensions.HostName | pod-api-7b4f9c |
customDimensions.CorrelationId | 0HN6KQ2JH2S5E:00000001 |
Queries KQL para Troubleshooting
Con estas propiedades indexadas, las queries en Application Insights se vuelven quirúrgicas:
| |
ℹ️ Application Insights ya captura automáticamente requests HTTP, dependencias y exceptions — el log estructurado lo complementa con el contexto de negocio que solo tu aplicación conoce.
La Aplicación de Ejemplo
La aplicación de ejemplo implementa todos los conceptos de este artículo en una Minimal API de .NET 8. La estructura del proyecto organiza los componentes de logging en una carpeta dedicada:
| |

El diagrama anterior muestra cómo se conectan los componentes: cada request HTTP pasa por el LogEnrichmentMiddleware, que abre un BeginScope() con las propiedades de contexto. Cualquier llamada de log hecha dentro de ese request — ya sea en los endpoints, en los servicios o en bibliotecas internas — hereda automáticamente esas propiedades. En paralelo, ApplicationTelemetryInitializer garantiza que la telemetría automática de Application Insights (requests, dependencies) también lleve la misma información.
Cómo Ejecutar Localmente
| |
Prueba el endpoint de log dinámico:
| |
El repositorio completo con instrucciones detalladas está en github.com/lzocateli/blog-zocateli-sample — Logging.
Consejos y Buenas Prácticas
Estas son las prácticas que considero esenciales para una estrategia de logging robusta:
Usa las categorías de log con criterio: .NET usa el namespace de la clase como categoría (
ILogger<OrderService>genera la categoríaSampleApi.Endpoints.OrderService). Esto permite filtrar por namespace en elappsettings.json— por ejemplo,"SampleApi.Endpoints": "Debug"activa debug solo en los endpoints sin afectar al resto de la aplicación.Nunca registres datos sensibles: nombres, CPF (identificación fiscal brasileña), tokens, contraseñas y datos financieros no deben aparecer en los logs. Además del riesgo de seguridad, la LGPD brasileña exige la protección de los datos personales. Si necesitas rastrear a un usuario, usa un identificador opaco como
CustomerId.Controla el costo de Application Insights: con volumen alto, Application Insights cobra por la ingesta de datos. Usa sampling adaptativo para reducir el volumen sin perder visibilidad. La configuración por defecto del SDK ya incluye sampling — evita deshabilitarlo sin un cálculo de costos.
EventId consistente por mensaje: cada
[LoggerMessage]debe tener unEventIdúnico y fijo. Esto permite crear alertas en Azure Monitor basadas en el EventId (más confiable que una regex sobre el mensaje) y facilita los dashboards de operación.Entorno de desarrollo con consola JSON: configura
appsettings.Development.jsonpara usar elJsonConsoleFormatterconIncludeScopes: true. Esto muestra las propiedades estructuradas directamente en la terminal durante el desarrollo, sin necesidad de Application Insights.Prueba los logs: con
[LoggerMessage]eILogger<T>, es trivial verificar en los tests unitarios si se emitieron los logs correctos. La aplicación de ejemplo incluye tests del middleware que verifican las propiedades inyectadas en el scope.Registra las operaciones administrativas como Warning: los cambios de nivel de log, los reinicios y las operaciones manuales deben registrarse como
Warning— visibles por defecto y fáciles de auditar.
Conclusión
Un logging eficiente no se trata de cantidad — se trata de calidad y contexto. En este artículo, cubrimos tres pilares que, juntos, transforman los logs de ruido en una herramienta de diagnóstico:
- Estructura: propiedades tipadas con el source generator
[LoggerMessage]en lugar de strings concatenados - Contexto automático:
LogEnrichmentMiddlewareconBeginScope()yApplicationTelemetryInitializergarantizan que cada entrada de log lleve la información de la aplicación, del host y del request - Control dinámico: un
ConfigurationProviderpersonalizado conOnReload()y un timer permite activarDebugen producción de forma segura y temporal
Todo esto funciona con el ILogger<T> nativo de .NET — sin wrappers, sin abstracciones inventadas, sin romper SonarQube. Application Insights recibe las propiedades en customDimensions, lo que permite queries KQL quirúrgicas para el troubleshooting.
Si tu aplicación todavía usa _logger.LogInformation($"Procesando pedido {id}"), ahora es un buen momento para evolucionar. Clona el repositorio de ejemplo, adáptalo a tu contexto y nota la diferencia la próxima vez que necesites investigar un problema en producción.
Para trabajar con logs en servicios background de larga duración, mira cómo aplicar esta misma estrategia en Worker y Background Service en .NET: Alto Volumen.
Lee También
- Pipeline de Configuración de .NET 8+ —
IOptions<T>, Secrets y configuración externalizada que sostienen la estrategia de logging - Worker y Background Service en .NET: Alto Volumen — logging en servicios background de alto volumen
- Cuello de Botella en Bases de Datos: Mensajería y Paginación — troubleshooting de rendimiento donde los logs son esenciales
- Programación Asíncrona en C#: async/await y Threads — async/await y contexto de ejecución que afectan a los log scopes
- Autenticación y Autorización: JWT, OAuth2 y OpenID Connect — protección de endpoints administrativos como el de nivel de log dinámico
Referencias
- Logging in .NET — Microsoft Learn
- LoggerMessage source generator — Microsoft Learn
- Compile-time logging source generation — Microsoft Learn
- Application Insights for ASP.NET Core — Microsoft Learn
- Configuration in ASP.NET Core — Microsoft Learn
- Log scopes — Microsoft Learn
- Azure Monitor KQL reference
- Application Insights sampling — Microsoft Learn
- SonarQube rule S6664 — Log message template
- SonarQube rule S2629 — Logging templates should be constant
- Repositorio blog-zocateli-sample — Logging — Código fuente completo de los ejemplos de este artículo

Al comentar, aceptas nuestra Política de Privacidad, Términos de Uso, Política de Eliminación de Datos.