Instrumentation APM en une étape sur Windows

Présentation

Grâce à l’instrumentation en une étape (SSI), vous pouvez activer APM pour vos applications Java et .NET sur des VM Windows à l’aide d’une seule commande d’installation du Datadog Agent.

Configurer APM avec un agent

Install the dd-apm skill in your AI coding agent for guided APM setup.
npx skills add https://github.com/datadog-labs/agent-skills --skill dd-apm --full-depth -y

Activer APM sur Windows

Avant de continuer, confirmez que votre environnement est compatible en consultant le guide de compatibilité SSI.

Installation d’un nouveau Datadog Agent

Si vous n’avez pas encore installé le Datadog Agent, suivez ces étapes pour installer l’Agent et activer la SSI simultanément.

Vous pouvez activer APM sur Windows de l’une des manières suivantes :

  • Instrumenter uniquement les applications .NET sur IIS
  • Instrumenter toutes les applications Java et .NET sur l’ensemble de votre host Windows

    Pour instrumenter uniquement les applications .NET exécutées sur IIS :

    1. Depuis une session PowerShell administrateur sur votre host Windows, exécutez l’une des commandes suivantes. Remplacez <YOUR_DD_API_KEY> par votre clé d’API Datadog.

      Utilisez le programme d’installation PowerShell :

      [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; $env:DD_API_KEY = '<YOUR_DD_API_KEY>'; $env:DD_SITE = '<span class="js-region-param region-param" data-region-param="dd_site"></span>'; $env:DD_APM_INSTRUMENTATION_ENABLED = 'iis'; $env:DD_APM_INSTRUMENTATION_LIBRARIES = 'dotnet:3'; (New-Object System.Net.WebClient).DownloadFile('https://install.datadoghq.com/datadog-installer-x86_64.exe', 'C:\\Windows\\SystemTemp\\datadog-installer-x86_64.exe'); C:\\Windows\\SystemTemp\\datadog-installer-x86_64.exe

      Alternatively, install with the MSI:

      $p = Start-Process -Wait -PassThru msiexec -ArgumentList '/qn /norestart /i "https://windows-agent.datadoghq.com/datadog-agent-7-latest.amd64.msi" /log C:\Windows\SystemTemp\install-datadog.log APIKEY="<YOUR_DD_API_KEY>" SITE="<span class="js-region-param region-param" data-region-param="dd_site"></span>\" DD_APM_INSTRUMENTATION_ENABLED=\"iis\" DD_APM_INSTRUMENTATION_LIBRARIES=\"dotnet:3\"'
if ($p.ExitCode -ne 0) { Write-Host \"msiexec failed with exit code $($p.ExitCode) please check the logs at C:\\Windows\\SystemTemp\\install-datadog.log\" -ForegroundColor Red }

      To install a different .NET version, change dotnet:3, or omit DD_APM_INSTRUMENTATION_LIBRARIES to install the latest.

      Note: The Chocolatey installation method does not preserve the SSI settings and cannot be used to enable SSI.

    2. Restart the IIS applications you want instrumented. (You do not need to restart the entire IIS server.)

    The Agent then automatically loads the Datadog .NET SDK into supported application processes to enable distributed tracing.

    Generate the command from Datadog: To get a command pre-filled with your API key and site, go to Install the Datadog Agent on Windows and, in the Customize your observability coverage section, toggle Application Performance Monitoring (APM). To pin the .NET SDK version, select Customize Library Versions under Instrumentation Configuration. Then copy and run the generated command.

    Rejoignez l'aperçu !
    L'instrumentation à l'échelle du host pour Windows est en aperçu et limitée aux participants à l'aperçu. Les options d'installation et de configuration décrites dans cet onglet n'apparaissent dans Datadog qu'une fois votre inscription effectuée. Demandez l'accès pour rejoindre l'aperçu.

    Pour instrumenter des applications Java et .NET sur l’ensemble de votre host Windows :

    1. Dans Datadog, accédez à Installer le Datadog Agent sur Windows.

    2. Dans la section Customize your observability coverage, activez Application Performance Monitoring (APM).

    3. (Facultatif) Définissez votre version de SDK :

      Par défaut, l’instrumentation en une étape installe la dernière version prise en charge des SDK Datadog .NET et Java. Si vous devez fixer une version spécifique :

      1. Sous Instrumentation Configuration, sélectionnez Customize Library Versions.
      2. Sous .NET, choisissez la version que vous souhaitez utiliser.

    4. Copiez et exécutez la commande d’installation fournie sur votre host Windows. Datadog génère cette commande dans l’application une fois que vous êtes inscrit à l’aperçu.

    5. Configurez les règles d’instrumentation.

      Le SSI au niveau du host instrumente automatiquement toutes les applications Java sur le host et toutes les applications .NET exécutées dans IIS. Pour instrumenter les applications .NET exécutées en dehors d’IIS, vous devez définir une règle d’instrumentation qui les autorise. Vous pouvez également utiliser des règles d’instrumentation pour un contrôle granulaire sur les applications Java sur le host ou les applications .NET dans IIS qui sont instrumentées.

    6. Redémarrez les services que vous souhaitez instrumenter.

    Le SSI ajoute un léger délai de démarrage aux applications instrumentées. Si ce surcoût n'est pas acceptable pour votre cas d'utilisation, contactez Datadog Support.

    Installation d’un Datadog Agent existant

    Si vous avez déjà un Datadog Agent installé, utilisez Fleet Automation pour activer le SSI.

    1. Dans Datadog, accédez à Fleet Automation > Configuration.

    2. Cliquez sur Configure Agents.

    3. Appliquez des filtres pour sélectionner les agents que vous souhaitez configurer, puis cliquez sur Suivant.

      L'écran de filtrage des agents dans Fleet Automation, avec des options pour définir le périmètre par environnement, système d'exploitation et nom de host

    4. Cliquez sur la tuile Application Performance Monitoring (APM), puis cliquez sur Next.

      L'écran de sélection de produit dans Fleet Automation, affichant la tuile Application Performance Monitoring (APM)

    5. Dans l’écran Configure SDKs Installation, cliquez sur Yes pour installer automatiquement les SDK. Sélectionnez Use latest version, ou décochez pour spécifier des versions individuelles du SDK.

      L'écran de configuration de l'installation des SDK dans Fleet Automation, avec des options pour activer l'installation automatique des SDK et sélectionner les versions

    6. Cliquez sur Next.

    7. Vérifiez votre configuration et cliquez sur Deploy Configuration.

    8. Configurez les règles d’instrumentation.

      Le SSI au niveau du host instrumente automatiquement toutes les applications Java sur le host et toutes les applications .NET exécutées dans IIS. Pour instrumenter les applications .NET exécutées en dehors d’IIS, vous devez définir une règle d’instrumentation qui les autorise. Vous pouvez également utiliser des règles d’instrumentation pour un contrôle granulaire sur les applications Java sur le host ou les applications .NET dans IIS qui sont instrumentées.

    Vérifiez l’installation

    1. Depuis une session PowerShell administrateur, confirmez que l’Agent est sain et que l’Agent APM est en cours d’exécution :

      & "$env:ProgramFiles\Datadog\Datadog Agent\bin\agent.exe" status

      Vérifiez la section APM Agent de la sortie.

    2. Une fois que vos applications instrumentées reçoivent du trafic, confirmez que vos services apparaissent sur la APM Services page. S’ils n’apparaissent pas en quelques minutes, suivez le guide de dépannage SSI.

    Configurez les tags de service unifiés

    Les Unified Service Tags (USTs) appliquent des tags cohérents aux traces, aux métriques et aux logs, facilitant ainsi la navigation et la corrélation de vos données d’observabilité. Découvrez comment définir des UST pour les services Windows.

    Activer les produits et fonctionnalités dépendants du SDK

    Une fois que SSI a chargé le SDK Datadog dans vos applications et activé le traçage distribué, vous pouvez configurer des produits supplémentaires qui dépendent du SDK :

    ProductEnvironment variable
    Runtime MetricsDD_RUNTIME_METRICS_ENABLED
    Log InjectionDD_LOGS_INJECTION
    Continuous ProfilerDD_PROFILING_ENABLED
    Data Streams MonitoringDD_DATA_STREAMS_ENABLED
    App and API ProtectionDD_APPSEC_ENABLED
    Runtime Code Analysis (IAST)DD_IAST_ENABLED
    Dynamic InstrumentationDD_DYNAMIC_INSTRUMENTATION_ENABLED
    Data Jobs MonitoringDD_DATA_JOBS_ENABLED
    Software Composition AnalysisDD_APPSEC_SCA_ENABLED

    Note: All variables accept true or false. DD_PROFILING_ENABLED also accepts auto, which profiles only eligible processes and is recommended for SSI.

    Pour activer des produits, définissez des variables d’environnement dans la configuration de votre application.

    Options avancées

    Définir des règles d’instrumentation

    Les règles d'instrumentation ne sont pas prises en charge pour le site Datadog sélectionné ().

    Les règles d'instrumentation (disponibles pour l'Agent v7.73+) s'appliquent uniquement à l'instrumentation à l'échelle du host. Elles ne sont pas prises en charge pour une installation IIS uniquement.

    Les règles d’instrumentation vous permettent de contrôler quels processus sont automatiquement instrumentés par SSI sur les hosts Windows. Des règles sont requises pour instrumenter les applications .NET s’exécutant en dehors d’IIS. Elles sont également utiles pour un contrôle granulaire des applications Java sur le host ou des applications .NET dans IIS qui sont instrumentées.

    Remarque : Vous pouvez utiliser Bits AI pour créer des règles d’instrumentation en langage naturel. Décrivez les processus que vous souhaitez instrumenter, et Bits AI génère la règle correspondante.

    Pour configurer les règles d’instrumentation :

    1. Dans Datadog, accédez à APM > Service Setup > Manage Instrumentation Rules.

    2. Cliquez sur Add or Edit Rules.

    3. Définissez les règles d’instrumentation :

      1. Cliquez sur Add New Rule, puis choisissez Allow Rule ou Block Rule pour spécifier si les processus correspondants doivent être instrumentés.
      2. Nommez votre règle.
      3. Ajoutez une ou plusieurs conditions. Consultez Définir les conditions de règle pour en savoir plus.
      L'interface utilisateur des règles d'instrumentation, affichant les options de configuration pour définir une règle

    4. (Facultatif) Faites glisser et déposez les règles pour les réorganiser.

      Remarque : Les règles sont évaluées dans l’ordre. Une fois qu’un processus correspond à une règle, les règles suivantes sont ignorées.

    5. Définissez le comportement par défaut (autoriser ou bloquer) pour les processus qui ne correspondent à aucune règle.

    6. Cliquez sur Next pour prévisualiser vos règles.

    7. Cliquez sur Deploy Rules.

    Si Remote Configuration est activé, les règles sont déployées sur chaque host et appliquées sur ceux pour lesquels SSI est activé dans un délai de 50 secondes. Sinon, cliquez sur Export pour exporter le fichier de configuration et l’appliquer manuellement à vos hosts.

    Définir les conditions de règle

    Chaque règle se compose d’une ou plusieurs conditions. Une condition comprend les éléments suivants :

    • Attribute : La propriété de processus que la règle évalue.
    • Operator : La logique de comparaison (equals, not equals, prefix ou contains).
    • Value : Le texte ou le motif à faire correspondre, tel qu’un nom de processus ou un indicateur de ligne de commande.

    Les attributs pris en charge incluent :

    AttributDescriptionExemple
    Système d’exploitationOS du host.windows
    ExécutableNom de l’exécutable du processus.w3wp.exe
    Chemin complet de l’exécutableChemin complet de l’exécutable.C:\Windows\System32\inetsrv\w3wp.exe
    ArgumentsArguments de ligne de commande utilisés pour démarrer le processus.--env=production
    Répertoire de travailRépertoire de travail du processus.C:\inetpub\wwwroot
    LangageLangage de programmation détecté pour le processus.dotnet
    Fichier de point d’entréeLe fichier spécifique utilisé pour lancer l’application.MyService.dll, app.py
    Pool d’applications IISLe pool d’applications IIS hébergeant le processus de travail. Comme tous les processus de travail IIS partagent l’exécutable w3wp.exe, c’est le moyen le plus fiable de cibler une application .NET spécifique sur IIS.DefaultAppPool, MyWebApp

    Exemples de cas d’utilisation

    Examinez les exemples suivants illustrant comment appliquer des règles d’instrumentation :

    Instrumenter tous les processus par défaut. Ajoutez des règles de blocage pour exclure les services qui ajouteraient du bruit sans valeur ajoutée, tels que les jobs cron d'analyse et les processeurs de lots Java.
    Deux règles d'instrumentation de blocage ciblant les conditions Répertoire de travail et Fichier de point d'entrée, avec une autorisation d'instrumentation par défaut
    Bloquer toute instrumentation par défaut. Ajoutez des règles d'autorisation pour inclure des applications IIS spécifiques dans APM. Comme tous les processus de travail IIS partagent le w3wp.exe exécutable, utilisez IIS Application Pool pour identifier les applications cibles. Cette approche est utile pour les déploiements progressifs.
    Deux règles d'autorisation d'instrumentation ciblent des pools d'applications IIS spécifiques par nom, avec le blocage de l'instrumentation par défaut.

    Supprimez l’instrumentation APM en une étape de votre Datadog Agent

    Pour désactiver SSI pour .NET sur votre host, exécutez :

    &"C:\Program Files\Datadog\Datadog Agent\bin\datadog-installer.exe" remove datadog-apm-library-dotnet

    Dépannage

    Si vous rencontrez des problèmes lors de l’activation de APM avec SSI, consultez le guide de dépannage SSI.

    Pour aller plus loin

    Documentation, liens et articles supplémentaires utiles:

    Activer les métriques d'exécutionDOCUMENTATION more more