Tracer des applications .NET Framework

Exigences de compatibilité

Frameworks .NET pris en charge

Le traceur .NET prend en charge l’instrumentation sur .NET Framework 4.6.1 et ultérieur.

Pour obtenir la liste complète des bibliothèques et architectures de processeur .NET Framework 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

Pour configurer Datadog APM dans des environnements sans serveur, tels qu'AWS Lambda ou Azure Functions, voir Sans serveur.
Remarque : L'instrumentation automatique de Datadog repose sur l'API de profilage .NET CLR. Cette API ne permet qu'un seul abonné (par exemple, Datadog APM). Pour garantir une visibilité maximale, exécutez uniquement une solution APM dans votre environnement d'application.

Installation

Avant de commencer, vérifiez que vous avez bien installé et configuré l’Agent.

  1. Installez le SDK.
  2. Activez le SDK pour votre service.
  3. Consultez vos données en direct.

Installez le SDK

Après avoir installé et configuré votre agent Datadog, l’étape suivante consiste à ajouter le SDK directement dans l’application pour l’instrumenter. En savoir plus sur les informations de compatibilité.

Installez le traceur .NET de Datadog à l’échelle de la machine afin que tous les services sur la machine soient instrumentés ou sur une base par application, afin que les développeurs puissent gérer l’instrumentation via les dépendances de l’application. Pour voir les instructions d’installation à l’échelle de la machine, cliquez sur l’onglet Windows. Pour voir les instructions d’installation par application, cliquez sur l’onglet NuGet.

    Pour installer le traceur .NET à l’échelle de la machine, procédez comme suit :

    1. Téléchargez le .NET Tracer MSI installer. Utilisez l’installateur MSI x64 si vous exécutez Windows 64 bits ; cela peut instrumenter à la fois des applications 64 bits et 32 bits. Choisissez uniquement l’installateur x86 si vous exécutez Windows 32 bits. À partir de la version 3.0.0, seul l’installateur x64 est fourni, car nous ne supportons pas les systèmes d’exploitation 32 bits.

    2. Exécutez l’installateur MSI de .NET Tracer avec des privilèges d’administrateur.

    Vous pouvez également automatiser l’installation MSI en exécutant ce qui suit dans PowerShell : Start-Process -Wait msiexec -ArgumentList '/qn /i datadog-apm.msi'

    Remarque : Cette installation n'instrumente pas les applications exécutées dans IIS. Pour les applications exécutées dans IIS, suivez le processus d'installation à l'échelle de la machine Windows.

    Pour installer le traceur .NET pour certaines applications, procédez comme suit :

    1. Ajoutez le Datadog.Trace.Bundle NuGet package à votre application.

    Activez le SDK pour votre service

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

    Pour des informations sur les différentes méthodes de définition des variables d’environnement, consultez Configuration des variables d’environnement du processus.

      Services Internet (IIS)

      1. L’installateur MSI de .NET Tracer ajoute toutes les variables d’environnement requises. Il n’y a pas de variables d’environnement que vous devez configurer.

      2. Pour instrumenter automatiquement les applications hébergées dans IIS, arrêtez complètement et redémarrez IIS 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.
        Remarque : Utilisez toujours les commandes ci-dessus pour arrêter complètement et redémarrer IIS afin d'activer le SDK. Évitez d'utiliser l'application du Gestionnaire IIS avec l'interface graphique ou iisreset.exe.

      Services en dehors d’IIS

      Remarque : Le runtime .NET essaie de charger la bibliothèque .NET dans tout processus .NET qui est démarré avec ces variables d'environnement définies. Vous devez limiter l'instrumentation uniquement aux applications qui doivent être instrumentées. Ne définissez pas ces variables d'environnement globalement car cela entraîne que tous les processus .NET sur l'hôte soient instrumentés.

      1. Définissez les variables d’environnement requises suivantes pour que l’instrumentation automatique soit attachée à votre application :

        COR_ENABLE_PROFILING=1

      2. Pour les applications autonomes et les services Windows, redémarrez manuellement l’application.

      Suivez les instructions dans le fichier readme du package, également disponibles dans dd-trace-dotnet le dépôt. Des exemples Docker sont également disponibles dans le dépôt.

      Consultez vos données en direct

      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

      Si nécessaire, configurez le SDK pour envoyer des données de télémétrie de performance d’application, y compris la configuration du Tagging de Service Unifié. Lisez Configuration de la bibliothèque pour plus de détails.

      Instrumentation personnalisée

      L’instrumentation personnalisée dépend de votre instrumentation automatique et inclut des étapes supplémentaires selon la méthode :

        Remarque : À partir de la version 3.0.0, l'instrumentation personnalisée nécessite également l'utilisation de l'instrumentation automatique. Vous devez viser à maintenir les versions des packages d'instrumentation automatique et personnalisée (par exemple : MSI et NuGet) synchronisées, et vous assurer de ne pas mélanger les versions majeures des packages.

        Pour utiliser l’instrumentation personnalisée dans votre application .NET :

        1. Instrumentez votre application en utilisant l’instrumentation automatique.
        2. Ajoutez le Datadog.Trace NuGet package à votre application.
        3. Dans le code de votre application, accédez au traceur global via la propriété Datadog.Trace.Tracer.Instance pour créer de nouveaux spans.

        Pour utiliser l’instrumentation personnalisée dans votre application .NET :

        1. Dans le code de votre application, accédez au traceur global via la propriété Datadog.Trace.Tracer.Instance pour créer de nouveaux 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.

        Configuration des variables d’environnement du processus

        Pour attacher l’instrumentation automatique à votre service, définissez les variables d’environnement requises avant de démarrer l’application. Voir la section Activer le SDK pour votre service afin d’identifier les variables d’environnement à définir en fonction de votre méthode d’installation du Tracer .NET et suivez les exemples ci-dessous pour définir correctement les variables d’environnement en fonction de l’environnement de votre service instrumenté.

        Remarque : Le runtime .NET essaie de charger la bibliothèque .NET dans tout processus .NET qui est démarré avec ces variables d'environnement définies. Vous devez limiter l'instrumentation uniquement aux applications qui doivent être instrumentées. Ne définissez pas ces variables d'environnement globalement car cela entraîne que tous les processus .NET sur l'hôte soient instrumentés.

        Services Windows

          Dans l’Éditeur du Registre, créez une valeur multi-chaîne appelée Environment dans la clé HKLM\System\CurrentControlSet\Services\<SERVICE NAME> et définissez les données de valeur sur :

          COR_ENABLE_PROFILING=1
          Utilisation de l'Éditeur du Registre pour créer des variables d'environnement pour un service Windows
          Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\<SERVICE NAME> -Name Environment -Value 'COR_ENABLE_PROFILING=1'

          IIS

          Après l’installation du MSI, aucune configuration supplémentaire n’est nécessaire pour instrumenter automatiquement vos sites IIS. Pour définir des variables d’environnement supplémentaires qui sont héritées par tous les sites IIS, effectuez les étapes suivantes :

          1. Ouvrez l’Éditeur du Registre, trouvez la valeur multi-chaîne appelée Environment dans la clé HKLM\System\CurrentControlSet\Services\WAS et ajoutez les variables d’environnement, une par ligne. Par exemple, pour ajouter l’injection de journaux et les métriques d’exécution, ajoutez 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.
          Utilisation de l'Éditeur du Registre pour créer des variables d'environnement pour tous les sites IIS

          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 Set required environment variables
SET COR_ENABLE_PROFILING=1

rem (Optionally) Set additional Datadog environment variables, for example:
SET DD_LOGS_INJECTION=true
SET DD_RUNTIME_METRICS_ENABLED=true

rem Start application
dotnet.exe example.dll

          Lectures complémentaires

          Documentation, liens et articles supplémentaires utiles:

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