Correlacionando Registros y Trazas de .NET

Documentos > APM > Correlacionar los datos de APM con otros datos de telemetría > Correlacione registros y trazas > Correlacionando Registros y Trazas de .NET

Puede configurar su biblioteca de registros y las configuraciones de trazado de .NET para que los ID de traza y de tramo se inyecten en los registros de la aplicación, proporcionándole datos de monitoreo del rendimiento de la aplicación correlacionados con los datos de registro.

Configure el .NET Tracer con Unified Service Tagging para la mejor experiencia y un contexto útil al correlacionar trazas y registros de la aplicación.

El .NET Tracer admite las siguientes bibliotecas de registros:

Serilog (v1.4+)
log4net
NLog
Microsoft.Extensions.Logging (agregado en v1.28.6)

Configure la recolección de registros

Asegúrese de que la recolección de registros esté configurada en el Agente de Datadog y que la configuración del Agente de Registros para los archivos especificados a seguir esté configurada en source: csharp para que las canalizaciones de registros puedan parsear los archivos de registro. Para más información, consulta Recolección de Registros en C#. Si el source está configurado a un valor diferente de csharp, es posible que necesites agregar un remapeador de trazas a la canalización de procesamiento de registros apropiada para que la correlación funcione correctamente.

La recolección automática de registros solo funciona para registros formateados como JSON. Alternativamente, utilice reglas de parseo personalizadas.

Configure la inyección en los registros

Para inyectar identificadores de correlación en sus mensajes de registro, siga las instrucciones para su biblioteca de registro.

Vea los ejemplos en dd-trace-dotnet para más ejemplos.

Nota: A partir de la versión 2.0.1 del .NET Tracer, la inyección automática para la biblioteca de registro Serilog requiere que la aplicación esté instrumentada con instrumentación automática.

Para inyectar automáticamente identificadores de correlación en sus mensajes de registro:

Configure el .NET Tracer con las siguientes configuraciones del Tracer:
- DD_ENV
- DD_SERVICE
- DD_VERSION
Habilite el trazado de instrumentación automática de su aplicación siguiendo las instrucciones para instalar el .NET Tracer.

Nota: A partir de la versión 1.29.0 del .NET Tracer, la inyección automática para la biblioteca de registro log4net requiere que la aplicación esté instrumentada con instrumentación automática.

Para inyectar automáticamente identificadores de correlación en sus mensajes de registro:

Configure el .NET Tracer con las siguientes configuraciones del tracer:
- DD_ENV
- DD_SERVICE
- DD_VERSION
Habilite el trazado de instrumentación automática de su aplicación siguiendo las instrucciones para instalar el .NET Tracer.
Agregue dd.env, dd.service, dd.version, dd.trace_id y dd.span_id propiedades de registro en su salida. Esto se puede hacer incluyendo estas propiedades individualmente o incluyendo todas las propiedades de registro. 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 ejemplos adicionales, consulte el proyecto de inyección automática de ID de traza 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 NLog requiere que la aplicación esté instrumentada con instrumentación automática.

Para inyectar automáticamente identificadores de correlación en sus mensajes de registro:

Configure el .NET Tracer con las siguientes configuraciones del tracer:
- DD_ENV
- DD_SERVICE
- DD_VERSION
Habilite el trazado de instrumentación automática de su aplicación siguiendo las instrucciones para instalar el .NET Tracer.
Habilite el contexto de diagnóstico mapeado (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 ejemplos adicionales, consulte 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 sus mensajes de registro:

Configure el .NET Tracer con las siguientes configuraciones del tracer:
- DD_ENV
- DD_SERVICE
- DD_VERSION
Habilite el trazado de instrumentación automática de su aplicación siguiendo las instrucciones para instalar el .NET Tracer.
Habilite los ámbitos de registro para su proveedor de registro, como se muestra en el código de ejemplo. Solo los proveedores que admiten ámbitos de registro 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 registro, los IDs de traza y de span se inyectan automáticamente en los registros de la aplicación 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á utilizando una biblioteca de registro que reemplaza la implementación predeterminada de LoggerFactory, como los paquetes de Serilog.Extensions.Hosting o Serilog.Extensions.Logging, siga las instrucciones específicas del marco (en este ejemplo, consulte Serilog).

Para ejemplos adicionales, consulte el proyecto de inyección automática de ID de traza Microsoft.Extensions.Logging en GitHub.

A continuación, complete la configuración para la inyección automática o manual.

Inyección automática

Para habilitar la inyección automática del identificador de correlación, asegúrese de que DD_LOGS_INJECTION esté habilitado.

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

Para configurar el .NET Tracer con un método diferente, consulte Configuración del .NET Tracer.

Después de configurar la inyección del identificador de correlación, consulte Recopilación de registros en C# para configurar su recopilación de registros.

Nota: Para correlacionar trazas con registros, es posible que necesite configurar un remapeador de ID de traza para analizar dd_trace_id como el ID de traza del registro. Consulte Registros correlacionados que no aparecen en el panel de ID de traza para más información.

A partir de la versión 2.35.0, si Configuración Remota del Agente está habilitada donde se ejecuta este servicio, puede configurar DD_LOGS_INJECTION en la interfaz de usuario del Catálogo.

Inyección manual

Si prefiere correlacionar manualmente sus trazas con sus registros, puede agregar identificadores de correlación a sus registros.

Clave requerida	Descripción
`dd.env`	Configure globalmente el `env` para el SDK. Por defecto es `""` si no se establece.
`dd.service`	Configure globalmente el nombre del servicio raíz. Por defecto es el nombre de la aplicación o el nombre del sitio de IIS si no se establece.
`dd.version`	Configure globalmente `version` para el servicio. Por defecto es `""` si no se establece.
`dd.trace_id`	ID de traza activa (representado como un número decimal de 64 bits) durante la declaración de registro. Por defecto, se establece en `0` si no hay traza.
`dd.span_id`	ID de tramo activo (representado como un número decimal de 64 bits) durante la declaración de registro. Por defecto, se establece en `0` si no hay traza.

Nota: Si no está utilizando una Integración de Registro de Datadog para analizar sus registros, las reglas de análisis de registros personalizadas deben analizar dd.trace_id y dd.span_id como cadenas. Para más información, consulte Registros Correlacionados que No Aparecen en el Panel de ID de Traza.

Nota: Si está utilizando Serilog, Nlog o log4net a través de ILogger, consulte la sección Microsoft.Extensions.Logging para configurar estas propiedades utilizando BeginScope().

Después de completar los pasos iniciales, finalice su configuración manual de enriquecimiento de registros:

Agregue una referencia al Datadog.Trace paquete NuGet en su proyecto.
Utilice la CorrelationIdentifier API para recuperar identificadores de correlación y agregarlos al contexto de registro mientras un tramo está activo.

Por último, consulte Colección de Registros en C# para configurar su colección de registros.

Ejemplos:

Nota: La biblioteca Serilog requiere que los nombres de las propiedades de los mensajes sean identificadores válidos de C#. Los nombres de propiedades requeridos 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
}