Associer vos logs .NET à 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 :

Prise en main

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

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 :

  1. Configurez le traceur .NET avec les paramètres suivants :

    • DD_ENV
    • DD_SERVICE
    • DD_VERSION
  2. 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 :

  1. Configurez le traceur .NET avec les paramètres suivants :

    • DD_ENV
    • DD_SERVICE
    • DD_VERSION
  2. Pour activer le tracing de l’instrumentation automatique de votre application, suivez les instructions d’installation du traceur .NET.

  3. 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 :

  1. Configurez le traceur .NET avec les paramètres suivants :

    • DD_ENV
    • DD_SERVICE
    • DD_VERSION
  2. Pour activer le tracing de l’instrumentation automatique de votre application, suivez les instructions d’installation du traceur .NET.

  3. Activez le contexte de diagnostic mappé (MDC), tel qu’expliqué dans l’exemple de code suivant pour les versions 4.6+ 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 :

  1. Configurez le traceur .NET avec les paramètres suivants :

    • DD_ENV
    • DD_SERVICE
    • DD_VERSION
  2. Pour activer le tracing de l’instrumentation automatique de votre application, suivez les instructions d’installation du traceur .NET.

  3. 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; // doit inclure des contextes afin d'ajouter les 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 :

  1. 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 relative aux logs corrélés dans le volet des ID de trace pour en savoir plus.

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é requiseDescription
dd.envConfigure globalement le paramètre env pour le traceur. Valeur par défaut en l’absence de configuration : "".
dd.serviceConfigure 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.versionConfigure globalement le paramètre version pour le service. Valeur par défaut en l’absence de configuration : "".
dd.trace_idID de la trace active lors de la déclaration du log. Valeur par défaut en l’absence de trace : 0.
dd.span_idID 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 FAQ à ce sujet.

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 :

  1. Ajoutez le package NuGet Datadog.Trace comme référence dans votre projet.

  2. 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
}

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

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.

Pour aller plus loin