Mettre en corrélation vos logs .NET avec vos traces

Docs > APM > Corréler les données APM avec d'autres données de télémétrie > Corréler vos logs et vos traces > Mettre en corrélation vos logs .NET avec vos traces

Vous pouvez configurer votre bibliothèque de logging et vos configurations de tracing .NET de façon à injecter vos ID de trace et de span dans vos logs d’application. Vos données de surveillance des performances de votre application seront ainsi mises en corrélation avec vos données de log.

Configurez le traceur .NET avec le tagging de service unifié pour profiter d’une expérience optimale et d’informations de contexte utiles lorsque vous mettez en corrélation vos traces d’application et vos logs.

Le traceur .NET prend en charge les bibliothèques de logging suivantes :

Serilog (v1.4+)
log4net
NLog
Microsoft.Extensions.Logging (ajouté dans v1.28.6)

Configurer la collecte des journaux

Assurez-vous que la collecte des journaux est configurée dans l’Agent Datadog et que la configuration de l’Agent Logs pour les fichiers spécifiés à suivre est définie sur source: csharp afin que les pipelines de journaux puissent analyser les fichiers journaux. Pour plus d’informations, voir C# Log Collection. Si le source est défini sur une valeur autre que csharp, vous devrez peut-être ajouter un trace remapper au pipeline de traitement des journaux approprié pour que la corrélation fonctionne correctement.

La collecte automatique des journaux ne fonctionne que pour les journaux formatés en JSON. Alternativement, utilisez des règles d'analyse personnalisées.

Configurer l’injection dans les journaux

Pour injecter des identificateurs de corrélation dans vos messages de log, suivez les instructions ci-dessous pour votre bibliothèque de journalisation.

Voir les exemples dans dd-trace-dotnet pour plus d'exemples.

Remarque : À partir de la version 2.0.1 du Tracer .NET, l'injection automatique pour la bibliothèque de journaux Serilog nécessite que l'application soit instrumentée avec une instrumentation automatique.

Pour injecter automatiquement des identificateurs de corrélation dans vos messages de log, procédez comme suit :

Configurer le Tracer .NET avec les paramètres de tracer suivants :
- DD_ENV
- DD_SERVICE
- DD_VERSION
Activez le traçage d’auto-instrumentation de votre application en suivant les instructions pour installer le Tracer .NET.

Remarque : À partir de la version 1.29.0 du Tracer .NET, l'injection automatique pour la bibliothèque de journaux log4net nécessite que l'application soit instrumentée avec une instrumentation automatique.

Pour injecter automatiquement des identificateurs de corrélation dans vos messages de log, procédez comme suit :

Configurer le Tracer .NET avec les paramètres de tracer suivants :
- DD_ENV
- DD_SERVICE
- DD_VERSION
Activez le traçage d’auto-instrumentation de votre application en suivant les instructions pour installer le Tracer .NET.
Ajoutez les propriétés de journaux dd.env, dd.service, dd.version, dd.trace_id et dd.span_id dans votre sortie de journal. Cela peut être fait en incluant ces propriétés individuellement ou en incluant toutes les propriétés de journaux. Les deux approches sont montrées dans le code d’exemple suivant :

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

Pour obtenir d’autres exemples, consultez le projet d’injection automatique des ID de trace avec log4net sur GitHub.

Remarque : À partir de la version 2.0.1 de .NET Tracer, l'injection automatique pour la bibliothèque de journalisation NLog nécessite que l'application soit instrumentée avec une instrumentation automatique.

Pour injecter automatiquement des identificateurs de corrélation dans vos messages de log, procédez comme suit :

Configurer le Tracer .NET avec les paramètres de tracer suivants :
- DD_ENV
- DD_SERVICE
- DD_VERSION
Activez le traçage d’auto-instrumentation de votre application en suivant les instructions pour installer le Tracer .NET.
Activez le contexte de diagnostic mappé (MDC), comme montré dans le code d’exemple suivant pour NLog version 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>

Pour les versions 4.6 et ultérieures de NLog :

  <!-- 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>

Pour la version 4.5 de NLog :

  <!-- 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>

Pour obtenir d’autres exemples, consultez les projets d’injection automatique des ID de trace avec NLog 4.0, NLog 4.5 ou NLog 4.6 sur GitHub.

Pour injecter automatiquement des identificateurs de corrélation dans vos messages de log, procédez comme suit :

