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
Datadog vous recommande de suivre les instructions de démarrage rapide fournies dans l'application Datadog pour profiter d'une expérience optimale, et notamment les sections suivantes :
- Obtenir des instructions détaillées en fonction de la configuration de votre déploiement (hosts, Docker, Kubernetes ou Amazon ECS) ;
- Définir les tags service
, env
et version
de façon dynamique ;
- Activer l'ingestion de 100 % des traces et l'injection des ID de trace dans les logs durant la configuration.
Remarque : l'instrumentation automatique Datadog repose sur l'API CLR Profiling .NET. Celle-ci permet seulement d'ajouter un abonné (par exemple, le traceur .NET Datadog avec le profileur activé). Pour bénéficier d'une visibilité optimisée, exécutez une seule solution APM dans l'environnement de votre application.
Pour instrumenter des applications découpées, ajoutez le package NuGet
Datadog.Trace.Trimming comme référence dans votre projet. La prise en charge des applications découpées est en version bêta.
Installation
- Configurer l’Agent Datadog pour l’APM
- Installer le traceur
- Activer le traceur
- Visualiser vos données en temps réel
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 :
Définissez apm_non_local_traffic: true
dans la section apm_config
de votre fichier de configuration principal datadog.yaml
.
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é :
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.
- 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
.
Installer le traceur
Si vous recueillez des traces à partir d'une application Kubernetes ou d'une application exécutée sur un host ou conteneur Linux, plutôt que de suivre les instructions ci-dessous, vous pouvez injecter la bibliothèque de tracing dans votre application. Consultez la section
Injecter des bibliothèques localement pour obtenir des instructions.
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.
Pour installer le traceur .NET à l’échelle d’une machine, procédez comme suit :
Téléchargez le programme d’installation MSI pour le traceur .NET. Choisissez le programme d’installation correspondant à l’architecture de votre système (x64 ou x86).
Exécutez le programme d’installation MSI pour le traceur .NET avec des privilèges d’administrateur.
Vous pouvez également générer un script pour la configuration MSI en exécutant Start-Process -Wait msiexec -ArgumentList '/qn /i datadog-apm.msi'
dans PowerShell.
Pour installer le traceur .NET à l’échelle d’une machine, procédez comme suit :
Téléchargez le dernier package du traceur .NET compatible avec votre système d’exploitation et votre architecture.
Pour installer le package et créer le répertoire de logs /var/log/datadog/dotnet
du traceur .NET avec les autorisations adéquates, exécutez l’une des commandes suivantes :
- Debian ou Ubuntu
sudo dpkg -i ./datadog-dotnet-apm_<VERSION_TRACEUR>_amd64.deb && /opt/datadog/createLogPath.sh
- CentOS ou Fedora
sudo rpm -Uvh datadog-dotnet-apm<VERSION_TRACEUR>-1.x86_64.rpm && /opt/datadog/createLogPath.sh
- Alpine ou autre distribution basée sur musl
sudo tar -C /opt/datadog -xzf datadog-dotnet-apm-<VERSION_TRACEUR>-musl.tar.gz && sh /opt/datadog/createLogPath.sh
- Autres distributions
sudo tar -C /opt/datadog -xzf datadog-dotnet-apm<VERSION_TRACEUR>-tar.gz && /opt/datadog/createLogPath.sh
Remarque : cette installation n'instrumente pas les applications s'exécutant dans IIS. Pour ces applications, suivez le processus d'installation Windows à l'échelle d'une machine.
Pour installer le traceur .NET pour certaines applications, procédez comme suit :
- Ajoutez le package NuGet
Datadog.Trace.Bundle
à votre application.
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.
Le programme d’installation MSI pour le traceur .NET ajoute toutes les variables d’environnement requises. Vous n’avez donc pas besoin de configurer la moindre variable d’environnement.
Note: You must set the
.NET CLR version for the application pool to
No Managed Code as recommended by
Microsoft.
Pour instrumenter automatiquement des applications hébergées sur ISS, arrêtez complètement IIS, puis démarrez-le en exécutant les commandes suivantes en tant qu’administrateur :
net stop /y was
net start w3svc
# Also, start any other services that were stopped when WAS was shut down.
Note: Always use the commands above to completely stop and restart IIS to enable the tracer. Avoid using the IIS Manager GUI application or iisreset.exe
.
Services non hébergés sur IIS
Depuis la v2.14.0, vous n'avez pas besoin de définir CORECLR_PROFILER
si vous avez installé le traceur via le programme d'installation MSI.
Définissez les variables d’environnement requises suivantes pour activer l’instrumentation automatique de votre application :
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
Pour les applications autonomes et les services Windows, redémarrez manuellement l’application.
Définissez les variables d’environnement requises suivantes pour activer l’instrumentation automatique de votre application :
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
Pour les applications autonomes, redémarrez manuellement l’application, comme vous le feriez en temps normal.
Visualiser vos données en temps réel
Après avoir activé le traceur .NET pour votre service, procédez comme suit :
Redémarrez votre service.
Créez une charge d’application.
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.
Remarque : si vous utilisez à la fois l'instrumentation automatique et l'instrumentation personnalisée, vous devez faire en sorte que les versions des packages (par exemple, MSI et NuGet) soient synchronisées.
Pour utiliser l’instrumentation personnalisée dans votre application .NET :
- Ajoutez le package NuGet
Datadog.Trace
à votre application. - Dans le code de votre application, accédez au traceur global via la propriété
Datadog.Trace.Tracer.Instance
pour créer de nouvelles spans.
Remarque : si vous utilisez à la fois l'instrumentation automatique et l'instrumentation personnalisée, vous devez faire en sorte que les versions des packages (par exemple, MSI et NuGet) soient synchronisées.
Pour utiliser l’instrumentation personnalisée dans votre application .NET :
- Ajoutez le package NuGet
Datadog.Trace
à votre application. - Dans le code de votre application, accédez au traceur global via la propriété
Datadog.Trace.Tracer.Instance
pour créer de nouvelles spans.
Pour utiliser l’instrumentation personnalisée dans votre application .NET :
- Dans le code de votre application, accédez au traceur global via la propriété
Datadog.Trace.Tracer.Instance
pour créer de nouvelles spans.
Pour découvrir comment ajouter des spans et des tags pour l’instrumentation personnalisée, consultez la documentation relative à l’instrumentation personnalisée .NET.
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
Depuis la v2.14.0, vous n'avez pas besoin de définir CORECLR_PROFILER
si vous avez installé le traceur via le programme d'installation MSI.
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 :
- 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
- 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.
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
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>
Relancez le service .NET pour que les variables d’environnement soient appliquées.
systemctl
(tous les services)
Remarque : lorsque ces variables d'environnement sont définies, le runtime .NET tente de charger un profileur dans tous les processus .NET démarrés. Assurez-vous de limiter l'instrumentation aux applications devant être tracées. Ne définissez pas ces variables d'environnement globalement, au risque d'activer le chargement du profileur par tous les processus .NET sur le host.
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
.
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
Vérifiez que les variables d’environnement ont bien été définies en exécutant systemctl show-environment
.
Relancez le service .NET pour que les variables d’environnement soient appliquées.
Pour aller plus loin
Documentation, liens et articles supplémentaires utiles: