Correlación de logs y trazas de .NET
Puedes establecer tu biblioteca de registro y las configuraciones de rastreo de .NET para que los IDs de traza y tramo se inyecten en los logs de aplicación, lo que te proporcionará datos de monitorización del rendimiento de la aplicación correlacionados con los datos de log.
Configura el .NET Tracer con el etiquetado de servicios unificado para obtener la mejor experiencia y un contexto útil al correlacionar las trazas y logs de aplicación.
.NET Tracer admite las siguientes bibliotecas de registro:
Configuración de la recopilación de logs
Asegúrate de que la recopilación de log está configurada en el Datadog Agent y que la configuración del Logs Agent para los archivos especificados a la cola esté establecida en source: csharp
, de modo que los pipelines de log puedan analizar los archivos de log. Para obtener más información, consulta Recopilación de logs de C#. Si source
se establece en un valor distinto de csharp
, es posible que tengas que añadir un reasignador de traza al pipeline de procesamiento de log apropiado para que la correlación funcione correctamente.
Nota: La recopilación automática de log solo funciona para logs con formato JSON. Como alternativa, utiliza reglas personalizadas de parseo.
Configuración de la inyección en logs
Para inyectar identificadores de correlación en tus mensajes de log, sigue las instrucciones de tu biblioteca de registro.
Nota: A partir de la versión 2.0.1 de .NET Tracer, la inyección automática para la biblioteca de registro de Serilog requiere que la aplicación esté instrumentada con la instrumentación automática.
Para inyectar automáticamente identificadores de correlación en tus mensajes de log:
Configura el .NET Tracer con la siguiente configuración del rastreador:
DD_ENV
DD_SERVICE
DD_VERSION
Activa el rastreo de instrumentación automática de tu aplicación siguiendo las instrucciones para instalar .NET Tracer.
Nota: A partir de la versión 1.29.0 de .NET Tracer, la inyección automática para la biblioteca de registro log4net requiere que la aplicación esté instrumentada con la instrumentación automática.
Para inyectar automáticamente identificadores de correlación en tus mensajes de log:
Configura el .NET Tracer con la siguiente configuración del rastreador:
DD_ENV
DD_SERVICE
DD_VERSION
Activa el rastreo de instrumentación automática de tu aplicación siguiendo las instrucciones para instalar .NET Tracer.
Añade las propiedades de log dd.env
, dd.service
, dd.version
, dd.trace_id
y dd.span_id
en tu salida de registro. Puedes hacer esto al incluir estas propiedades individualmente o al incluir todas las propiedades de log. Ambos enfoques se muestran en el siguiente código de ejemplo:
<layout type="log4net.Layout.SerializedLayout, log4net.Ext.Json">
<decorator type="log4net.Layout.Decorators.StandardTypesDecorator, log4net.Ext.Json" />
<default />
<!--miembros explícitos por defecto-->
<remove value="ndc" />
<!--elimina el miembro del mensaje preformateado por defecto-->
<remove value="message" />
<!--añade mensajes sin formato-->
<member value="message:messageobject" />
<!-- Incluye propiedades de Datadog -->
<!-- Incluye propiedades individuales con value='<property_name>' -->
<member value='dd.env' />
<member value='dd.service' />
<member value='dd.version' />
<member value='dd.trace_id' />
<member value='dd.span_id' />
<!-- O incluye todas las propiedades con value='properties' -->
<member value='properties'/>
</layout>
Para ver ejemplos adicionales, consulta el proyecto de inyección automática de ID de traza de log4net en GitHub.
Nota: A partir de la versión 2.0.1 de .NET Tracer, la inyección automática para la biblioteca de registro de NLog requiere que la aplicación esté instrumentada con la instrumentación automática.
Para inyectar automáticamente identificadores de correlación en tus mensajes de log:
Configura el .NET Tracer con la siguiente configuración del rastreador:
DD_ENV
DD_SERVICE
DD_VERSION
Activa el rastreo de instrumentación automática de tu aplicación siguiendo las instrucciones para instalar .NET Tracer.
Habilita el contexto de diagnóstico asignado (MDC), como se muestra en el siguiente código de ejemplo para NLog versión 5.0+:
<!-- Añade includeScopeProperties="true" para emitir propiedades ScopeContext -->
<layout xsi:type="JsonLayout" includeScopeProperties="true">
<attribute name="date" layout="${longdate}" />
<attribute name="level" layout="${level:upperCase=true}"/>
<attribute name="message" layout="${message}" />
<attribute name="exception" layout="${exception:format=ToString}" />
</layout>
Para NLog versión 4.6+:
<!-- Añade includeMdlc="true" para emitir propiedades MDC -->
<layout xsi:type="JsonLayout" includeMdlc="true">
<attribute name="date" layout="${longdate}" />
<attribute name="level" layout="${level:upperCase=true}"/>
<attribute name="message" layout="${message}" />
<attribute name="exception" layout="${exception:format=ToString}" />
</layout>
Para NLog versión 4.5:
<!-- Añade includeMdc="true" para emitir propiedades MDC -->
<layout xsi:type="JsonLayout" includeMdc="true">
<attribute name="date" layout="${longdate}" />
<attribute name="level" layout="${level:upperCase=true}"/>
<attribute name="message" layout="${message}" />
<attribute name="exception" layout="${exception:format=ToString}" />
</layout>
Para ver ejemplos adicionales, consulta los proyectos de inyección automática de ID de traza utilizando NLog 4.0, NLog 4.5, o NLog 4.6 en GitHub.
Para inyectar automáticamente identificadores de correlación en tus mensajes de log:
Configura el .NET Tracer con la siguiente configuración del rastreador:
DD_ENV
DD_SERVICE
DD_VERSION
Activa el rastreo de instrumentación automática de tu aplicación siguiendo las instrucciones para instalar .NET Tracer.
Activa contextos de log para tu proveedor de registro, como se muestra en el código de ejemplo. Solo los proveedores que admiten contextos de log tendrán identificadores de correlación inyectados.
Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging =>
{
logging.AddFile(opts =>
{
opts.IncludeScopes = true; // debes incluir contextos para que se añadan identificadores de correlación
opts.FormatterName = "json";
});
}
Si hay una traza activa cuando se está escribiendo el log, los IDs de traza y tramo se inyectan automáticamente en la aplicación de logs con las propiedades dd_trace_id
y dd_span_id
. Si no hay una traza activa, solo se inyectan las propiedades dd_env
, dd_service
y dd_version
.
Nota: Si estás utilizando una biblioteca de registro que reemplaza el despliegueLoggerFactory
por defecto como los paquetes Serilog.Extensions.Hosting o Serilog.Extensions.Logging, sigue las instrucciones específicas del marco (en este ejemplo, ve Serilog).
Para obtener ejemplos adicionales, consulta el proyecto de inyección de ID de traza automática Microsoft.Extensions.Logging en GitHub.
A continuación, completa la configuración para la inyección automática o manual.
Inyección automática
El último paso para activar la inyección automática de identificadores de correlación es:
- Activa
DD_LOGS_INJECTION=true
en las variables de entorno del .NET Tracer. Para configurar el .NET Tracer con un método diferente, consulta Configuración de .NET Tracer.
Después de configurar la inyección del identificador de correlación, consulta Recopilación de log de C# para configurar tu recopilación de log.
Nota: Para correlacionar trazas con logs, puede que necesites configurar un reasignador de ID de traza para analizar dd_trace_id
como el ID de traza del log. Consulta Los logs correlacionados no aparecen en el panel de ID de traza para obtener más información.
Inyección manual
Si prefieres correlacionar manualmente tus trazas con tus logs, puedes añadir identificadores de correlación a tus logs.
Clave requerida | Descripción |
---|
dd.env | Configura globalmente el env para el rastreador. Por defecto es "" si no se configura. |
dd.service | Configura globalmente el nombre raíz del servicio. Por defecto es el nombre de la aplicación o el nombre del sitio IIS si no está configurado. |
dd.version | Configura globalmente version para el servicio. Por defecto es "" si no se configura. |
dd.trace_id | ID activo de traza durante la sentencia de log. Por defecto 0 si no hay traza. |
dd.span_id | ID activo de tramo durante la sentencia de log. Por defecto 0 si no hay traza. |
Nota: Si no utilizas la integración de log de Datadog para analizar tus logs, las reglas personalizadas de parseo de log deben analizar dd.trace_id
y dd.span_id
como cadenas. Para obtener más información, consulta Los Logs correlacionados no aparecen en el panel de ID de traza.
Nota: Si estás utilizando Serilog, Nlog o log4net a través de ILogger, consulta la sección Microsoft.Extensions.Logging para configurar estas propiedades con BeginScope()
.
Después de completar los pasos de introducción, termina tu configuración de mejora de log manual:
Haz referencia al paquete Datadog.Trace
de NuGet en tu proyecto.
Utiliza la API CorrelationIdentifier
para recuperar identificadores de correlación y añadirlos al contexto de log mientras esté activo un tramo.
Por último, consulta Recopilación de log de C# para configurar tu recopilación de log.
Ejemplos:
Nota: La biblioteca de Serilog requiere que los nombres de las propiedades de los mensajes sean identificadores C# válidos. Los nombres de propiedades obligatorios son: dd_env
, dd_service
, dd_version
, dd_trace_id
y dd_span_id
.
using Datadog.Trace;
using Serilog.Context;
// deben haber tramos iniciados y activos antes de este bloque.
using (LogContext.PushProperty("dd_env", CorrelationIdentifier.Env))
using (LogContext.PushProperty("dd_service", CorrelationIdentifier.Service))
using (LogContext.PushProperty("dd_version", CorrelationIdentifier.Version))
using (LogContext.PushProperty("dd_trace_id", CorrelationIdentifier.TraceId.ToString()))
using (LogContext.PushProperty("dd_span_id", CorrelationIdentifier.SpanId.ToString()))
{
// Loguear algo
}
using Datadog.Trace;
using log4net;
// deben haber tramos iniciados y activos antes de este bloque.
try
{
LogicalThreadContext.Properties["dd.env"] = CorrelationIdentifier.Env;
LogicalThreadContext.Properties["dd.service"] = CorrelationIdentifier.Service;
LogicalThreadContext.Properties["dd.version"] = CorrelationIdentifier.Version;
LogicalThreadContext.Properties["dd.trace_id"] = CorrelationIdentifier.TraceId.ToString();
LogicalThreadContext.Properties["dd.span_id"] = CorrelationIdentifier.SpanId.ToString();
// Loguear algo.
}
finally
{
LogicalThreadContext.Properties.Remove("dd.env");
LogicalThreadContext.Properties.Remove("dd.service");
LogicalThreadContext.Properties.Remove("dd.version");
LogicalThreadContext.Properties.Remove("dd.trace_id");
LogicalThreadContext.Properties.Remove("dd.span_id");
}
using Datadog.Trace;
using NLog;
// deben haber tramos iniciados y activos antes de este bloque.
using (MappedDiagnosticsLogicalContext.SetScoped("dd.env", CorrelationIdentifier.Env))
using (MappedDiagnosticsLogicalContext.SetScoped("dd.service", CorrelationIdentifier.Service))
using (MappedDiagnosticsLogicalContext.SetScoped("dd.version", CorrelationIdentifier.Version))
using (MappedDiagnosticsLogicalContext.SetScoped("dd.trace_id", CorrelationIdentifier.TraceId.ToString()))
using (MappedDiagnosticsLogicalContext.SetScoped("dd.span_id", CorrelationIdentifier.SpanId.ToString()))
{
// Loguear algo.
}
using Datadog.Trace;
using Microsoft.Extensions.Logging;
ILogger _logger;
// deben haber tramos iniciados y activos antes de este bloque.
using(_logger.BeginScope(new Dictionary<string, object>
{
{"dd.env", CorrelationIdentifier.Env},
{"dd.service", CorrelationIdentifier.Service},
{"dd.version", CorrelationIdentifier.Version},
{"dd.trace_id", CorrelationIdentifier.TraceId.ToString()},
{"dd.span_id", CorrelationIdentifier.SpanId.ToString()},
}))
{
// Loguear algo.
}
Puedes obtener más información sobre el uso de BeginScope para crear mensajes estructurados de log para los siguientes proveedores de log:
Leer más
Additional helpful documentation, links, and articles: