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

Docs > APM > Correlate APM Data with Other Telemetry > 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 le 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é avec la v1.28.6)

Configurer la collecte de logs

Vérifiez que la collecte de logs est activée dans l’Agent Datadog et que la configuration de l’Agent de log pour le suivi des fichiers spécifiés est définie sur source: csharp, afin que les pipelines de log puissent parser les fichiers de log. Pour en savoir plus, consultez la section Collecte de logs avec C#. Si la source est définie sur une valeur autre que csharp, vous devrez peut-être ajouter un remappeur de traces vers le pipeline de traitement de logs approprié pour que la mise en corrélation fonctionne correctement.

Remarque : la collecte automatique de logs fonctionne uniquement pour les logs au format JSON. Pour les autres formats, utilisez des règles de parsing personnalisées.

Configurer l’injection dans les logs

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

Consultez les extraits dans dd-trace-dotnet pour obtenir d'autres exemples.

Remarque : depuis la version 2.0.1 du traceur .NET, l'injection automatique pour la bibliothèque de journalisation Serilog requiert l'instrumentation automatique de l'application.

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

Configurez le traceur .NET avec les paramètres suivants :
- DD_ENV
- DD_SERVICE
- DD_VERSION
Pour activer le tracing de l’instrumentation automatique de votre application, suivez les instructions d’installation du traceur .NET.

Remarque : depuis la version 1.29.0 du traceur .NET, l'injection automatique pour la bibliothèque de journalisation log4net requiert l'instrumentation automatique de l'application.

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

Configurez le traceur .NET avec les paramètres suivants :
- DD_ENV
- DD_SERVICE
- DD_VERSION
Pour activer le tracing de l’instrumentation automatique de votre application, suivez les instructions d’installation du traceur .NET.
Ajoutez les propriétés de log dd.env, dd.service, dd.version, dd.trace_id et dd.span_id à votre sortie de journalisation. Pour ce faire, vous pouvez inclure chaque propriété ou l’ensemble d’entre elles. L’exemple de code suivant illustre les deux approches :

  <layout type="log4net.Layout.SerializedLayout, log4net.Ext.Json">
    <decorator type="log4net.Layout.Decorators.StandardTypesDecorator, log4net.Ext.Json" />
    <default />
    <!--membres par défaut explicites-->
    <remove value="ndc" />
    <!--Supprimer le membre du message préformaté par défaut-->
    <remove value="message" />
    <!--Ajouter le message brut-->
    <member value="message:messageobject" />

    <!-- Inclure des propriétés Datadog-->
    <!-- 1re option : ajouter des propriétés individuelles avec 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' />
    <!-- 2e options : ajouter toutes les propriétés avec 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 : depuis la version 2.0.1 du traceur .NET, l'injection automatique pour la bibliothèque de journalisation NLog requiert l'instrumentation automatique de l'application.

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

Configurez le traceur .NET avec les paramètres suivants :
- DD_ENV
- DD_SERVICE
- DD_VERSION
Pour activer le tracing de l’instrumentation automatique de votre application, suivez les instructions d’installation du traceur .NET.
Activez le contexte de diagnostic mappé (MDC), comme dans l’exemple de code suivant pour les versions 5.0+ de NLog :

  <!-- Ajouter includeScopeProperties="true" pour injecter les propriétés de 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>

Pour les versions 4.6 et ultérieures de NLog :

  <!-- Ajouter includeMdlc="true" pour injecter les propriétés du 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>

Pour la version 4.5 de NLog :

  <!-- Ajouter includeMdc="true" pour injecter les propriétés du 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>

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 :

Configurez le traceur .NET avec les paramètres suivants :
- DD_ENV
- DD_SERVICE
- DD_VERSION
Pour activer le tracing de l’instrumentation automatique de votre application, suivez les instructions d’installation du traceur .NET.
Activez les contexte de log pour votre fournisseur de journalisation, tel qu’indiqué dans l’exemple de code ci-dessous. Seuls les fournisseurs prenant en charge les contextes de log injectent des identificateurs de corrélation.

Host.CreateDefaultBuilder(args)
    .ConfigureLogging(logging =>
    {
        logging.AddFile(opts =>
        {
            opts.IncludeScopes = true; // les contextes doivent être inclus pour permettre l'ajout des identificateurs de corrélation
            opts.FormatterName = "json";
        });
    }

Si une trace est active lors de l’écriture du log, les ID de trace et de span sont automatiquement injectés dans les logs de l’application, avec les propriétés dd_trace_id et dd_span_id. Si aucune trace n’est active, seules les propriétés dd_env, dd_service et dd_version sont injectées.

Remarque : si votre bibliothèque de journalisation remplace l’implémentation LoggerFactory par défaut, par exemple le package Serilog.Extensions.Hosting ou le package Serilog.Extensions.Logging, suivez les instructions spécifiques au framework (dans cet exemple, consultez les instructions pour 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 en suivant les étapes pour l’injection automatique ou manuelle.

Injection automatique

Pour activer l’injection automatique des identificateurs de corrélation, il ne vous reste plus qu’à effectuer l’étape suivante :

Activez DD_LOGS_INJECTION=true dans les variables d’environnement du traceur .NET. Pour configurer le traceur .NET avec une autre méthode, consultez la documentation dédiée.

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

Remarque : pour mettre en corrélation les traces avec les logs, vous devrez peut-être définir un remapper d’ID de trace afin de parser dd_trace_id en tant qu’ID de trace des logs. Consultez la section Les logs corrélés ne s’affichent pas dans le volet des ID de trace pour en savoir plus.

Bêta : depuis la version 2.35.0, si la configuration à distance de l'Agent est activée à l'emplacement où ce service s'exécute, vous pouvez définir DD_LOGS_INJECTION depuis l'interface du catalogue des services.

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	Rôle
`dd.env`	Configure globalement le paramètre `env` pour le traceur. Valeur par défaut en l’absence de configuration : `""`.
`dd.service`	Configure globalement le nom du service racine. Valeur par défaut en l’absence de configuration : le nom de l’application ou le nom du site IIS.
`dd.version`	Configure globalement le paramètre `version` pour le service. Valeur par défaut en l’absence de configuration : `""`.
`dd.trace_id`	ID de la trace active lors de la déclaration du log. Valeur par défaut en l’absence de trace : `0`.
`dd.span_id`	ID de la span active lors de la déclaration du log. Valeur par défaut en l’absence de span : `0`.

Remarque : si vous n’utilisez pas une intégration de log de Datadog pour parser vos logs, des règles de parsing de log personnalisées doivent être définies pour parser dd.trace_id et dd.span_id en tant que chaînes. Pour en savoir plus, consultez la documentation Les logs corrélés ne s’affichent pas dans le volet des 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 avec BeginScope().

Après avoir effectué les étapes de prise en main, procédez comme suit pour terminer la configuration de l’enrichissement manuel de vos logs :

Ajoutez le package NuGet Datadog.Trace comme référence dans votre projet.
Utilisez l’API CorrelationIdentifier pour récupérer les identificateurs de corrélation et les ajouter au contexte des logs lorsqu’une span est active.

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

Exemples :

Remarque : la bibliothèque Serilog exige que les noms de propriété de message soient des identificateurs C# valides. Les noms de propriété imposés sont : dd_env, dd_service, dd_version, dd_trace_id et dd_span_id.

using Datadog.Trace;
using Serilog.Context;

// Des spans doivent avoir été initialisées et être actives avant ce bloc.
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()))
{
    // Loguer quelque chose
}

using Datadog.Trace;
using log4net;

// Des spans doivent avoir été initialisées et être actives avant ce bloc.
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();

    // Loguer quelque chose

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

// Des spans doivent avoir été initialisées et être actives avant ce bloc.
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()))
{
    // Loguer quelque chose
}

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

ILogger _logger;

// Des spans doivent avoir été lancées et doivent être actives avant ce bloc.
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()},
}))
{
    // Loguer un événement
}