Configurer le Tracer .NET avec les paramètres de tracer suivants :
- DD_ENV
- DD_SERVICE
- DD_VERSION
Activez le traçage d’auto-instrumentation de votre application en suivant les instructions pour installer le Tracer .NET.
Activez les log scopes pour votre fournisseur de journalisation, comme montré dans le code d’exemple. Seuls les fournisseurs qui prennent en charge les log scopes auront des identifiants de corrélation injectés.

Host.CreateDefaultBuilder(args)
    .ConfigureLogging(logging =>
    {
        logging.AddFile(opts =>
        {
            opts.IncludeScopes = true; // must include scopes so that correlation identifiers are added
            opts.FormatterName = "json";
        });
    }

S’il y a une trace active lorsque le journal est écrit, les identifiants de trace et de span sont automatiquement injectés dans les journaux de l’application avec les propriétés dd_trace_id et dd_span_id. S’il n’y a pas de trace active, seules les propriétés dd_env, dd_service et dd_version sont injectées.

Remarque : Si vous utilisez une bibliothèque de journalisation qui remplace l’implémentation par défaut LoggerFactory comme les paquets Serilog.Extensions.Hosting ou Serilog.Extensions.Logging, suivez les instructions spécifiques au framework (dans cet exemple, voir Serilog).

Pour obtenir d’autres exemples, consultez le projet d’injection automatique des ID de trace avec Microsoft.Extensions.Logging sur GitHub.

Ensuite, finalisez la configuration pour une injection automatique ou manuelle.

Injection automatique

Pour activer l’injection automatique des identifiants de corrélation, assurez-vous que DD_LOGS_INJECTION est activé.

À partir de la version 3.24.0, DD_LOGS_INJECTION est activé par défaut. Pour les versions antérieures, définissez DD_LOGS_INJECTION=true dans les variables d’environnement de .NET Tracer.

Pour configurer le .NET Tracer avec une méthode différente, voir Configurer le .NET Tracer.

Une fois l’injection configurée, consultez la section Collecte de logs avec C# pour configurer la collecte de logs.

Remarque : Pour corréler les traces avec les journaux, vous devrez peut-être configurer un trace ID remapper pour analyser dd_trace_id comme l’ID de trace du journal. Voir Journaux corrélés non affichés dans le panneau d’ID de trace pour plus d’informations.

Starting in version 2.35.0, if Agent Remote Configuration is enabled where this service runs, you can set DD_LOGS_INJECTION dans l'interface utilisateur Catalog.

Injection manuelle

Si vous préférez corréler manuellement vos traces avec vos logs, vous pouvez ajouter des identificateurs de corrélation à vos logs :

Clé requise	Description
`dd.env`	Configure globalement le `env` pour le SDK. Par défaut, cela vaut `""` si non défini.
`dd.service`	Configure globalement le nom du service racine. Par défaut, cela prend le nom de l’application ou le nom du site IIS si non défini.
`dd.version`	Configure globalement `version` pour le service. Par défaut, cela vaut `""` si non défini.
`dd.trace_id`	ID de trace actif (représenté comme un nombre décimal de 64 bits) pendant l’instruction de journalisation. Par défaut, cela vaut `0` s’il n’y a pas de trace.
`dd.span_id`	ID de span actif (représenté comme un nombre décimal de 64 bits) pendant l’instruction de journalisation. Par défaut, cela vaut `0` s’il n’y a pas de trace.

Remarque: Si vous n’utilisez pas une Datadog Log Integration pour analyser vos journaux, des règles d’analyse de journaux personnalisées doivent analyser dd.trace_id et dd.span_id comme des chaînes. Pour plus d’informations, voir Les journaux corrélés n’apparaissent pas dans le panneau ID de trace.

Remarque : Si vous utilisez Serilog, NLog ou log4net via ILogger, consultez la section Microsoft.Extensions.Logging pour configurer ces propriétés en utilisant BeginScope().

Après avoir complété les étapes de démarrage, terminez votre configuration manuelle d’enrichissement des journaux :

Référencez le Datadog.Trace paquet NuGet dans votre projet.
Utilisez l’API CorrelationIdentifier pour récupérer les identifiants de corrélation et les ajouter au contexte de journalisation pendant qu’un span est actif.

Enfin, consultez la section Collecte de logs avec C# pour configurer la collecte de logs.

Exemples :

Remarque : La bibliothèque Serilog nécessite que les noms des propriétés de message soient des identifiants C# valides. Les noms de propriétés requis sont : dd_env, dd_service, dd_version, dd_trace_id et 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
}