Correlación de logs y trazas de .NET

Documentos > APM > Correlacionar los datos de APM con otros datos de telemetría > Correlacionar logs y trazas > 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:

Serilog (v1.4+)
log4net
NLog
Microsoft.Extensions.Logging (añadido en v1.28.6)

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.

La recopilación automática de logs solo funciona para logs formateados como JSON. Como alternativa, utiliza reglas de parseo personalizadas.

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.

Consulta las muestras en dd-trace-dotnet para ver más ejemplos.

Nota: A partir de la versión 2.0.1 del rastreador de .NET, 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 del rastreador de .NET, la inyección automática para la biblioteca de registro de log4net requiere que la aplicación esté instrumentada con 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 />
    <!--explicit default members-->
    <remove value="ndc" />
    <!--remove the default preformatted message member-->
    <remove value="message" />
    <!--add raw message-->
    <member value="message:messageobject" />

    <!-- Include Datadog properties -->
    <!-- EITHER Include individual properties with 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' />
    <!-- OR Include all properties with 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 del rastreador de .NET, la inyección automática para la biblioteca de registro de NLog requiere que la aplicación esté instrumentada con 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+:

  <!-- Add includeScopeProperties="true" to emit ScopeContext properties -->
  <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+:

  <!-- Add includeMdlc="true" to emit MDC properties -->
  <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:

  <!-- Add includeMdc="true" to emit MDC properties -->
  <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; // must include scopes so that correlation identifiers are added
            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 framework (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

Para activar la inyección automática de identificadores de correlación, asegúrate de que DD_LOGS_INJECTION está activado.

A partir de la versión 3.24.0, DD_LOGS_INJECTION está activado por defecto. Para versiones anteriores, configura DD_LOGS_INJECTION=true en las variables de entorno del rastreador de .NET.

Para configurar el rastreador de .NET con un método diferente, consulta Configuración del rastreador de .NET.

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.

A partir de la versión 2.35.0, si la configuración remota del Agent está habilitada donde se ejecuta este servicio, puedes establecer DD_LOGS_INJECTION en la interfaz de usuario de Software Catalog.

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 de traza activo (representado como un número decimal de 64 bits) durante la sentencia de log. Por defecto `0` si no hay trazas.
`dd.span_id`	ID de tramo activo (representado como un número decimal de 64 bits) durante la sentencia de log. Por defecto `0` si no hay trazas.

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;

// there must be spans started and active before this block.
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()))
{
    // Log something
}

using Datadog.Trace;
using log4net;

// there must be spans started and active before this block.
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();

    // Log something

}
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;

// there must be spans started and active before this block.
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()))
{
    // Log something
}

using Datadog.Trace;
using Microsoft.Extensions.Logging;

ILogger _logger;

// there must be spans started and active before this block.
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()},
}))
{
    // Log something
}