Tracer des applications .NET Core

Exigences de compatibilité

Runtimes .NET Core pris en charge

Le traceur .NET prend en charge l’instrumentation sur .NET Core 2.1 et 3.1, .NET 5, .NET 6 et .NET 7.

Pour obtenir la liste complète des bibliothèques et architectures de processeur .NET Core de Datadog prises en charge (y compris les anciennes versions et les versions de maintenance), consultez la section relative aux exigences de compatibilité.

Installation et démarrage

Installation

1. Configurer l’Agent Datadog pour l’APM
2. Installer le traceur
3. Activer le traceur
4. Visualiser vos données en temps réel

Configurer l’Agent Datadog pour l’APM

Installez et configurez l’Agent Datadog de façon à ce qu’il reçoive les traces provenant de votre application instrumentée. Par défaut, l’Agent Datadog est activé dans votre fichier datadog.yaml avec l’option enabled: true sous apm_config. Il détecte les données de trace sur http://localhost:8126.

Pour les environnements conteneurisés, sans serveur et cloud, référez-vous aux instructions ci-dessous :

1. Définissez apm_non_local_traffic: true dans la section apm_config de votre fichier de configuration principal datadog.yaml.

2. Consultez les instructions de configuration spécifiques pour vous assurer que l’Agent est configuré de façon à recevoir des traces dans un environnement conteneurisé :

3. Le client de tracing tente d’envoyer des traces aux éléments suivants :

   • Le socket de domaine Unix /var/run/datadog/apm.socket par défaut.
   • Si le socket n’existe pas, les traces sont envoyées à localhost:8126.
   • Si un autre socket, host ou port est requis, utilisez la variable d’environnement DD_TRACE_AGENT_URL : DD_TRACE_AGENT_URL=http://custom-hostname:1234 ou DD_TRACE_AGENT_URL=unix:///var/run/datadog/apm.socket
   • L’utilisation des sockets de domaine Unix pour le transport de traces est possible uniquement sur NET Core 3.1 ou une version ultérieure.

Pour en savoir plus sur la configuration de ces paramètres, consultez la section Configuration.

4. Pour vous assurer que l’Agent envoie des données au bon site Datadog, définissez le paramètre DD_SITE de l’Agent Datadog sur .

Le tracing est disponible pour d’autres environnements, tels que Heroku, Cloud Foundry et AWS Elastic Beanstalk.

Pour tous les autres environnements, consultez la documentation relative aux intégrations pour l’environnement qui vous intéresse et contactez l’assistance Datadog si vous rencontrez des problèmes de configuration.

Installer le traceur

Vous pouvez installer le traceur .NET Datadog à l’échelle d’une machine afin d’instrumenter tous les services sur la machine. Il est également possible d’installer le traceur pour certaines applications, afin que les développeurs puissent gérer l’instrumentation via les dépendances de l’application. Pour obtenir des instructions afin d’installer le traceur à l’échelle d’une machine, cliquez sur l’onglet Windows ou Linux. Pour obtenir des instructions afin d’installer le traceur pour certaines applications, cliquez sur l’onglet NuGet.

Activer le traceur pour votre service

Pour activer le traceur .NET pour votre service, définissez les variables d’environnement requises et redémarrez l’application.

Pour en savoir plus sur les différentes options disponibles pour définir les variables d’environnement, consultez la rubrique Configurer des variables d’environnement de processus.

Visualiser vos données en temps réel

Après avoir activé le traceur .NET pour votre service, procédez comme suit :

1. Redémarrez votre service.

2. Créez une charge d’application.

3. Dans Datadog, accédez à APM > APM Traces.

Configuration

Au besoin, configurez la bibliothèque de tracing pour envoyer les données de télémétrie relatives aux performances de l’application, notamment en configurant le tagging de service unifié. Consultez la section relative à la configuration de la bibliothèque pour en savoir plus.

Instrumentation personnalisée

La configuration de l’instrumentation personnalisée varie selon votre instrumentation automatique. Certaines méthodes peuvent également inclure des étapes supplémentaires.

Pour découvrir comment ajouter des spans et des tags pour l’instrumentation personnalisée, consultez la documentation relative à l’instrumentation personnalisée .NET.

Configurer des variables d’environnement de processus

Pour intégrer une instrumentation automatique à votre service, vous devez définir les variables d’environnement requises avant de démarrer l’application. Consultez la rubrique Activer le traceur pour votre service pour déterminer les variables d’environnement que vous devez définir en fonction de la méthode d’installation du traceur .NET. Référez-vous aux exemples ci-dessous afin de définir correctement les variables d’environnement pour l’environnement de votre service instrumenté.

Windows

Services Windows

Dans l’éditeur du registre, créez une valeur multi-chaînes Environment dans la clé HKLM\System\CurrentControlSet\Services\<NOM_SERVICE> et définissez les données de la valeur sur :

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}

[string[]] $v = @("CORECLR_ENABLE_PROFILING=1", "CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}")
Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<NOM_SERVICE> -Name Environment -Value $v

IIS

Une fois le programme d’installation MSI installé, aucune autre configuration n’est requise pour instrumenter automatiquement vos sites IIS. Pour définir d’autres variables d’environnement qui seront transmises à tous les sites IIS, suivez les étapes ci-dessous :

1. Ouvrez l’éditeur de registre, recherchez la valeur multi-chaînes intitulée Environment dans la clé HKLM\System\CurrentControlSet\Services\WAS, puis ajoutez chaque variable d’environnement sur une ligne distincte. Pour ajouter une injection de logs et des métriques runtime, vous pouvez par exemple ajouter les lignes suivantes aux données de valeur :

   DD_LOGS_INJECTION=true
   DD_RUNTIME_METRICS_ENABLED=true
   

2. Exécutez les commandes suivantes pour redémarrer IIS :

   net stop /y was
   net start w3svc
   # Also, start any other services that were stopped when WAS was shut down.
   

Applications console

Pour instrumenter automatiquement une application console, définissez les variables d’environnement depuis un fichier de commandes avant de démarrer votre application :

rem Définir des variables d'environnement
SET CORECLR_ENABLE_PROFILING=1
rem Sauf pour la v2.14.0 ou une version ultérieure si vous avez installé le traceur avec le programme d'installation MSI
SET CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}

rem Définir d'autres variables d'environnement Datadog
SET DD_LOGS_INJECTION=true
SET DD_RUNTIME_METRICS_ENABLED=true

rem Lancer l'application
dotnet.exe example.dll

Linux

Script bash

Pour définir les variables d’environnement requises à l’aide d’un fichier bash avant le lancement de votre application :

# Définir des variables d'environnement
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
export CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
export DD_DOTNET_TRACER_HOME=/opt/datadog

# Définir d'autres variables d'environnement Datadog
export DD_LOGS_INJECTION=true
export DD_RUNTIME_METRICS_ENABLED=true

# Lancer votre application
dotnet example.dll

Conteneur Docker Linux

Pour définir les variables d’environnement requises sur un conteneur Docker Linux :

# Définir des variables d'environnement
ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
ENV CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
ENV DD_DOTNET_TRACER_HOME=/opt/datadog

# Définir d'autres variables d'environnement Datadog
ENV DD_LOGS_INJECTION=true
ENV DD_RUNTIME_METRICS_ENABLED=true

# Lancer votre application
CMD ["dotnet", "example.dll"]

systemctl (service spécifique)

Lorsque vous utilisez la commande systemctl pour exécuter des applications .NET en tant que service, vous pouvez ajouter les variables d’environnement requises qui doivent être chargées pour un service spécifique.

1. Créez un fichier nommé environment.env contenant :

   CORECLR_ENABLE_PROFILING=1
   CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
   CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
   DD_DOTNET_TRACER_HOME=/opt/datadog
   
   # Set additional Datadog environment variables
   DD_LOGS_INJECTION=true
   DD_RUNTIME_METRICS_ENABLED=true
   

2. Dans le fichier de configuration du service, ajoutez une référence vers ce fichier en tant que EnvironmentFile dans le bloc Service :

   [Service]
   EnvironmentFile=/path/to/environment.env
   ExecStart=<command used to start the application>
   

3. Relancez le service .NET pour que les variables d’environnement soient appliquées.

systemctl (tous les services)

Lorsque vous utilisez la commande systemctl pour exécuter des applications .NET en tant que service, vous pouvez également faire en sorte que les variables d’environnement soient chargées pour tous les services exécutés par systemctl.

1. Définissez les variables d’environnement requises en exécutant systemctl set-environment :

   systemctl set-environment CORECLR_ENABLE_PROFILING=1
   systemctl set-environment CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
   systemctl set-environment CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so
   systemctl set-environment DD_DOTNET_TRACER_HOME=/opt/datadog
   
   # Set additional Datadog environment variables
   systemctl set-environment DD_LOGS_INJECTION=true
   systemctl set-environment DD_RUNTIME_METRICS_ENABLED=true
   

2. Vérifiez que les variables d’environnement ont bien été définies en exécutant systemctl show-environment.

3. Relancez le service .NET pour que les variables d’environnement soient appliquées.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

Associer vos logs d'application .NET à vos tracesDOCUMENTATION Métriques runtimeDOCUMENTATION Extension Microsoft Azure App ServiceDOCUMENTATION Explorer vos services, ressources et tracesDOCUMENTATION Surveillance .NET avec l'APM et le tracing distribué de DatadogBLOG Surveiller des applications ASP.NET Core conteneuriséesBLOG Déployer des applications ASP.NET Core sur Azure App ServiceBLOG Optimiser les performances de votre application .NET avec le profileur en continu DatadogGITHUB Exemples d'instrumentation personnaliséeGITHUB Code sourceGITHUB