Surveiller les applications .NET et Node.js avec Application Insights (API classique)

Note

Passez en revue les conseils de prise en charge du Kit de développement logiciel (SDK) Application Insights pour notre stratégie de prise en charge du SDK d’API classique.

Caution

Nous recommandons la distribution OpenTelemetry d'Azure Monitor pour les nouvelles applications ou clients afin d'alimenter Azure Monitor Application Insights. La distribution OpenTelemetry Azure Monitor offre une fonctionnalité et une expérience similaires à celles du Kit de développement logiciel (SDK) Application Insights. Il est possible de migrer à partir du SDK Application Insights à l'aide des guides de migration pour .NET, Node.js et Python, mais nous travaillons toujours à ajouter une few more features pour la compatibilité descendante.

Cet article explique comment activer et configurer Application Insights pour les applications .NET (ASP.NET, ASP.NET Core et Worker Service) et Node.js. Application Insights peut collecter les données de télémétrie suivantes depuis vos applications :

• Demandes
• Dépendances
• Exceptions
• Compteurs de performance
• Traces (journaux d’activité)
• Pulsations
• Événements personnalisés et métriques (nécessite une instrumentation manuelle)
• Affichages de pages (nécessite le Kit de développement logiciel (SDK) JavaScript pour les pages web)
• Tests de disponibilité (nécessitent la configuration manuelle des tests de disponibilité)

Scénarios pris en charge

.NET

Soutenu	ASP.NET	ASP.NET Core	Service Worker
Système d’exploitation	Windows	Windows, Linux ou macOS	Windows, Linux ou macOS
Méthode d’hébergement	In-process (IIS ou IIS Express)	En cours ou en dehors du processus	Service console ou en arrière-plan (s’exécute en tant que processus, généralement via dotnet CLI ou en tant que démon Windows Service/Linux)
Méthode de déploiement	Web Deploy, MSI ou copie manuelle de fichiers	Framework dépendant ou autonome	Framework dépendant ou autonome
Serveur web	Internet Information Services (IIS)	Internet Information Server (IIS) ou Kestrel	Non applicable (aucun serveur web ; conçu pour les charges de travail non HTTP telles que la messagerie, les tâches en arrière-plan et les applications console)
Plateforme d’hébergement	Azure App Service (Windows), les serveurs Azure Virtual Machines ou locaux	Fonctionnalité Web Apps de Azure App Service, Azure Virtual Machines, Docker et Azure Kubernetes Service (AKS)	Azure Virtual Machines, Azure Kubernetes Service (AKS), conteneurs ou tout environnement dans lequel .NET Core est pris en charge
version .NET	.NET Framework 4.6.1 et versions ultérieures	Toutes les versions .NET officiellement prises en charge qui ne sont pas en version bêta.	Toutes les versions .NET officiellement prises en charge qui ne sont pas en version bêta.

Le Kit de développement logiciel (SDK) du service Worker n’effectue pas de collecte de données de télémétrie par lui-même. Au lieu de cela, il apporte d’autres collecteurs automatiques Application Insights connus comme DependencyCollector, PerfCounterCollector et ApplicationInsightsLoggingProvider. Cet SDK expose des méthodes d'extension sur IServiceCollection pour activer et configurer la collecte de données de télémétrie.

Note

Un service worker est une application en arrière-plan longue durée qui exécute des tâches en dehors d’un pipeline de requête/réponse HTTP. Le SDK Application Insights pour Worker Service peut être utilisé dans le nouveau .NET Core Worker Service, les tâches d’arrière-plan dans ASP.NET Core et les applications console telles que .NET Core et .NET Framework.

Node.js

Soutenu	Node.js
Système d’exploitation	Windows, Linux ou macOS
Méthode d’hébergement	Service console ou en arrière-plan (s’exécute en tant que processus par le biais de scripts npm ou de commandes de nœud)
Méthode de déploiement	Dépendant de l’infrastructure (nécessite Node.js runtime installé via le package npm)
Serveur web	Modules HTTP intégrés ou frameworks web (Express, Fastify, etc.) ou non applicables aux charges de travail non HTTP
Plateforme d’hébergement	Azure App Service, Azure Virtual Machines, Azure Kubernetes Service (AKS), Docker, local ou tout environnement dans lequel Node.js est pris en charge
Version Node.js	Toutes les versions LTS de Node.js officiellement prises en charge (actuellement, 18.19.0+ ou 20.6.0+ pour le SDK 3.X)

La bibliothèque de client Node.js peut automatiquement analyser les requêtes HTTP entrantes et sortantes, les exceptions et certaines métriques du système. À partir de la version 0.20, la bibliothèque de client peut également analyser certains packages tiers courants, comme MongoDB, MySQL et Redis.

Tous les événements liés à une demande HTTP entrante sont mis en corrélation pour une résolution des problèmes plus rapide.

Vous pouvez utiliser l’API TelemetryClient pour instrumenter et surveiller manuellement des aspects supplémentaires de votre application et de votre système. L’API TelemetryClient est décrite plus en détail plus loin dans cet article.

Ajouter Application Insights

.NET

Dans cette section

• Conditions préalables
• Instrumenter votre application avec le Kit de développement logiciel (SDK) Application Insights
• Déployer l’agent Application Insights

Conditions préalables

• Un abonnement Azure. Si vous n'en avez pas encore, créez un compte Azure gratuit.
• Ressource basée sur un espace de travail Application Insights.
• Application fonctionnelle.

Instrumenter votre application avec le Kit de développement logiciel (SDK) Application Insights

Cette section vous guide tout au long de l’ajout d’Application Insights à une application web basée sur des modèles.

ASP.NET

1. Ajoutez les packages NuGet suivants et leurs dépendances à votre projet :

   • Microsoft.ApplicationInsights.WindowsServer
   • Microsoft.ApplicationInsights.Web
   • Microsoft.AspNet.TelemetryCorrelation

2. Dans certains cas, le fichier ApplicationInsights.config est automatiquement créé pour vous. Si le fichier est déjà présent, passez à l’étape no 4.

   Créez-le vous-même s’il manque. Dans le répertoire racine d’une application ASP.NET, créez un fichier appelé ApplicationInsights.config.

3. Copiez la configuration XML suivante dans le fichier que vous venez de créer :

   
   
   Développer pour afficher la configuration

   <?xml version="1.0" encoding="utf-8"?>
   <ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
     <TelemetryInitializers>
       <Add Type="Microsoft.ApplicationInsights.DependencyCollector.HttpDependenciesParsingTelemetryInitializer, Microsoft.AI.DependencyCollector" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.AzureRoleEnvironmentTelemetryInitializer, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.BuildInfoConfigComponentVersionTelemetryInitializer, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.Web.WebTestTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.SyntheticUserAgentTelemetryInitializer, Microsoft.AI.Web">
         <!-- Extended list of bots:
               search|spider|crawl|Bot|Monitor|BrowserMob|BingPreview|PagePeeker|WebThumb|URL2PNG|ZooShot|GomezA|Google SketchUp|Read Later|KTXN|KHTE|Keynote|Pingdom|AlwaysOn|zao|borg|oegp|silk|Xenu|zeal|NING|htdig|lycos|slurp|teoma|voila|yahoo|Sogou|CiBra|Nutch|Java|JNLP|Daumoa|Genieo|ichiro|larbin|pompos|Scrapy|snappy|speedy|vortex|favicon|indexer|Riddler|scooter|scraper|scrubby|WhatWeb|WinHTTP|voyager|archiver|Icarus6j|mogimogi|Netvibes|altavista|charlotte|findlinks|Retreiver|TLSProber|WordPress|wsr-agent|http client|Python-urllib|AppEngine-Google|semanticdiscovery|facebookexternalhit|web/snippet|Google-HTTP-Java-Client-->
         <Filters>search|spider|crawl|Bot|Monitor|AlwaysOn</Filters>
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Web.ClientIpHeaderTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AzureAppServiceRoleNameFromHostNameHeaderInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.OperationNameTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.OperationCorrelationTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.UserTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AuthenticatedUserIdTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AccountIdTelemetryInitializer, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.SessionTelemetryInitializer, Microsoft.AI.Web" />
     </TelemetryInitializers>
     <TelemetryModules>
       <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
         <ExcludeComponentCorrelationHttpHeadersOnDomains>
           <!-- 
           Requests to the following hostnames will not be modified by adding correlation headers.
           Add entries here to exclude additional hostnames.
           NOTE: this configuration will be lost upon NuGet upgrade.
           -->
           <Add>core.windows.net</Add>
           <Add>core.chinacloudapi.cn</Add>
           <Add>core.cloudapi.de</Add>
           <Add>core.usgovcloudapi.net</Add>
         </ExcludeComponentCorrelationHttpHeadersOnDomains>
         <IncludeDiagnosticSourceActivities>
           <Add>Microsoft.Azure.EventHubs</Add>
           <Add>Azure.Messaging.ServiceBus</Add>
         </IncludeDiagnosticSourceActivities>
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector">
         <!--
         Use the following syntax here to collect additional performance counters:
   
         <Counters>
           <Add PerformanceCounter="\Process(??APP_WIN32_PROC??)\Handle Count" ReportAs="Process handle count" />
           ...
         </Counters>
   
         PerformanceCounter must be either \CategoryName(InstanceName)\CounterName or \CategoryName\CounterName
   
         NOTE: performance counters configuration will be lost upon NuGet upgrade.
   
         The following placeholders are supported as InstanceName:
           ??APP_WIN32_PROC?? - instance name of the application process for Win32 counters.
           ??APP_W3SVC_PROC?? - instance name of the application IIS worker process for IIS/ASP.NET counters.
           ??APP_CLR_PROC?? - instance name of the application CLR process for .NET counters.
         -->
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse.QuickPulseTelemetryModule, Microsoft.AI.PerfCounterCollector" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.AppServicesHeartbeatTelemetryModule, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.AzureInstanceMetadataTelemetryModule, Microsoft.AI.WindowsServer">
         <!--
         Remove individual fields collected here by adding them to the ApplicationInsighs.HeartbeatProvider
         with the following syntax:
   
         <Add Type="Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule, Microsoft.ApplicationInsights">
           <ExcludedHeartbeatProperties>
             <Add>osType</Add>
             <Add>location</Add>
             <Add>name</Add>
             <Add>offer</Add>
             <Add>platformFaultDomain</Add>
             <Add>platformUpdateDomain</Add>
             <Add>publisher</Add>
             <Add>sku</Add>
             <Add>version</Add>
             <Add>vmId</Add>
             <Add>vmSize</Add>
             <Add>subscriptionId</Add>
             <Add>resourceGroupName</Add>
             <Add>placementGroupId</Add>
             <Add>tags</Add>
             <Add>vmScaleSetName</Add>
           </ExcludedHeartbeatProperties>
         </Add>
   
         NOTE: exclusions will be lost upon upgrade.
         -->
       </Add>
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule, Microsoft.AI.WindowsServer" />
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule, Microsoft.AI.WindowsServer">
         <!--</Add>
       <Add Type="Microsoft.ApplicationInsights.WindowsServer.FirstChanceExceptionStatisticsTelemetryModule, Microsoft.AI.WindowsServer">-->
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule, Microsoft.AI.Web">
         <Handlers>
           <!-- 
           Add entries here to filter out additional handlers:
   
           NOTE: handler configuration will be lost upon NuGet upgrade.
           -->
           <Add>Microsoft.VisualStudio.Web.PageInspector.Runtime.Tracing.RequestDataHttpHandler</Add>
           <Add>System.Web.StaticFileHandler</Add>
           <Add>System.Web.Handlers.AssemblyResourceLoader</Add>
           <Add>System.Web.Optimization.BundleHandler</Add>
           <Add>System.Web.Script.Services.ScriptHandlerFactory</Add>
           <Add>System.Web.Handlers.TraceHandler</Add>
           <Add>System.Web.Services.Discovery.DiscoveryRequestHandler</Add>
           <Add>System.Web.HttpDebugHandler</Add>
         </Handlers>
       </Add>
       <Add Type="Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule, Microsoft.AI.Web" />
       <Add Type="Microsoft.ApplicationInsights.Web.AspNetDiagnosticTelemetryModule, Microsoft.AI.Web" />
     </TelemetryModules>
     <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
     <TelemetrySinks>
       <Add Name="default">
         <TelemetryProcessors>
           <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse.QuickPulseTelemetryProcessor, Microsoft.AI.PerfCounterCollector" />
           <Add Type="Microsoft.ApplicationInsights.Extensibility.AutocollectedMetricsExtractor, Microsoft.ApplicationInsights" />
           <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
             <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
             <ExcludedTypes>Event</ExcludedTypes>
           </Add>
           <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
             <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
             <IncludedTypes>Event</IncludedTypes>
           </Add>
           <!--
             Adjust the include and exclude examples to specify the desired semicolon-delimited types. (Dependency, Event, Exception, PageView, Request, Trace)
           -->
         </TelemetryProcessors>
         <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel" />
       </Add>
     </TelemetrySinks>
     <!-- 
       Learn more about Application Insights configuration with ApplicationInsights.config here:
       http://go.microsoft.com/fwlink/?LinkID=513840
     -->
     <ConnectionString>Copy the connection string from your Application Insights resource</ConnectionString>
   </ApplicationInsights>
   

4. Ajoutez la connection string, qui peut être effectuée de deux manières :

   • (Recommandé) Définissez la connection string dans la configuration.

     Avant la balise </ApplicationInsights> fermante dans ApplicationInsights.config, ajoutez une ligne contenant la chaîne de connexion pour votre ressource Application Insights. Vous trouverez votre connection string dans le volet vue d’ensemble de la ressource Application Insights nouvellement créée.

     <ConnectionString>Copy the connection string from your Application Insights resource</ConnectionString>
     

   • Définissez la connection string dans le code.

     Fournissez un connection string dans votre classe program.cs.

     var configuration = new TelemetryConfiguration
     {
         ConnectionString = "Copy the connection string from your Application Insights resource"
     };
     

5. Au même niveau dans votre projet que le fichier ApplicationInsights.config, créez un dossier appelé ErrorHandler avec un nouveau fichier C# appelé AiHandleErrorAttribute.cs. Le contenu du fichier ressemble à ceci :

   using System;
   using System.Web.Mvc;
   using Microsoft.ApplicationInsights;
   
   namespace WebApplication10.ErrorHandler //namespace will vary based on your project name
   {
       [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)] 
       public class AiHandleErrorAttribute : HandleErrorAttribute
       {
           public override void OnException(ExceptionContext filterContext)
           {
               if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
               {
                   //If customError is Off, then AI HTTPModule will report the exception
                   if (filterContext.HttpContext.IsCustomErrorEnabled)
                   {   
                       var ai = new TelemetryClient();
                       ai.TrackException(filterContext.Exception);
                   } 
               }
               base.OnException(filterContext);
           }
       }
   }
   

6. Dans le dossier App_Start, ouvrez le fichier FilterConfig.cs et modifiez-le pour qu’il corresponde à l’exemple :

   using System.Web;
   using System.Web.Mvc;
   
   namespace WebApplication10 //Namespace will vary based on project name
   {
       public class FilterConfig
       {
           public static void RegisterGlobalFilters(GlobalFilterCollection filters)
           {
               filters.Add(new ErrorHandler.AiHandleErrorAttribute());
           }
       }
   }
   

7. Si Web.config est déjà mis à jour, ignorez cette étape. Sinon, mettez le fichier à jour comme suit :

   
   
   Développer pour afficher la configuration

   <?xml version="1.0" encoding="utf-8"?>
   <!--
     For more information on how to configure your ASP.NET application, please visit
     https://go.microsoft.com/fwlink/?LinkId=301880
     -->
   <configuration>
     <appSettings>
       <add key="webpages:Version" value="3.0.0.0" />
       <add key="webpages:Enabled" value="false" />
       <add key="ClientValidationEnabled" value="true" />
       <add key="UnobtrusiveJavaScriptEnabled" value="true" />
     </appSettings>
     <system.web>
       <compilation debug="true" targetFramework="4.7.2" />
       <httpRuntime targetFramework="4.7.2" />
       <!-- Code added for Application Insights start -->
       <httpModules>
         <add name="TelemetryCorrelationHttpModule" type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation" />
         <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" />
       </httpModules>
       <!-- Code added for Application Insights end -->
     </system.web>
     <runtime>
       <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
         <dependentAssembly>
           <assemblyIdentity name="Antlr3.Runtime" publicKeyToken="eb42632606e9261f" />
           <bindingRedirect oldVersion="0.0.0.0-3.5.0.2" newVersion="3.5.0.2" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" />
           <bindingRedirect oldVersion="0.0.0.0-12.0.0.0" newVersion="12.0.0.0" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="System.Web.Optimization" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="1.0.0.0-1.1.0.0" newVersion="1.1.0.0" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="WebGrease" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="0.0.0.0-1.6.5135.21930" newVersion="1.6.5135.21930" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="System.Web.Helpers" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="System.Web.WebPages" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="1.0.0.0-3.0.0.0" newVersion="3.0.0.0" />
         </dependentAssembly>
         <dependentAssembly>
           <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35" />
           <bindingRedirect oldVersion="1.0.0.0-5.2.7.0" newVersion="5.2.7.0" />
         </dependentAssembly>
         <!-- Code added for Application Insights start -->
         <dependentAssembly>
           <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
           <bindingRedirect oldVersion="0.0.0.0-4.0.1.1" newVersion="4.0.1.1" />
         </dependentAssembly>
         <!-- Code added for Application Insights end -->
       </assemblyBinding>
     </runtime>
     <system.codedom>
       <compilers>
         <compiler language="c#;cs;csharp" extension=".cs" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.CSharpCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=2.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:default /nowarn:1659;1699;1701" />
         <compiler language="vb;vbs;visualbasic;vbscript" extension=".vb" type="Microsoft.CodeDom.Providers.DotNetCompilerPlatform.VBCodeProvider, Microsoft.CodeDom.Providers.DotNetCompilerPlatform, Version=2.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" warningLevel="4" compilerOptions="/langversion:default /nowarn:41008 /define:_MYTYPE=\&quot;Web\&quot; /optionInfer+" />
       </compilers>
     </system.codedom>
     <system.webServer>
       <validation validateIntegratedModeConfiguration="false" />
       <!-- Code added for Application Insights start -->
       <modules>
         <remove name="TelemetryCorrelationHttpModule" />
         <add name="TelemetryCorrelationHttpModule" type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule, Microsoft.AspNet.TelemetryCorrelation" preCondition="managedHandler" />
         <remove name="ApplicationInsightsWebTracking" />
         <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" preCondition="managedHandler" />
       </modules>
       <!-- Code added for Application Insights end -->
     </system.webServer>
   </configuration>
   

À ce stade, vous avez correctement configuré la surveillance des applications côté serveur. Si vous exécutez votre application web, vous voyez la télémétrie commencer à apparaître dans Application Insights.

ASP.NET Core

1. Installez le package NuGet du SDK Application Insights pour ASP.NET Core.

   Nous vous recommandons de toujours utiliser la dernière version stable. Recherchez les notes de publication complètes du Kit de développement logiciel (SDK) sur le dépôt GitHub open source.

   L’exemple de code suivant montre les modifications à ajouter au fichier .csproj de votre projet :

   <ItemGroup>
       <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
   </ItemGroup>
   

2. Ajoutez AddApplicationInsightsTelemetry() à votre classe program.cs.

   Ajoutez builder.Services.AddApplicationInsightsTelemetry(); après la méthode WebApplication.CreateBuilder(), comme dans cet exemple :

   // This method gets called by the runtime. Use this method to add services to the container.
   var builder = WebApplication.CreateBuilder(args);
   
   // The following line enables Application Insights telemetry collection.
   builder.Services.AddApplicationInsightsTelemetry();
   
   // This code adds other services for your application.
   builder.Services.AddMvc();
   
   var app = builder.Build();
   

3. Ajoutez la connection string, qui peut être effectuée de trois façons :

   • (Recommandé) Définissez la connection string dans la configuration.

     Définissez le connection string dans appsettings.json et vérifiez que le fichier de configuration est copié dans le dossier racine de l’application pendant la publication.

     {
         "Logging": {
             "LogLevel": {
                 "Default": "Information",
                 "Microsoft.AspNetCore": "Warning"
             }
         },
         "AllowedHosts": "*",
         "ApplicationInsights": {
             "ConnectionString": "<YOUR-CONNECTION-STRING>"
         }
     }
     

   • Définissez la connection string dans la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING ou ApplicationInsights:ConnectionString dans le fichier de configuration JSON.

     Par exemple:

     • SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
     • SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
     • APPLICATIONINSIGHTS_CONNECTION_STRING est généralement utilisé dans les applications web. Vous pouvez également l’utiliser partout où ce SDK est pris en charge.

     Note

     Une connection string spécifiée dans le code gagne sur la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING, qui gagne sur d’autres options.

   • Définissez la connection string dans le code.

     Fournissez une chaîne de connexion en tant que partie de l'argument ApplicationInsightsServiceOptions pour AddApplicationInsightsTelemetry dans votre classe Program.cs.

Secrets d’utilisateur et autres fournisseurs de configuration

Si vous souhaitez stocker la chaîne de connexion dans les secrets utilisateur d’ASP.NET Core ou la récupérer depuis un autre fournisseur de configuration, vous pouvez utiliser la surcapacité avec un paramètre Microsoft.Extensions.Configuration.IConfiguration. services.AddApplicationInsightsTelemetry(Configuration); est un exemple de paramètre.

Dans Microsoft.ApplicationInsights.AspNetCore version 2.15.0 et versions ultérieures, l’appel services.AddApplicationInsightsTelemetry() lit automatiquement le connection string à partir de Microsoft.Extensions.Configuration.IConfiguration de l’application. Il n’est pas nécessaire de fournir explicitement IConfiguration.

Si IConfiguration a chargé la configuration depuis plusieurs fournisseurs, services.AddApplicationInsightsTelemetry priorise la configuration de appsettings.json, quel que soit l’ordre dans lequel les fournisseurs sont ajoutés. Utilisez la méthode services.AddApplicationInsightsTelemetry(IConfiguration) pour lire la configuration à partir de IConfiguration sans ce traitement préférentiel pour appsettings.json.

Service Worker

Dans cette section

• Utiliser le Kit de développement logiciel (SDK) Application Insights pour le service Worker
• Application de service Worker .NET Core
• Tâches en arrière-plan ASP.NET Core avec des services hébergés
• Application console .NET Core /. NET Framework

Utiliser le Kit de développement logiciel (SDK) Application Insights pour le service Worker

1. Installez le package Microsoft.ApplicationInsights.WorkerService sur l’application.

   L’extrait de code suivant montre les modifications qui doivent être ajoutées au fichier de .csproj votre projet :

       <ItemGroup>
           <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
       </ItemGroup>
   

2. Configurez le connection string dans la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING ou dans la configuration (appsettings.json).

   

3. Récupérez une instance ILogger ou TelemetryClient à partir du conteneur Dependency Injection (DI) en appelant serviceProvider.GetRequiredService<TelemetryClient>(); ou en utilisant Constructor Injection. Cette étape déclenche la configuration de TelemetryConfiguration et des modules de collecte automatique.

Des instructions spécifiques pour chaque type d’application sont décrites dans les sections suivantes.

Application de service Worker .NET Core

L’exemple complet est partagé sur le site web NuGet.

1. Download et installez le SDK .NET.

2. Créez un projet de service Worker à l’aide d’un modèle de projet Visual Studio nouveau ou de la ligne de commande dotnet new worker.

3. Ajoutez le package Microsoft.ApplicationInsights.WorkerService à l’application.

4. Ajoutez services.AddApplicationInsightsTelemetryWorkerService(); à la CreateHostBuilder() méthode dans votre Program.cs classe, comme dans cet exemple :

       public static IHostBuilder CreateHostBuilder(string[] args) =>
           Host.CreateDefaultBuilder(args)
               .ConfigureServices((hostContext, services) =>
               {
                   services.AddHostedService<Worker>();
                   services.AddApplicationInsightsTelemetryWorkerService();
               });
   

5. Modifiez votre Worker.cs selon l’exemple suivant :

       using Microsoft.ApplicationInsights;
       using Microsoft.ApplicationInsights.DataContracts;
   
       public class Worker : BackgroundService
       {
           private readonly ILogger<Worker> _logger;
           private TelemetryClient _telemetryClient;
           private static HttpClient _httpClient = new HttpClient();
   
           public Worker(ILogger<Worker> logger, TelemetryClient tc)
           {
               _logger = logger;
               _telemetryClient = tc;
           }
   
           protected override async Task ExecuteAsync(CancellationToken stoppingToken)
           {
               while (!stoppingToken.IsCancellationRequested)
               {
                   _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
   
                   using (_telemetryClient.StartOperation<RequestTelemetry>("operation"))
                   {
                       _logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                       _logger.LogInformation("Calling bing.com");
                       var res = await _httpClient.GetAsync("https://bing.com");
                       _logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                       _telemetryClient.TrackEvent("Bing call event completed");
                   }
   
                   await Task.Delay(1000, stoppingToken);
               }
           }
       }
   

6. Configurez le connection string.

   

   Note

   Nous vous recommandons de spécifier la connection string dans la configuration. L’exemple de code suivant montre comment spécifier un connection string dans appsettings.json. Vérifiez que appsettings.json est copié dans le dossier racine de l’application lors de la publication.

       {
           "ApplicationInsights":
           {
               "ConnectionString" : "<YOUR-CONNECTION-STRING>"
           },
           "Logging":
           {
               "LogLevel":
               {
                   "Default": "Warning"
               }
           }
       }
   

Vous pouvez également spécifier la connection string dans la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING.

En règle générale, APPLICATIONINSIGHTS_CONNECTION_STRING spécifie la chaîne de connexion des applications déployées sur des applications web en tant que tâches Web.

Note

Une connection string spécifiée dans le code est prioritaire sur la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING, qui est prioritaire sur d’autres options.

Tâches en arrière-plan ASP.NET Core avec des services hébergés

Ce document explique comment créer des tâches en arrière-plan dans une application ASP.NET Core.

L’exemple complet est partagé sur cette page GitHub.

1. Installez le package Microsoft.ApplicationInsights.WorkerService sur l’application.

2. Ajoutez services.AddApplicationInsightsTelemetryWorkerService(); à la ConfigureServices() méthode, comme dans cet exemple :

       public static async Task Main(string[] args)
       {
           var host = new HostBuilder()
               .ConfigureAppConfiguration((hostContext, config) =>
               {
                   config.AddJsonFile("appsettings.json", optional: true);
               })
               .ConfigureServices((hostContext, services) =>
               {
                   services.AddLogging();
                   services.AddHostedService<TimedHostedService>();
   
                   // connection string is read automatically from appsettings.json
                   services.AddApplicationInsightsTelemetryWorkerService();
               })
               .UseConsoleLifetime()
               .Build();
   
           using (host)
           {
               // Start the host
               await host.StartAsync();
   
               // Wait for the host to shutdown
               await host.WaitForShutdownAsync();
           }
       }
   

   Le code suivant concerne TimedHostedServicel’emplacement où réside la logique de tâche en arrière-plan :

       using Microsoft.ApplicationInsights;
       using Microsoft.ApplicationInsights.DataContracts;
   
       public class TimedHostedService : IHostedService, IDisposable
       {
           private readonly ILogger _logger;
           private Timer _timer;
           private TelemetryClient _telemetryClient;
           private static HttpClient httpClient = new HttpClient();
   
           public TimedHostedService(ILogger<TimedHostedService> logger, TelemetryClient tc)
           {
               _logger = logger;
               this._telemetryClient = tc;
           }
   
           public Task StartAsync(CancellationToken cancellationToken)
           {
               _logger.LogInformation("Timed Background Service is starting.");
   
               _timer = new Timer(DoWork, null, TimeSpan.Zero,
                   TimeSpan.FromSeconds(1));
   
               return Task.CompletedTask;
           }
   
           private void DoWork(object state)
           {
               _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
   
               using (_telemetryClient.StartOperation<RequestTelemetry>("operation"))
               {
                   _logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                   _logger.LogInformation("Calling bing.com");
                   var res = httpClient.GetAsync("https://bing.com").GetAwaiter().GetResult();
                   _logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                   _telemetryClient.TrackEvent("Bing call event completed");
               }
           }
       }
   

3. Configurez le connection string. Utilisez le même appsettings.json que dans l’exemple précédent .NET Worker Service.

application console .NET Core/.NET Framework

Comme mentionné au début de cet article, le nouveau package peut être utilisé pour activer les données de télémétrie Application Insights à partir d’une application console standard. Ce package cible netstandard2.0. Il peut donc être utilisé pour les applications console dans .NET Core ou version ultérieure, et .NET Framework ou ultérieur.

L’exemple complet est partagé sur cette page GitHub.

1. Installez le package Microsoft.ApplicationInsights.WorkerService sur l’application.

2. Modifiez Program.cs comme indiqué dans l’exemple suivant :

       using Microsoft.ApplicationInsights;
       using Microsoft.ApplicationInsights.DataContracts;
       using Microsoft.ApplicationInsights.WorkerService;
       using Microsoft.Extensions.DependencyInjection;
       using Microsoft.Extensions.Logging;
       using System;
       using System.Net.Http;
       using System.Threading.Tasks;
   
       namespace WorkerSDKOnConsole
       {
           class Program
           {
               static async Task Main(string[] args)
               {
                   // Create the DI container.
                   IServiceCollection services = new ServiceCollection();
   
                   // Being a regular console app, there is no appsettings.json or configuration providers enabled by default.
                   // Hence connection string and any changes to default logging level must be specified here.
                   services.AddLogging(loggingBuilder => loggingBuilder.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("Category", LogLevel.Information));
                   services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = "<YOUR-CONNECTION-STRING>");
   
                   // To pass a connection string
                   // - aiserviceoptions must be created
                   // - set connectionstring on it
                   // - pass it to AddApplicationInsightsTelemetryWorkerService()
   
                   // Build ServiceProvider.
                   IServiceProvider serviceProvider = services.BuildServiceProvider();
   
                   // Obtain logger instance from DI.
                   ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();
   
                   // Obtain TelemetryClient instance from DI, for additional manual tracking or to flush.
                   var telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();
   
                   var httpClient = new HttpClient();
   
                   while (true) // This app runs indefinitely. Replace with actual application termination logic.
                   {
                       logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
   
                       // Replace with a name which makes sense for this operation.
                       using (telemetryClient.StartOperation<RequestTelemetry>("operation"))
                       {
                           logger.LogWarning("A sample warning message. By default, logs with severity Warning or higher is captured by Application Insights");
                           logger.LogInformation("Calling bing.com");                    
                           var res = await httpClient.GetAsync("https://bing.com");
                           logger.LogInformation("Calling bing completed with status:" + res.StatusCode);
                           telemetryClient.TrackEvent("Bing call event completed");
                       }
   
                       await Task.Delay(1000);
                   }
   
                   // Explicitly call Flush() followed by sleep is required in console apps.
                   // This is to ensure that even if application terminates, telemetry is sent to the back-end.
                   telemetryClient.Flush();
                   Task.Delay(5000).Wait();
               }
           }
       }
   

Cette application console utilise également la même valeur par défaut TelemetryConfiguration. Il peut être personnalisé de la même façon que les exemples des sections précédentes.

Déployer l’agent Application Insights pour les serveurs locaux

Dans cette section

• Commencer - Pour commencer à utiliser des exemples de code concis.
• Instructions détaillées : pour une présentation approfondie de la prise en main.
• Références d’API : pour référence d’API PowerShell.

Application Insights Agent est un module PowerShell publié dans le PowerShell Gallery. Il remplace Status Monitor. La télémétrie est envoyée au portail Azure, où vous pouvez surveiller votre application.

Pour obtenir la liste complète des scénarios d’instrumentation automatique pris en charge, veuillez consulter la rubrique Environnements pris en charge, langages et les fournisseurs de ressources pris en charge.

Note

Le module prend actuellement en charge l’instrumentation sans code de ASP.NET et d’applications web ASP.NET Core hébergées avec Internet Information Server (IIS). Utilisez un SDK pour instrumenter des applications Java et Node.js.

Note

La surveillance côté client est activée par défaut pour les applications ASP.NET Core. Si vous souhaitez désactiver le monitoring côté client, définissez une variable d’environnement dans le serveur à l’aide des informations suivantes :

• Nom :APPINSIGHTS_JAVASCRIPT_ENABLED
• Valeur : false

Démarrage

Cette section contient les commandes de démarrage rapide qui sont censées fonctionner pour la plupart des environnements. Les instructions dépendent de PowerShell Gallery pour distribuer les mises à jour. Ces commandes prennent en charge le paramètre -Proxy PowerShell.

Pour obtenir une explication de ces commandes, des instructions de personnalisation et des informations sur le dépannage, consultez les instructions détaillées.

Si vous n'avez pas d'abonnement Azure, créez un compte free avant de commencer.

Option 1 : Télécharger et installer Application Insights Agent via PowerShell Gallery

Note

Pour connaître les prérequis éventuels, consultez la prise en charge de TLS (Transport Layer Security) dans la PowerShell Gallery.

1. Installez le module (exécuter en tant qu’administrateur) :

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
   Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
   Set-PSRepository -Name "PSGallery" -InstallationPolicy Trusted
   Install-Module -Name PowerShellGet -Force
   

2. Installez Application Insights Agent (exécuté en tant qu’administrateur) :

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
   Install-Module -Name Az.ApplicationMonitor -AllowPrerelease -AcceptLicense
   

   Note

   Le commutateur AllowPrerelease dans l’applet de commande Install-Module permet l’installation de la version bêta.

   Pour plus d’informations, consultez Install-Module.

3. Activer la surveillance :

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
   Enable-ApplicationInsightsMonitoring -ConnectionString 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/'
   

Option 2 : Télécharger et installer l’agent Application Insights manuellement (option hors connexion)

1. Téléchargez manuellement la dernière version du module à partir de PowerShell Gallery.

2. Décompressez et installez Application Insights Agent :

   $pathToNupkg = "C:\Users\t\Desktop\Az.ApplicationMonitor.0.3.0-alpha.nupkg"
   $pathToZip = ([io.path]::ChangeExtension($pathToNupkg, "zip"))
   $pathToNupkg | rename-item -newname $pathToZip
   $pathInstalledModule = "$Env:ProgramFiles\WindowsPowerShell\Modules\Az.ApplicationMonitor"
   Expand-Archive -LiteralPath $pathToZip -DestinationPath $pathInstalledModule
   

3. Activer la surveillance :

   Enable-ApplicationInsightsMonitoring -ConnectionString 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/'
   

Instructions détaillées

Cette section explique comment intégrer au PowerShell Gallery et télécharger le module ApplicationMonitor. Il contient les paramètres les plus courants dont vous aurez besoin pour commencer. Nous fournissons également des instructions de téléchargement manuel si vous n’avez pas d’accès Internet.

Exécuter PowerShell en tant qu’administrateur avec une stratégie d'exécution élevée

Important

PowerShell a besoin d’autorisations de niveau administrateur pour apporter des modifications à votre ordinateur.

Stratégie d’exécution

• Description : Par défaut, l’exécution des scripts PowerShell est désactivée. Nous vous recommandons d’autoriser les scripts RemoteSigned (signés à distance) uniquement pour l’étendue Current (Actuelle).
• Référence : À propos des stratégies d’exécution et Set-ExecutionPolicy.
• Commande : Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process.
• Paramètre facultatif :
  • -Force. Pour contourner l’invite de confirmation.

Exemples d’erreurs

Install-Module : The 'Install-Module' command was found in the module 'PowerShellGet', but the module could not be
loaded. For more information, run 'Import-Module PowerShellGet'.

Import-Module : File C:\Program Files\WindowsPowerShell\Modules\PackageManagement\1.3.1\PackageManagement.psm1 cannot
be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https://go.microsoft.com/fwlink/?LinkID=135170.

Prérequis pour PowerShell

Effectuez l’audit de votre instance de PowerShell en exécutant la commande $PSVersionTable. Cette commande génère la sortie suivante :

Name                           Value
----                           -----
PSVersion                      5.1.17763.316
PSEdition                      Desktop
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
BuildVersion                   10.0.17763.316
CLRVersion                     4.0.30319.42000
WSManStackVersion              3.0
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1

Ces instructions ont été écrites et testées sur un ordinateur exécutant Windows 10 et les versions suivantes.

Conditions préalables pour PowerShell Gallery

Ces étapes préparent votre serveur à télécharger des modules à partir de PowerShell Gallery.

Note

PowerShell Gallery est pris en charge sur Windows 10, Windows Server 2016 et PowerShell 6+. Pour plus d’informations sur les versions antérieures, consultez Installation de PowerShellGet.

1. Exécutez PowerShell en tant qu’administrateur avec une stratégie d’exécution avec élévation de privilèges.

2. Installez le fournisseur du package NuGet.

   • Description : vous avez besoin de ce fournisseur pour interagir avec des référentiels NuGet tels que PowerShell Gallery.
   • Référence : Install-PackageProvider.
   • Commande : Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201.
   • Paramètres facultatifs :
     • -Proxy. Spécifie un serveur proxy pour la demande.
     • -Force. Pour contourner l’invite de confirmation.

   Vous recevez cette invite si NuGet n’est pas configuré :

   NuGet provider is required to continue
   PowerShellGet requires NuGet provider version '2.8.5.201' or newer to interact with NuGet-based repositories.
   The NuGet provider must be available in 'C:\Program Files\PackageManagement\ProviderAssemblies' or
   'C:\Users\t\AppData\Local\PackageManagement\ProviderAssemblies'. You can also install the NuGet provider by running
   'Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force'. Do you want PowerShellGet to install and import
   the NuGet provider now?
   [Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):
   

3. Configurez PowerShell Gallery en tant que référentiel approuvé.

   • Description : par défaut, PowerShell Gallery est un référentiel non approuvé.
   • Référence : Set-PSRepository.
   • Commande : Set-PSRepository -Name "PSGallery" -InstallationPolicy Trusted.
   • Paramètre facultatif :
     • -Proxy. Spécifie un serveur proxy pour la demande.

   Vous recevez cette invite si PowerShell Gallery n'est pas approuvé :

   Untrusted repository
   You are installing the modules from an untrusted repository.
   If you trust this repository, change its InstallationPolicy value
   by running the Set-PSRepository cmdlet. Are you sure you want to
   install the modules from 'PSGallery'?
   [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"):
   

   Vous pouvez confirmer cette modification et effectuer l’audit de tous les PSRepositories en exécutant la commande Get-PSRepository.

4. Installez la nouvelle version de PowerShellGet.

   • Description : ce module contient les outils utilisés pour obtenir d’autres modules à partir de PowerShell Gallery. La version 1.0.0.1 est fournie avec Windows 10 et Windows Server. La version 1.6.0 ou supérieure est nécessaire. Pour déterminer la version installée, exécutez la commande Get-Command -Module PowerShellGet.
   • Référence : Installation de PowerShellGet.
   • Commande : Install-Module -Name PowerShellGet.
   • Paramètres facultatifs :
     • -Proxy. Spécifie un serveur proxy pour la demande.
     • -Force. Pour ignorer l’avertissement « Déjà installé » et installer la dernière version.

   Vous recevez cette erreur si vous n’utilisez pas la version la plus récente de PowerShellGet :

   Install-Module : A parameter cannot be found that matches parameter name 'AllowPrerelease'.
   At line:1 char:20
   Install-Module abc -AllowPrerelease
                  ~~~~~~~~~~~~~~~~
   CategoryInfo          : InvalidArgument: (:) [Install-Module], ParameterBindingException
   FullyQualifiedErrorId : NamedParameterNotFound,Install-Module
   

5. Redémarrez PowerShell. Impossible de charger la nouvelle version dans la session active. Les nouvelles sessions PowerShell chargent la dernière version de PowerShellGet.

Option 1 : Télécharger et installer le module via PowerShell Gallery

Ces étapes téléchargent le module Az.ApplicationMonitor à partir de PowerShell Gallery.

1. Vérifiez que toutes les conditions préalables pour PowerShell Gallery sont remplies.
2. Exécutez PowerShell en tant qu’administrateur avec une stratégie d’exécution avec élévation de privilèges.
3. Installez le module Az.ApplicationMonitor.
   • Référence : Install-Module.
   • Commande : Install-Module -Name Az.ApplicationMonitor.
   • Paramètres facultatifs :
     • -Proxy. Spécifie un serveur proxy pour la demande.
     • -AllowPrerelease. Pour installer les versions alpha et bêta.
     • -AcceptLicense. Court-circuite l'invite « Accepter la licence »
     • -Force. Ignorer l’avertissement « Référentiel non approuvé ».

Option 2 : Télécharger et installer le module manuellement (option hors connexion)

Si pour une raison quelconque vous ne pouvez pas vous connecter au module PowerShell, vous pouvez manuellement télécharger et installer le module Az.ApplicationMonitor.

Téléchargement manuel du dernier fichier nupkg

1. Accédez à https://www.powershellgallery.com/packages/Az.ApplicationMonitor.
2. Sélectionnez la dernière version du fichier dans la table Historique des versions.
3. Sous Options d’installation, sélectionnez Téléchargement manuel.

Option 2.1 : Installer dans un répertoire de modules PowerShell

Installez le module PowerShell téléchargé manuellement dans un répertoire PowerShell afin qu’il soit détectable par les sessions PowerShell. Pour plus d’informations, consultez l’article Installation d’un module PowerShell.

Décompressez nupkg en tant que fichier zip à l’aide de Expand-Archive (v1.0.1.0)

• Description : La version de base de Microsoft.PowerShell.Archive (v1.0.1.0) ne peut pas décompresser les fichiers nupkg. Renommez le fichier avec l’extension .zip.

• Référence : Expand-Archive.

• Commande :

  $pathToNupkg = "C:\az.applicationmonitor.0.3.0-alpha.nupkg"
  $pathToZip = ([io.path]::ChangeExtension($pathToNupkg, "zip"))
  $pathToNupkg | rename-item -newname $pathToZip
  $pathInstalledModule = "$Env:ProgramFiles\WindowsPowerShell\Modules\az.applicationmonitor"
  Expand-Archive -LiteralPath $pathToZip -DestinationPath $pathInstalledModule
  

Décompressez nupkg à l’aide de Expand-Archive (v1.1.0.0)

• Description : Utilisez une version actuelle de Expand-Archive pour décompresser des fichiers nupkg sans avoir à modifier l’extension.

• Référence : Expand-Archive et Microsoft.PowerShell.Archive.

• Commande :

  $pathToNupkg = "C:\az.applicationmonitor.0.2.1-alpha.nupkg"
  $pathInstalledModule = "$Env:ProgramFiles\WindowsPowerShell\Modules\az.applicationmonitor"
  Expand-Archive -LiteralPath $pathToNupkg -DestinationPath $pathInstalledModule
  

Option 2.2 : Décompresser et importer manuellement nupkg

Installez le module PowerShell téléchargé manuellement dans un répertoire PowerShell afin qu’il soit détectable par les sessions PowerShell. Pour plus d’informations, consultez l’article Installation d’un module PowerShell.

Si vous installez le module dans n’importe quel répertoire, importez-le manuellement à l’aide de Import-Module.

Important

Les bibliothèques de liens dynamiques (DLL) s’installent via des chemins relatifs. Stockez le contenu du package dans le répertoire du runtime prévu et confirmez que les autorisations d’accès autorisent la lecture mais pas l’écriture.

1. Remplacez l’extension par « .zip » et extrayez le contenu du package dans le répertoire d’installation prévu.
2. Recherchez le chemin de fichier de Az.ApplicationMonitor.psd1.
3. Exécutez PowerShell en tant qu’administrateur avec une stratégie d’exécution avec élévation de privilèges.
4. Chargez le module à l’aide de la commande Import-Module Az.ApplicationMonitor.psd1.

Router le trafic via un proxy

Lorsque vous analysez un ordinateur sur votre intranet privé, vous devez acheminer le trafic HTTP via un proxy.

Les commandes PowerShell pour télécharger et installer Az.ApplicationMonitor à partir du PowerShell Gallery prennent en charge un paramètre -Proxy. Lorsque vous écrivez vos scripts d’installation, passez en revue les instructions précédentes.

Le kit de développement logiciel (SDK) Application Insights doit envoyer les données de télémétrie de votre application à Microsoft. Nous vous recommandons de configurer les paramètres de proxy de votre application dans votre fichier web.config. Pour plus d’informations, consultez Comment obtenir un relais proxy ?.

Activer la supervision

Utilisez la commande Enable-ApplicationInsightsMonitoring pour activer la supervision.

Consultez la documentation de référence de l’API pour obtenir une description détaillée de l’utilisation de cette cmdlet.

Référence d’API

Important

• Les applets de commande suivantes nécessitent une session PowerShell avec des autorisations d’administrateur et une stratégie d’exécution avec élévation de privilèges. Pour plus d’informations, consultez Run PowerShell as Admin with an elevated execution policy (Exécuter PowerShell en tant qu’administrateur avec une stratégie d’exécution avec élévation de privilèges).
• Les applets de commande suivantes nécessitent que vous révisiez et acceptez notre licence et notre déclaration de confidentialité.
• Le moteur d’instrumentation ajoute une surcharge et est désactivé par défaut.

Cette section décrit les applets de commande suivantes, qui sont membres du module PowerShell Az.ApplicationMonitor :

Note

Accédez à l’une des sections ci-dessous pour plus d’informations, y compris des exemples, des paramètres et un résultat.

Enable-InstrumentationEngine

Active le moteur d’instrumentation en définissant certaines clés de Registre. Redémarrez IIS pour que les modifications soient prises en compte.

Le moteur d’instrumentation peut compléter les données collectées par les kits de développement logiciel (SDK) .NET. Il collecte les événements et les messages qui décrivent l’exécution d’un processus managé. Ces événements et messages incluent les codes de résultat de dépendance, les verbes HTTP et le texte de commande SQL.

Activez le moteur d’instrumentation si :

• Vous avez déjà activé le monitoring avec la cmdlet Enable mais n’avez pas activé le moteur d’instrumentation.
• Vous avez instrumenté manuellement votre application avec les sdk .NET et souhaitez collecter des données de télémétrie supplémentaires.

Exemples

Enable-InstrumentationEngine

Paramètres

Paramètre	Descriptif
-AcceptLicense	Optionnel. Utilisez cet interrupteur pour accepter la licence et la déclaration de confidentialité dans les installations sans interface graphique.
-Verbose	Paramètre commun. Utilisez ce commutateur pour générer des journaux détaillés.

Sortie

Exemple de sortie de l’activation réussie du moteur d’instrumentation :

Configuring IIS Environment for instrumentation engine...
Configuring registry for instrumentation engine...

Enable-ApplicationInsightsMonitoring

Permet la surveillance sans code des applications IIS sur un ordinateur cible.

Cette cmdlet modifie l’élément applicationHost.config de l’application IIS et définit des clés de Registre. Elle crée un fichier applicationinsights.ikey.config, qui définit la clé d’instrumentation utilisée par chaque application. IIS charge RedfieldModule au démarrage, qui injecte le SDK Application Insights dans les applications à mesure qu’elles démarrent. Redémarrez IIS pour que vos modifications prennent effet.

Après avoir activé la surveillance, nous vous recommandons d’utiliser Métriques en temps réel pour vérifier rapidement si votre application nous envoie des données de télémétrie.

Exemples

Exemple avec une seule chaîne de connexion

Dans cet exemple, toutes les applications sur l’ordinateur actuel sont fournies avec une seule connection string.

Enable-ApplicationInsightsMonitoring -ConnectionString 'InstrumentationKey=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/'

Exemple avec une clé d’instrumentation unique

Dans cet exemple, toutes les applications de l’ordinateur actuel sont fournies avec une seule clé d’instrumentation.

Enable-ApplicationInsightsMonitoring -InstrumentationKey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Exemple avec une carte de clé d'instrumentation

Dans cet exemple :

• MachineFilter effectue la correspondance avec l’ordinateur actuel en utilisant le caractère générique '.*'.
• AppFilter='WebAppExclude' fournit une clé d’instrumentation null. L’application spécifiée n’est pas instrumentée.
• AppFilter='WebAppOne' attribue à l’application spécifiée une clé d’instrumentation unique.
• AppFilter='WebAppTwo' attribue à l’application spécifiée une clé d’instrumentation unique.
• AppFilter utilise le caractère générique '.*' pour faire correspondre les applications web avec lesquelles aucune correspondance n’a encore été établie, et affecte une clé d’instrumentation par défaut.
• Des espaces ont été ajoutées pour faciliter la lisibilité.

Enable-ApplicationInsightsMonitoring -InstrumentationKeyMap `
    ` @(@{MachineFilter='.*';AppFilter='WebAppExclude'},
        ` @{MachineFilter='.*';AppFilter='WebAppOne';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1'}},
        ` @{MachineFilter='.*';AppFilter='WebAppTwo';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2'}},
        ` @{MachineFilter='.*';AppFilter='.*';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault'}})

• MachineFilter est une expression régulière C# requise du nom de l’ordinateur ou de la machine virtuelle.
  • « .* » correspond à tout.
  • « ComputerName » établit une correspondance uniquement avec les ordinateurs ayant le nom exact spécifié.
• AppFilter est une expression C# régulière obligatoire du nom du site IIS. Vous pouvez obtenir la liste des sites sur votre serveur en exécutant la commande get-iissite.
  • « .* » correspond à tout.
  • « SiteName » établit une correspondance uniquement avec le site IIS ayant le nom exact spécifié.
• InstrumentationKey est requis pour activer la surveillance des applications qui correspondent aux deux filtres précédents.
  • Conservez la valeur null si vous souhaitez définir des règles pour exclure la surveillance.

Paramètres

Paramètre	Descriptif
-EnableInstrumentationEngine	Optionnel. Utilisez cette instruction switch pour permettre au moteur d’instrumentation de collecter des événements et des messages sur ce qui se passe pendant l’exécution d’un processus managé. Ces événements et messages incluent les codes de résultat de dépendance, les verbes HTTP et le texte de commande SQL. Le moteur d’instrumentation ajoute une surcharge et est désactivé par défaut.
-AcceptLicense	Optionnel. Utilisez cet interrupteur pour accepter la licence et la déclaration de confidentialité dans les installations sans interface graphique.
-IgnoreSharedConfig	Lorsque vous avez un cluster de serveurs web, il se peut que vous utilisiez une configuration partagée. HttpModule ne peut pas être injecté dans cette configuration partagée. Ce script échoue avec le message indiquant que des étapes d’installation supplémentaires sont requises. Utilisez ce commutateur pour ignorer cette vérification et poursuivre l’installation des prérequis. Pour plus d’informations, consultez conflit connu avec la configuration partagée IIS
-Verbose	Paramètre commun. Utilisez ce commutateur pour afficher les journaux détaillés.
-WhatIf	Paramètre commun. Utilisez cette instruction switch pour tester et valider vos paramètres d’entrée sans réellement activer la surveillance.

Sortie

Exemple de sortie à partir d’une activation réussie

Initiating Disable Process
Applying transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config'
'C:\Windows\System32\inetsrv\config\applicationHost.config' backed up to 'C:\Windows\System32\inetsrv\config\applicationHost.config.backup-2019-03-26_08-59-52z'
in :1,237
No element in the source document matches '/configuration/location[@path='']/system.webServer/modules/add[@name='ManagedHttpModuleHelper']'
Not executing RemoveAll (transform line 1, 546)
Transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config' was successfully applied. Operation: 'disable'
GAC Module will not be removed, since this operation might cause IIS instabilities
Configuring IIS Environment for codeless attach...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring IIS Environment for instrumentation engine...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring registry for instrumentation engine...
Successfully disabled Application Insights Agent
Installing GAC module 'C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\0.2.0\content\Runtime\Microsoft.AppInsights.IIS.ManagedHttpModuleHelper.dll'
Applying transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config'
Found GAC module Microsoft.AppInsights.IIS.ManagedHttpModuleHelper.ManagedHttpModuleHelper, Microsoft.AppInsights.IIS.ManagedHttpModuleHelper, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35
'C:\Windows\System32\inetsrv\config\applicationHost.config' backed up to 'C:\Windows\System32\inetsrv\config\applicationHost.config.backup-2019-03-26_08-59-52z_1'
Transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config' was successfully applied. Operation: 'enable'
Configuring IIS Environment for codeless attach...
Configuring IIS Environment for instrumentation engine...
Configuring registry for instrumentation engine...
Updating app pool permissions...
Successfully enabled Application Insights Agent

Disable-InstrumentationEngine

Désactive le moteur d’instrumentation en supprimant certaines clés de Registre. Redémarrez IIS pour que les modifications soient prises en compte.

Exemples

Disable-InstrumentationEngine

Paramètres

Paramètre	Descriptif
-Verbose	Paramètre commun. Utilisez ce commutateur pour générer des journaux détaillés.

Sortie

Exemple de sortie à partir d’une désactivation réussie du moteur d’instrumentation

Configuring IIS Environment for instrumentation engine...
Registry: removing 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]'
Registry: removing 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]'
Registry: removing 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]'
Configuring registry for instrumentation engine...

Disable-ApplicationInsightsMonitoring

Désactive l’analyse sur l’ordinateur cible. Cette applet de commande supprime les modifications apportées à l’élément applicationHost.config de l’application IIS et supprime les clés de Registre.

Exemples

Disable-ApplicationInsightsMonitoring

Paramètres

Paramètre	Descriptif
-Verbose	Paramètre commun. Utilisez ce commutateur pour afficher les journaux détaillés.

Sortie

Exemple de sortie à partir d’une désactivation réussie de la surveillance

Initiating Disable Process
Applying transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config'
'C:\Windows\System32\inetsrv\config\applicationHost.config' backed up to 'C:\Windows\System32\inetsrv\config\applicationHost.config.backup-2019-03-26_08-59-00z'
in :1,237
No element in the source document matches '/configuration/location[@path='']/system.webServer/modules/add[@name='ManagedHttpModuleHelper']'
Not executing RemoveAll (transform line 1, 546)
Transformation to 'C:\Windows\System32\inetsrv\config\applicationHost.config' was successfully applied. Operation: 'disable'
GAC Module will not be removed, since this operation might cause IIS instabilities
Configuring IIS Environment for codeless attach...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring IIS Environment for instrumentation engine...
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\IISADMIN[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC[Environment]
Registry: skipping non-existent 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS[Environment]
Configuring registry for instrumentation engine...
Successfully disabled Application Insights Agent

Get-ApplicationInsightsMonitoringConfig

Obtient le fichier de configuration et imprime les valeurs dans la console.

Exemples

Get-ApplicationInsightsMonitoringConfig

Paramètres

Aucun paramètre requis.

Sortie

Exemple de sortie à partir de la lecture du fichier de configuration

RedfieldConfiguration:
Filters:
0)InstrumentationKey: AppFilter: WebAppExclude MachineFilter: .*
1)InstrumentationKey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2 AppFilter: WebAppTwo MachineFilter: .*
2)InstrumentationKey: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault AppFilter: .* MachineFilter: .*

Get-ApplicationInsightsMonitoringStatus

Cette applet de commande fournit des informations de résolution des problèmes sur l’agent Application Insights. Utilisez ce cmdlet pour analyser l’état de l’analyse, la version du module PowerShell et pour inspecter le processus en cours d’exécution. Cette cmdlet signale les informations de version et les informations sur les fichiers de clés nécessaires à la supervision.

Exemples

Exemple : État de l’application

Exécutez la commande Get-ApplicationInsightsMonitoringStatus pour afficher l’état d’analyse des sites Web.

Get-ApplicationInsightsMonitoringStatus

IIS Websites:

SiteName               : Default Web Site
ApplicationPoolName    : DefaultAppPool
SiteId                 : 1
SiteState              : Stopped

SiteName               : DemoWebApp111
ApplicationPoolName    : DemoWebApp111
SiteId                 : 2
SiteState              : Started
ProcessId              : not found

SiteName               : DemoWebApp222
ApplicationPoolName    : DemoWebApp222
SiteId                 : 3
SiteState              : Started
ProcessId              : 2024
Instrumented           : true
InstrumentationKey     : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx123

SiteName               : DemoWebApp333
ApplicationPoolName    : DemoWebApp333
SiteId                 : 4
SiteState              : Started
ProcessId              : 5184
AppAlreadyInstrumented : true

Dans cet exemple :

• l’identificateur de la machine est un ID anonyme utilisé pour identifier de manière unique votre serveur. Si vous créez une demande d’assistance, nous aurons besoin de l’ID pour rechercher les logs de votre serveur.

• Le site Web par défaut est arrêté dans IIS

• IIS affiche DemoWebApp111 comme démarré, mais l’application ne reçoit aucune requête. Le rapport n’affiche aucun processus en cours d’exécution (ProcessId : introuvable).

• DemoWebApp222 est en cours d’exécution et est en cours d’analyse (Instrumented: true). En fonction de la configuration utilisateur, la clé d'instrumentation xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx123 a été associée à ce site.

• DemoWebApp333 est instrumenté manuellement à l’aide du Kit de développement logiciel (SDK) Application Insights. L’agent Application Insights détecte le Kit de développement logiciel (SDK) et ne surveille pas ce site.

• La présence de AppAlreadyInstrumented : true signifie que l’agent Application Insights a identifié une DLL en conflit chargée dans l’application web, supposé que l’application web est instrumentée manuellement et que l’agent s’est retiré et n’instrumente pas ce processus.

• Instrumented : true indique que l’agent Application Insights a correctement instrumenté l’application web s’exécutant dans le processus de w3wp.exe spécifié.

Exemple : Informations sur le module PowerShell

Exécutez la commande Get-ApplicationInsightsMonitoringStatus -PowerShellModule pour afficher des informations sur le module actuel :

Get-ApplicationInsightsMonitoringStatus -PowerShellModule

PowerShell Module version:
0.4.0-alpha

Application Insights SDK version:
2.9.0.3872

Executing PowerShell Module Assembly:
Microsoft.ApplicationInsights.Redfield.Configurator.PowerShell, Version=2.8.14.11432, Culture=neutral, PublicKeyToken=31bf3856ad364e35

PowerShell Module Directory:
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\0.2.2\content\PowerShell

Runtime Paths:
ParentDirectory (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content

ConfigurationPath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\applicationInsights.ikey.config

ManagedHttpModuleHelperPath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AppInsights.IIS.ManagedHttpModuleHelper.dll

RedfieldIISModulePath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll

InstrumentationEngine86Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation32\MicrosoftInstrumentationEngine_x86.dll

InstrumentationEngine64Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\MicrosoftInstrumentationEngine_x64.dll

InstrumentationEngineExtensionHost86Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation32\Microsoft.ApplicationInsights.ExtensionsHost_x86.dll

InstrumentationEngineExtensionHost64Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.ApplicationInsights.ExtensionsHost_x64.dll

InstrumentationEngineExtensionConfig86Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation32\Microsoft.InstrumentationEngine.Extensions.config

InstrumentationEngineExtensionConfig64Path (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.InstrumentationEngine.Extensions.config

ApplicationInsightsSdkPath (Exists: True)
C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.dll

Exemple : État d’exécution

Vous pouvez inspecter le processus sur l’ordinateur instrumenté pour vérifier si toutes les DLL sont chargées. Si la surveillance fonctionne, au moins 12 DLL doivent être chargées.

Exécutez la commande suivante Get-ApplicationInsightsMonitoringStatus -InspectProcess :

Get-ApplicationInsightsMonitoringStatus -InspectProcess

iisreset.exe /status
Status for IIS Admin Service ( IISADMIN ) : Running
Status for Windows Process Activation Service ( WAS ) : Running
Status for Net.Msmq Listener Adapter ( NetMsmqActivator ) : Running
Status for Net.Pipe Listener Adapter ( NetPipeActivator ) : Running
Status for Net.Tcp Listener Adapter ( NetTcpActivator ) : Running
Status for World Wide Web Publishing Service ( W3SVC ) : Running

handle64.exe -accepteula -p w3wp
BF0: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.ServerTelemetryChannel.dll
C58: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.AzureAppServices.dll
C68: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.DependencyCollector.dll
C78: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.WindowsServer.dll
C98: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.Web.dll
CBC: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.PerfCounterCollector.dll
DB0: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.AI.Agent.Intercept.dll
B98: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll
BB4: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.Contracts.dll
BCC: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.Redfield.Lightup.dll
BE0: File  (R-D)   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.dll

listdlls64.exe -accepteula w3wp
0x0000000019ac0000  0x127000  C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\MicrosoftInstrumentationEngine_x64.dll
0x00000000198b0000  0x4f000   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.ApplicationInsights.ExtensionsHost_x64.dll
0x000000000c460000  0xb2000   C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Instrumentation64\Microsoft.ApplicationInsights.Extensions.Base_x64.dll
0x000000000ad60000  0x108000  C:\Windows\TEMP\2.4.0.0.Microsoft.ApplicationInsights.Extensions.Intercept_x64.dll

Paramètres

Par défaut, cette cmdlet signale l’état d’analyse des applications Web. Utilisez cette option pour vérifier si votre application a été correctement instrumentée. Vous pouvez également examiner la clé d’instrumentation qui a été mise en correspondance avec votre site.

Paramètre	Descriptif
-PowerShellModule	Facultatif. Utilisez ce commutateur pour signaler les numéros de version et les chemins des DLL nécessaires à l’analyse. Utilisez cette option si vous avez besoin identifier la version de n’importe quelle DLL, y compris le SDK Application Insights.
-InspectProcess	Facultatif. Utilisez ce commutateur pour signaler si IIS est en cours d’exécution. Elle télécharge des outils externes pour déterminer si les DLL sont chargées dans le runtime d’IIS. Si ce processus échoue pour une raison quelconque, vous pouvez exécuter ces commandes manuellement : * iisreset.exe /status * \[handle64.exe\](/sysinternals/downloads/handle) -p w3wp \| findstr /I "InstrumentationEngine AI. ApplicationInsights" * \[listdlls64.exe\](/sysinternals/downloads/listdlls) w3wp \| findstr /I "InstrumentationEngine AI ApplicationInsights"
-Force	Facultatif. Utilisé uniquement avec InspectProcess. Utilisez ce commutateur pour ignorer l’invite utilisateur qui apparaît avant le téléchargement d’outils supplémentaires.

Set-ApplicationInsightsMonitoringConfig

Définit le fichier de configuration sans effectuer de réinstallation complète. Redémarrez IIS pour que vos modifications prennent effet.

Important

Cette cmdlet requiert une session PowerShell avec des autorisations d’administrateur.

Exemples

Exemple avec une clé d’instrumentation unique

Dans cet exemple, toutes les applications de l’ordinateur actuel sont fournies avec une seule clé d’instrumentation.

Enable-ApplicationInsightsMonitoring -InstrumentationKey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Exemple avec une carte de clé d'instrumentation

Dans cet exemple :

• MachineFilter effectue la correspondance avec l’ordinateur actuel en utilisant le caractère générique '.*'.
• AppFilter='WebAppExclude' fournit une clé d’instrumentation null. L’application spécifiée n’est pas instrumentée.
• AppFilter='WebAppOne' attribue à l’application spécifiée une clé d’instrumentation unique.
• AppFilter='WebAppTwo' attribue à l’application spécifiée une clé d’instrumentation unique.
• AppFilter utilise le caractère générique '.*' pour faire correspondre les applications web avec lesquelles aucune correspondance n’a encore été établie, et affecte une clé d’instrumentation par défaut.
• Des espaces ont été ajoutées pour faciliter la lisibilité.

Enable-ApplicationInsightsMonitoring -InstrumentationKeyMap `
    ` @(@{MachineFilter='.*';AppFilter='WebAppExclude'},
      ` @{MachineFilter='.*';AppFilter='WebAppOne';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1'}},
      ` @{MachineFilter='.*';AppFilter='WebAppTwo';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2'}},
      ` @{MachineFilter='.*';AppFilter='.*';InstrumentationSettings=@{InstrumentationKey='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxdefault'}})

Paramètres

Paramètre	Descriptif
-InstrumentationKey	Obligatoire. Utilisez ce paramètre pour fournir une clé d’instrumentation unique que l’ensemble des applications utiliseront sur l’ordinateur cible.
-InstrumentationKeyMap	Obligatoire. Utilisez ce paramètre pour fournir plusieurs clés d’instrumentation et un mappage des clés d’instrumentation utilisées par chaque application.

Vous pouvez créer un script d’installation unique pour plusieurs ordinateurs en définissant le paramètre MachineFilter.

Important

Les applications correspondent à des règles dans l’ordre dans lequel vous les fournissez. Spécifiez les règles les plus spécifiques et finissez par les règles les plus génériques.

Important

InstrumentationKeyMap est une fonctionnalité de routage avancée qui mappe les applications Internet Information Services (IIS) sur le même ordinateur aux ressources Application Insights. La fonctionnalité s'applique aux applications ASP.NET hébergées par IIS et aux applications ASP.NET Core que l'agent Application Insights configure automatiquement.

Fonctionnement de la correspondance

• La carte définit une liste ordonnée de règles nommées filters. La première règle de correspondance prend effet. Placez d'abord des règles spécifiques et terminez par une règle générale.
• Chaque règle peut affecter une ressource Application Insights différente aux applications correspondantes. Préférez les chaînes de connexion dans les scénarios pris en charge, car les clés d’instrumentation sont héritées.

Filtres disponibles

• MachineFilter ou machineFilter: expression régulière C# qui correspond au nom de l’ordinateur ou de la machine virtuelle. .* correspond à tous les prénoms.
• AppFilter ou appFilter: expression régulière C# qui correspond au nom du site IIS (HostingEnvironment.SiteName). Ce filtre est requis quand VirtualPathFilter ou virtualPathFilter n’est pas fourni.
• VirtualPathFilter ou virtualPathFilter: expression régulière C# qui correspond au chemin virtuel IIS (HostingEnvironment.ApplicationVirtualPath). Utilisez ce filtre pour cibler une application unique sous un site.

Mappage de terminologie

• Les applets de commande PowerShell utilisent MachineFilter, AppFilteret VirtualPathFilter.
• Le fichier JSON d’extension de machine virtuelle Azure et de Virtual Machine Scale Sets utilise machineFilter, appFilter et virtualPathFilter, et définit la ressource avec instrumentationSettings.

Conseil / Astuce

Incluez une règle finale qui correspond à toutes les applications, telles que .*, et appliquez une ressource par défaut pour rendre le comportement explicite.

Forme de carte de cette cmdlet

• Fournissez -InstrumentationKeyMap comme tableau PowerShell de tables de hachage.
• Pour cette cmdlet, définissez la ressource cible par règle avec InstrumentationSettings=@{ InstrumentationKey = '<ikey>' }.
• Si vous souhaitez une ressource unique pour toutes les applications sur la machine, utilisez -ConnectionString ou -InstrumentationKey à la place.

Start-ApplicationInsightsMonitoringTrace

Collecte les événements de suivi d’événements pour Windows (ETW) émis par le runtime d’attache sans code. Utilisez cette cmdlet comme alternative plus simple à l’exécution de PerfView.

Les événements sont imprimés dans la console en temps réel et également écrits dans un fichier .etl. Vous pouvez ouvrir le fichier .etl avec PerfView pour une analyse plus approfondie.

Cette cmdlet s’exécute jusqu’à ce qu’elle atteigne le délai d’expiration. La valeur par défaut est de 5 minutes ou correspond au délai d’arrêt manuel avec Ctrl + C.

Exemples

Comment recueillir des événements

Utilisez ce flux quand vous devez enquêter pour savoir pourquoi une application IIS n’est pas instrumentée.

Le runtime d’attachement sans code émet des événements ETW au démarrage d’IIS et au démarrage de votre application.

1. Dans une invite de commandes d’administration, exécutez iisreset /stop pour arrêter IIS et toutes les applications web.
2. Commencez le traçage en exécutant cette cmdlet.
3. Dans une invite de commandes d’administration, exécutez iisreset /start pour démarrer IIS.
4. Déclenchez le démarrage en naviguant jusqu’à votre application.
5. Une fois le chargement de l’application terminé, appuyez sur Ctrl + C pour arrêter ou laissez le délai d’expiration mettre fin à la session.

Événements à collecter

Vous pouvez choisir les sources d’événements à inclure :

1. -CollectSdkEvents collecte des événements depuis le Kit de développement logiciel (SDK) Application Insights.
2. -CollectRedfieldEvents collecte des événements depuis l’agent Application Insights et du runtime Redfield, ce qui est utile pour les diagnostics de démarrage d’application et IIS.
3. Collectez les deux jeux en spécifiant les deux commutateurs.
4. Si vous ne spécifiez pas de commutateur, les deux ensembles sont collectés par défaut.

Paramètres

Paramètre	Descriptif
-DuréeMaximaleEnMinutes	Optionnel. Définit la durée de collecte avant expiration du délai d’attente. La valeur par défaut est de 5 minutes.
-LogDirectory	Optionnel. Répertoire dans lequel le fichier .etl doit être écrit. Par défaut, le fichier est créé sous le répertoire PowerShell du module. Le chemin d’accès complet s’affiche au démarrage de la session.
-CollectSdkEvents	Optionnel. Incluez les événements du Kit de développement logiciel (SDK) Application Insights.
-CollectRedfieldEvents	Optionnel. Incluez des événements de l’agent Application Insights et du runtime Redfield.
-Verbose	Paramètre commun. Génère des journaux détaillés.

Sortie

Exemple de journaux de démarrage d’application

Start-ApplicationInsightsMonitoringTrace -CollectRedfieldEvents
Starting...
Log File: C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\logs\20190627_144217_ApplicationInsights_ETW_Trace.etl
Tracing enabled, waiting for events.
Tracing will timeout in 5 minutes. Press CTRL+C to cancel.
2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Resolved variables to: MicrosoftAppInsights_ManagedHttpModulePath='C:\Program Files\WindowsPowerShell\Modules\Az.ApplicationMonitor\content\Runtime\Microsoft.ApplicationInsights.RedfieldIISModule.dll', MicrosoftAppInsights_ManagedHttpModuleType='Microsoft.ApplicationInsights.RedfieldIISModule.RedfieldIISModule'
2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Resolved variables to: MicrosoftDiagnosticServices_ManagedHttpModulePath2='', MicrosoftDiagnosticServices_ManagedHttpModuleType2=''
2:42:31 PM EVENT: Microsoft-ApplicationInsights-IIS-ManagedHttpModuleHelper Trace Environment variable 'MicrosoftDiagnosticServices_ManagedHttpModulePath2' or 'MicrosoftDiagnosticServices_ManagedHttpModuleType2' is null, skipping managed dll loading

Déployer l’agent Application Insights pour les machines virtuelles et les ensembles de machines virtuelles

Dans cette section

• Activer la supervision pour les machines virtuelles
• Activer la surveillance des ensembles de machines virtuelles

Activez Azure MonitorApplication Insights pour la surveillance via autoinstrumentation des applications hébergées sur Internet Information Server (IIS) et des applications ASP.NET et ASP.NET Core sur Azure Virtual Machines et Azure Virtual Machine Scale Sets.

Déployez l’agent Application Insights avec une extension de machine virtuelle. L’agent récupère automatiquement les mêmes signaux de dépendance que le Kit de développement logiciel (SDK). Utilisez PowerShell pour automatiser des déploiements à grande échelle.

Note

• Pour les applications Java, utilisez l’agent Application Insights Java 3.0 qui autocollectes les bibliothèques, frameworks, journaux et dépendances les plus populaires, ainsi que de nombreuses configurations othermes.
• Node.js et les applications Python s'exécutant sur des machines virtuelles Azure et Azure Virtual Machine Scale Sets ne prennent pas en charge l'autoinstrumentation. Utilisez la distribution Azure Monitor OpenTelemetry à la place.
• Pour surveiller les invités de machine virtuelle en plus des applications hébergées sur eux, consultez les données invitées de machine virtuelle.

Pour obtenir la liste complète des scénarios d’instrumentation automatique pris en charge, consultez Environnements, langages et fournisseurs de ressources pris en charge.

Activer la supervision pour les machines virtuelles

Vous pouvez utiliser le portail Azure ou PowerShell pour activer la surveillance des machines virtuelles.

Option 1 : portail Azure

1. Dans le portail Azure, accédez à votre ressource Application Insights. Copiez votre chaîne de connexion dans le Presse-papiers.

   

2. Accédez à votre machine virtuelle. Sous la section Paramètres dans le menu de gauche, sélectionnez Extensions + applications>Ajouter.

   

3. Sélectionnez Application Insights Agent>Suivant.

   

4. Collez le connection string que vous avez copié à l’étape 1, puis sélectionnez Review + create.

   

Option 2 : PowerShell

Note

Vous découvrez PowerShell ? Consultez le Guide de prise en main.

Installez ou mettez à jour l’agent Application Insights en tant qu’extension pour Azure machines virtuelles :

# define variables to match your environment before running
$ResourceGroup = "<myVmResourceGroup>"
$VMName = "<myVmName>"
$Location = "<myVmLocation>"
$ConnectionString = "<myAppInsightsResourceConnectionString>"

$publicCfgJsonString = @"
{
    "redfieldConfiguration": {
        "instrumentationKeyMap": {
        "filters": [
            {
            "appFilter": ".*",
            "machineFilter": ".*",
            "virtualPathFilter": ".*",
            "instrumentationSettings" : {
                "connectionString": "$ConnectionString"
            }
            }
        ]
        }
    }
    }
"@

$privateCfgJsonString = '{}'
    
Set-AzVMExtension -ResourceGroupName $ResourceGroup -VMName $VMName -Location $Location -Name "ApplicationMonitoringWindows" -Publisher "Microsoft.Azure.Diagnostics" -Type "ApplicationMonitoringWindows" -Version "2.8" -SettingString $publicCfgJsonString -ProtectedSettingString $privateCfgJsonString

Note

Pour les déploiements à grande échelle plus complexes, vous pouvez utiliser une boucle PowerShell pour installer ou mettre à jour l’extension Application Insights Agent sur plusieurs machines virtuelles.

Interrogez l’état de l’extension Application Insights Agent pour Azure machines virtuelles :

Get-AzVMExtension -ResourceGroupName "<myVmResourceGroup>" -VMName "<myVmName>" -Name ApplicationMonitoringWindows -Status

Obtenez la liste des extensions installées pour Azure machines virtuelles :

Get-AzResource -ResourceId "/subscriptions/<mySubscriptionId>/resourceGroups/<myVmResourceGroup>/providers/Microsoft.Compute/virtualMachines/<myVmName>/extensions"

Désinstallez l’extension Application Insights Agent de Azure machines virtuelles :

Remove-AzVMExtension -ResourceGroupName "<myVmResourceGroup>" -VMName "<myVmName>" -Name "ApplicationMonitoring"

Note

Vérifiez l’installation en sélectionnant Live Metrics Stream dans la ressource Application Insights associée au connection string que vous avez utilisé pour déployer l’extension Agent Application Insights. Si vous envoyez des données à partir de plusieurs machines virtuelles, sélectionnez la cible Azure machines virtuelles sous Nom du serveur. Il peut falloir jusqu'à une minute avant que le flux de données commence.

instrumentationKeyMap (paramètres d’extension)

Important

InstrumentationKeyMap est une fonctionnalité de routage avancée qui mappe les applications Internet Information Services (IIS) sur le même ordinateur aux ressources Application Insights. La fonctionnalité s'applique aux applications ASP.NET hébergées par IIS et aux applications ASP.NET Core que l'agent Application Insights configure automatiquement.

Fonctionnement de la correspondance

• La carte définit une liste ordonnée de règles nommées filters. La première règle de correspondance prend effet. Placez d'abord des règles spécifiques et terminez par une règle générale.
• Chaque règle peut affecter une ressource Application Insights différente aux applications correspondantes. Préférez les chaînes de connexion dans les scénarios pris en charge, car les clés d’instrumentation sont héritées.

Filtres disponibles

• MachineFilter ou machineFilter: expression régulière C# qui correspond au nom de l’ordinateur ou de la machine virtuelle. .* correspond à tous les prénoms.
• AppFilter ou appFilter: expression régulière C# qui correspond au nom du site IIS (HostingEnvironment.SiteName). Ce filtre est requis quand VirtualPathFilter ou virtualPathFilter n’est pas fourni.
• VirtualPathFilter ou virtualPathFilter: expression régulière C# qui correspond au chemin virtuel IIS (HostingEnvironment.ApplicationVirtualPath). Utilisez ce filtre pour cibler une application unique sous un site.

Mappage de terminologie

• Les applets de commande PowerShell utilisent MachineFilter, AppFilteret VirtualPathFilter.
• Le fichier JSON d’extension de machine virtuelle Azure et de Virtual Machine Scale Sets utilise machineFilter, appFilter et virtualPathFilter, et définit la ressource avec instrumentationSettings.

Conseil / Astuce

Incluez une règle finale qui correspond à toutes les applications, telles que .*, et appliquez une ressource par défaut pour rendre le comportement explicite.

Emplacement de l’extension pour les machines virtuelles et les Virtual Machine Scale Sets

Placez la carte sous redfieldConfiguration.instrumentationKeyMap.filters dans les paramètres publics de l'extension (-SettingString pour les machines virtuelles, -Setting pour Virtual Machine Scale Sets). Les noms des propriétés sont rédigés en minuscules. Définissez la ressource cible par règle avec instrumentationSettings.connectionString.

{
  "redfieldConfiguration": {
    "instrumentationKeyMap": {
      "filters": [
        {
          "machineFilter": ".*",
          "appFilter": ".*",
          "instrumentationSettings": {
            "connectionString": "<your-APPLICATIONINSIGHTS_CONNECTION_STRING>"
          }
        }
      ]
    }
  }
}

Activer la surveillance des ensembles de machines virtuelles

Vous pouvez utiliser le portail Azure ou PowerShell pour activer la surveillance des jeux d'échelles de machines virtuelles.

Option 1 : portail Azure

Suivez les étapes précédentes relatives aux machines virtuelles, mais accédez à vos ensembles de machines virtuelles plutôt qu'à votre machine virtuelle.

Option 2 : PowerShell

Installez ou mettez à jour l'agent Application Insights en tant qu'extension pour les ensembles de machines virtuelles.

# Set resource group, vmss name, and connection string to reflect your environment
$ResourceGroup = "<myVmResourceGroup>"
$VMSSName = "<myVmName>"
$ConnectionString = "<myAppInsightsResourceConnectionString>"
$publicCfgHashtable =
@{
  "redfieldConfiguration"= @{
    "instrumentationKeyMap"= @{
      "filters"= @(
        @{
          "appFilter"= ".*";
          "machineFilter"= ".*";
          "virtualPathFilter"= ".*";
          "instrumentationSettings" = @{
            "connectionString"= "$ConnectionString"
          }
        }
      )
    }
  }
};
$privateCfgHashtable = @{};
$vmss = Get-AzVmss -ResourceGroupName $ResourceGroup -VMScaleSetName $VMSSName
Add-AzVmssExtension -VirtualMachineScaleSet $vmss -Name "ApplicationMonitoringWindows" -Publisher "Microsoft.Azure.Diagnostics" -Type "ApplicationMonitoringWindows" -TypeHandlerVersion "2.8" -Setting $publicCfgHashtable -ProtectedSetting $privateCfgHashtable
Update-AzVmss -ResourceGroupName $vmss.ResourceGroupName -Name $vmss
# Note: Depending on your update policy, you might need to run Update-AzVmssInstance for each instance

Obtenir une liste des extensions installées pour des groupes de machines virtuelles identiques :

Get-AzResource -ResourceId "/subscriptions/<mySubscriptionId>/resourceGroups/<myResourceGroup>/providers/Microsoft.Compute/virtualMachineScaleSets/<myVmssName>/extensions"

Désinstaller l’extension de surveillance des applications sur des groupes de machines virtuelles identiques :

# set resource group and vmss name to reflect your environment
$vmss = Get-AzVmss -ResourceGroupName "<myResourceGroup>" -VMScaleSetName "<myVmssName>"
Remove-AzVmssExtension -VirtualMachineScaleSet $vmss -Name "ApplicationMonitoringWindows"
Update-AzVmss -ResourceGroupName $vmss.ResourceGroupName -Name $vmss.Name -VirtualMachineScaleSet $vmss
# Note: Depending on your update policy, you might need to run Update-AzVmssInstance for each instance

Résolution des problèmes

Pour connaître les étapes de résolution des problèmes dédiées, consultez Problèmes de déploiement de l’extension Application Insights Monitoring Agent pour les machines virtuelles et les groupes de machines virtuelles identiques.

Node.js

Conditions préalables

• Un abonnement Azure. Si vous n'en avez pas encore, créez un compte Azure gratuit.
• Ressource basée sur un espace de travail Application Insights.
• Application fonctionnelle.

Configurer la bibliothèque de client Node.js

Incluez le SDK dans votre application afin qu’il collecte des données.

1. Copiez la connection string de votre ressource à partir de votre nouvelle ressource. Application Insights utilise le connection string pour mapper les données à votre ressource Azure. Avant que le SDK puisse utiliser votre connection string, vous devez spécifier la connection string dans une variable d’environnement ou dans votre code.

   

2. Ajoutez la bibliothèque de client Node.js aux dépendances de votre application via package.json. À partir du dossier racine de votre application, exécutez :

   npm install applicationinsights --save
   

   Note

   Si vous utilisez TypeScript, n’installez pas de packages « typages » distincts. Ce package NPM contient de typages intégrés.

3. Chargez explicitement la bibliothèque dans votre code. Étant donné que le kit de développement logiciel (SDK) injecte l’instrumentation dans beaucoup d’autres bibliothèques, chargez-la dès que possible, même avant les autres instructions require.

   let appInsights = require('applicationinsights');
   

4. Vous pouvez également fournir un connection string via la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING, au lieu de le transmettre manuellement à setup() ou new appInsights.TelemetryClient(). Cela vous permet de conserver des chaînes de connexion en dehors du code source validé, ainsi que de spécifier des chaînes de connexion différentes selon les environnements. Pour configurer manuellement, appelez appInsights.setup('[your connection string]');.

   Pour des options de configuration supplémentaires, consultez les sections suivantes.

   Vous pouvez essayer le kit de développement logiciel (SDK) sans envoyer de télémétrie en définissant appInsights.defaultClient.config.disableAppInsights = true.

5. Commencez à collecter et à envoyer automatiquement des données en appelant appInsights.start();.

Note

Dans le cadre de l’utilisation de l’instrumentation Application Insights, nous collectons et envoyons des données de diagnostic à Microsoft. Ces données nous permettent d’exécuter et d’améliorer Application Insights. Vous avez la possibilité de désactiver la collecte de données nonessential. Pour plus d’informations, consultez le FAQ Application Insights.

Utilisation de base

Pour la collecte prête à l'emploi des requêtes HTTP, des événements populaires de bibliothèques tierces, des exceptions non gérées et des métriques système :

let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

Note

Si la connection string est définie dans la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING, .setup() peut être appelée sans argument. Cela facilite l’utilisation de différentes chaînes de connexion pour différents environnements.

Chargez la bibliothèque Application Insights require("applicationinsights") le plus tôt possible dans vos scripts avant de charger d’autres packages. Cette étape est nécessaire pour que la bibliothèque Application Insights puisse préparer des packages ultérieurs pour le suivi. Si vous rencontrez des conflits avec d’autres bibliothèques en procédant à une préparation similaire, essayez de charger la bibliothèque Application Insights par la suite.

En raison de la façon dont JavaScript gère les rappels, un travail supplémentaire est nécessaire pour effectuer le suivi d’une requête sur les dépendances externes et les rappels ultérieurs. Par défaut, ce suivi supplémentaire est activé. Désactivez-le en appelant setAutoDependencyCorrelation(false) comme décrit dans la section Configuration du SDK.

Migrer à partir de versions antérieures à 0.22

Il existe des changements majeurs entre les versions avant la version 0.22 et après. Ces changements sont conçus pour apporter une cohérence avec d’autres Kits de développement logiciel (SDK) Application Insights et permettre une extensibilité future.

En général, vous pouvez migrer avec les actions suivantes :

• Remplacez les références à appInsights.client par appInsights.defaultClient.
• Remplacez les références à appInsights.getClient() par new appInsights.TelemetryClient().
• Remplacez tous les arguments des méthodes client.track* par un objet unique contenant des propriétés nommées en tant qu’arguments. Consultez les indications de type intégré de l’IDE ou TelemetryTypes pour l’objet exempté et pour chaque type de données de télémétrie.

Si vous accédez aux fonctions de configuration du SDK sans les chaîner à appInsights.setup(), vous pouvez maintenant trouver ces fonctions dans appInsights.Configurations. par exemple appInsights.Configuration.setAutoCollectDependencies(true). Passez en revue les modifications apportées à la configuration par défaut dans la section suivante.

Vérifier que Application Insights reçoit des données de télémétrie

.NET

ASP.NET & ASP.NET Core

Exécutez votre application et lancez des requêtes. Les données de télémétrie doivent être transmis à Application Insights maintenant. Le kit de développement logiciel (SDK) Application Insights collecte automatiquement les requêtes web adressées à votre application, ainsi que les données de télémétrie suivantes.

Service Worker

Exécutez votre application. Les travailleurs de tous les exemples précédents effectuent un appel HTTP toutes les secondes vers bing.com et émettent également quelques journaux en utilisant ILogger. Ces lignes sont encapsulées à l’intérieur de l’appel StartOperation de TelemetryClient, qui est utilisé pour créer une opération. Dans cet exemple, RequestTelemetry est nommé « opération ».

Application Insights collecte ces journaux ILogger, avec une gravité d’Avertissement ou supérieure par défaut, et des dépendances. Ils sont corrélés à RequestTelemetry par une relation parent-enfant. La corrélation fonctionne également au-delà des limites de processus/réseau. Par exemple, si l’appel a été effectué à un autre composant surveillé, il est également corrélé à ce parent.

Cette opération RequestTelemetry personnalisée peut être considérée comme l’équivalent d’une requête web entrante dans une application web classique. Il n’est pas nécessaire d’utiliser une opération, mais elle convient le mieux au modèle de données de corrélation Application Insights. RequestTelemetry agit comme l’opération parente et toutes les données de télémétrie générées à l’intérieur de l’itération worker sont traitées comme appartenant logiquement à la même opération.

Cette approche garantit également que les données de télémétrie générées, à la fois automatiques et manuelles, ont la même operation_id. Étant donné que l’échantillonnage est basé sur operation_id, l’algorithme d’échantillonnage conserve ou supprime toutes les données de télémétrie d’une seule itération.

Node.js

Le Kit de développement logiciel (SDK) recueille automatiquement les données de télémétrie sur le runtime Node.js et certains modules tiers courants. Utilisez votre application pour générer certaines de ces données.

Ensuite, dans le portail Azure accédez à la ressource Application Insights que vous avez créée précédemment. Dans la Vue d’ensemble de la chronologie, cherchez vos premiers points de données. Pour voir plus de données détaillées, sélectionnez des composants différents dans les graphiques.

Pour visualiser la topologie découverte pour votre application, vous pouvez utiliser Cartographie d’application.

Pas de données

Comme le SDK regroupe par lots les données à envoyer, l’affichage des éléments dans le portail peut prendre un certain temps. Si les données n’apparaissent pas dans votre ressource, essayez ce qui suit :

• Continuez d’utiliser l’application. Prenez plus de mesures pour générer davantage de données de télémétrie.
• Sélectionnez Actualiser dans l’affichage des ressources du portail. Les graphiques s’actualisent périodiquement et automatiquement. Les actualiser manuellement les force à s’actualiser immédiatement.
• Vérifiez que les ports sortants requis sont ouverts.
• Utilisez la fonction Recherche pour chercher des événements spécifiques.
• Consultez les FAQ.

Collecte des données de télémétrie

.NET

Dans cette section

• Métriques temps réel
• Traces (journaux d’activité)
• Suivi distribué
• Dépendances
• Exceptions
• Métriques personnalisées
• Opérations personnalisées
• Compteurs
• Collecte d’instantanés

Métriques temps réel

Les métriques en direct peuvent être utilisées pour vérifier rapidement si la supervision de l’application avec Application Insights est correctement configurée. La télémétrie peut prendre quelques minutes pour apparaître dans le portail Azure, mais le volet des métriques actives affiche l’utilisation du processeur du processus en cours d’exécution en quasi-temps réel. Elle peut également afficher d’autres données de télémétrie comme les requêtes, les dépendances et les traces.

Note

Les métriques actives sont activées par défaut lorsque vous l’intégrez à l’aide des instructions recommandées pour les applications .NET.

Get started

1. Activez les métriques actives avec les kits SDK Application Insights en suivant les instructions spécifiques au langage :

   • ASP.NET : activé par défaut, mais peut également être activé manuellement à l’aide du code.
   • ASP.NET Core : activé par défaut, mais peut également être activé manuellement à l’aide du code.
   • .NET/.NET Core Console/Worker : activé par défaut.

2. Ouvrez la ressource Application Insights pour votre application dans le portail Azure. Sélectionnez Live Metrics répértorié sous Examiner dans le menu de gauche.

3. Sécurisez le canal de contrôle en activant l'authentification Microsoft Entra en cas d'utilisation de filtres personnalisés.

Fonctionnalités prises en charge

Language	Métriques de base	Mesures de performances	Filtrage personnalisé	Exemple de télémétrie	Répartition du CPU par processus
.NET Framework	Pris en charge (LTS)	Pris en charge (LTS)	Pris en charge (LTS)	Pris en charge (LTS)	Pris en charge (LTS)
.NET Core (target=.NET Framework)	Pris en charge (LTS)	Pris en charge (LTS)	Pris en charge (LTS)	Pris en charge (LTS)	Pris en charge (LTS)
.NET Core (target=.NET Core)	Pris en charge (LTS)	Supported*	Pris en charge (LTS)	Pris en charge (LTS)	Non pris en charge

Les métriques de base incluent les requêtes, les dépendances et le taux d’exceptions. Les métriques du niveau de performance (compteurs de performances) incluent la mémoire et l’UC. L’exemple de télémétrie montre un flux d’informations détaillées pour les demandes et les dépendances ayant échoué, les exceptions, les événements et les traces.

La prise en charge de PerfCounters varie légèrement entre les versions de .NET Core qui ne ciblent pas le framework .NET :

• Les métriques PerfCounters sont prises en charge lors de l’exécution dans Azure App Service pour Windows (ASP.NET Core SDK version 2.4.1 ou ultérieure).
• PerfCounters est pris en charge lorsque l’application s’exécute sur any Windows machine pour les applications qui ciblent .NET Core LTS ou version ultérieure.
• PerfCounters est pris en charge lorsque l’application exécute anywhere (par exemple, Linux, Windows, app service pour Linux ou conteneurs) dans les versions les plus récentes, mais uniquement pour les applications qui ciblent .NET Core LTS ou version ultérieure.

Activer les métriques actives à l’aide du code pour n’importe quelle application .NET

ASP.NET

Pour configurer manuellement les métriques en direct :

1. Installez le package NuGet Microsoft.ApplicationInsights.PerfCounterCollector.

2. L’exemple suivant de code d’application console illustre la configuration de métriques en direct :

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
using System;
using System.Threading.Tasks;

namespace LiveMetricsDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            // Create a TelemetryConfiguration instance.
            TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
            config.ConnectionString = "<YOUR-CONNECTION-STRING>";
            QuickPulseTelemetryProcessor quickPulseProcessor = null;
            config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
                .Use((next) =>
                {
                    quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
                    return quickPulseProcessor;
                })
                .Build();

            var quickPulseModule = new QuickPulseTelemetryModule();

            // Secure the control channel.
            // This is optional, but recommended.
            quickPulseModule.AuthenticationApiKey = "<YOUR-API-KEY>";
            quickPulseModule.Initialize(config);
            quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

            // Create a TelemetryClient instance. It is important
            // to use the same TelemetryConfiguration here as the one
            // used to set up live metrics.
            TelemetryClient client = new TelemetryClient(config);

            // This sample runs indefinitely. Replace with actual application logic.
            while (true)
            {
                // Send dependency and request telemetry.
                // These will be shown in live metrics.
                // CPU/Memory Performance counter is also shown
                // automatically without any additional steps.
                client.TrackDependency("My dependency", "target", "http://sample",
                    DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
                client.TrackRequest("My Request", DateTimeOffset.Now,
                    TimeSpan.FromMilliseconds(230), "200", true);
                Task.Delay(1000).Wait();
            }
        }
    }
}

ASP.NET Core

Pour configurer manuellement les métriques en direct :

1. Installez le package NuGet Microsoft.ApplicationInsights.PerfCounterCollector.

2. L’exemple suivant de code d’application console illustre la configuration de métriques en direct :

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.ConnectionString = "<YOUR-CONNECTION-STRING>";
QuickPulseTelemetryProcessor quickPulseProcessor = null;
config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
    .Use((next) =>
    {
        quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
        return quickPulseProcessor;
    })
    .Build();

var quickPulseModule = new QuickPulseTelemetryModule();

// Secure the control channel.
// This is optional, but recommended.
quickPulseModule.AuthenticationApiKey = "<YOUR-API-KEY>";
quickPulseModule.Initialize(config);
quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

// Create a TelemetryClient instance. It is important
// to use the same TelemetryConfiguration here as the one
// used to set up live metrics.
TelemetryClient client = new TelemetryClient(config);

// This sample runs indefinitely. Replace with actual application logic.
while (true)
{
    // Send dependency and request telemetry.
    // These will be shown in live metrics.
    // CPU/Memory Performance counter is also shown
    // automatically without any additional steps.
    client.TrackDependency("My dependency", "target", "http://sample",
        DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
    client.TrackRequest("My Request", DateTimeOffset.Now,
        TimeSpan.FromMilliseconds(230), "200", true);
    Task.Delay(1000).Wait();
}

L’exemple précédent concerne une application console, mais le même code peut être utilisé dans n’importe quelle application .NET.

Important

Si d’autres modules de télémétrie sont activés pour la télémétrie automatique, vérifiez que la même configuration utilisée pour initialiser ces modules est utilisée pour le module de métriques actives.

Note

La configuration par défaut permet de collecter les journaux ILoggerWarning et des journaux de gravité supérieure. Pour plus d’informations, consultez Comment personnaliser la collection de journaux ILogger ?

Service Worker

Les journaux émis via ILogger avec la gravité Avertissement ou supérieur sont automatiquement capturés. Pour modifier ce comportement, remplacez explicitement la configuration de journalisation du fournisseur ApplicationInsights, comme indiqué dans le code suivant. La configuration suivante permet à Application Insights de capturer tous les journaux Information et ceux de gravité supérieure.

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Il est important de noter que l’exemple suivant n’entraîne pas le fournisseur Application Insights à capturer les logs Information. Il ne la capture pas, car le kit de développement logiciel (SDK) ajoute un filtre de journalisation par défaut qui indique à ApplicationInsights de capturer uniquement les journaux Warning de gravité supérieure. Application Insights nécessite un remplacement explicite.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Note

Application Insights respecte les niveaux de journal configurés via ConfigureLogging(...) dans le code. Si seule appsettings.json est utilisée et que ConfigureLogging n’est pas remplacé explicitement, le niveau de journal par défaut est Avertissement.

Pour plus d’informations, suivez les documents ILogger pour personnaliser les niveaux de journalisation capturés par Application Insights.

Traces (journaux d’activité)

Cette section explique comment envoyer des journaux de suivi de diagnostic à partir de ASP.NET ou de ASP.NET Core applications à Application Insights, puis explorer/rechercher ces journaux dans le portail.

Vous pouvez utiliser les journaux de suivi pour identifier les traces associées à chaque demande utilisateur et les mettre en corrélation avec d’autres événements et rapports d’exception.

Application Insights capture les journaux d’activité à partir de ASP.NET Core et d’autres applications .NET via ILogger, et à partir de ASP.NET classiques (.NET Framework) via le Kit de développement logiciel (SDK) et les adaptateurs classiques.

Note

• Par défaut, le fournisseur Application Insights envoie uniquement les journaux dont la gravité est égale ou supérieure à Warning. Pour inclure Information ou les journaux de niveau inférieur, mettez à jour les paramètres du niveau des journaux dans appsettings.json.

• Le Microsoft.ApplicationInsights.WorkerService package NuGet, utilisé pour activer Application Insights pour les services d'arrière-plan, est hors du cadre.

• Pour consulter les questions fréquemment posées (FAQ), consultez Logging avec .NET FAQ.

Installer la journalisation sur votre application

ASP.NET

Choisissez une approche de journalisation pour émettre des journaux de diagnostic que Application Insights peut collecter.

Pour les applications ASP.NET classiques qui utilisent le tracé System.Diagnostics, configurez un Application Insights TraceListener dans le fichier de configuration.

Ajoutez un écouteur à web.config ou app.config:

<configuration>
  <system.diagnostics>
    <trace>
      <listeners>
        <add name="myAppInsightsListener"
             type="Microsoft.ApplicationInsights.TraceListener.ApplicationInsightsTraceListener, Microsoft.ApplicationInsights.TraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

Note

Le module de capture de journal est un adaptateur utile pour les enregistreurs d’événements tiers. Toutefois, si vous n’utilisez pas déjà NLog, log4Net ou System.Diagnostics.Trace, envisagez d’appeler Application Insights TrackTrace() directement.

Configurer Application Insights pour collecter des journaux de suivi

Option 1 : Ajoutez Application Insights à votre projet si vous ne l’avez pas déjà fait. Lors de l’ajout d’Application Insights dans Visual Studio, une option permet d’inclure le collecteur de journaux.

Option 2 : Cliquez avec le bouton droit sur votre projet dans Solution Explorer pour Configure Application Insights. Sélectionnez l’option Configurer la collecte de traces .

Note

Si vous ne disposez pas du menu Application Insights ou de l’option collecteur de logs, reportez-vous à l’article dédié de dépannage.

ASP.NET Core

Le Kit de développement logiciel (SDK) Application Insights pour ASP.NET Core collecte déjà les journaux ILogger par défaut. Si vous utilisez le Kit de développement logiciel (SDK), vous n’avez généralement pas besoin d’appeler builder.Logging.AddApplicationInsights(), et vous pouvez ne pas tenir compte des instructions d’installation ILogger suivantes.

Si vous avez uniquement besoin du transfert de journaux et non de la pile de données de télémétrie complète, vous pouvez utiliser le Microsoft.Extensions.Logging.ApplicationInsights package fournisseur pour capturer les journaux.

Installation manuelle

Utilisez cette méthode si votre type de projet n’est pas pris en charge par le programme d’installation d’Application Insights (par exemple, certains scénarios de bureau/console) ou si vous préférez un contrôle explicite au niveau du package.

1. Dans Solution Explorer, cliquez avec le bouton droit sur votre projet, puis sélectionnez Manage des packages NuGet.

2. Recherchez Application Insights.

3. Sélectionnez l’un des packages suivants :

   • ILogger : NuGet iLogger bannerMicrosoft.Extensions.Logging.ApplicationInsights
   • System.Diagnostics : NuGet System.Diagnostics bannerMicrosoft.ApplicationInsights.TraceListener
   • log4net : Microsoft.ApplicationInsights.Log4NetAppenderNuGet Log4Net banner
   • NLog: Microsoft.ApplicationInsights.NLogTarget
   • Microsoft.ApplicationInsights.EventSourceListener
   • Microsoft.ApplicationInsights.DiagnosticSourceListener
   • Bannière Microsoft.ApplicationInsights.EtwCollector

Le package NuGet installe les assemblys nécessaires et modifie web.config ou app.config, le cas échéant.

Instructions d’installation :

Note

Cliquez pour développer une des sections ci-dessous afin d'obtenir des instructions d'installation spécifiques au paquet.

ILogger

1. Installez le Microsoft.Extensions.Logging.ApplicationInsights.

2. Ajouter ApplicationInsightsLoggerProvider:

using Microsoft.Extensions.Logging.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Logging.AddApplicationInsights(
        configureTelemetryConfiguration: (config) => 
            config.ConnectionString = builder.Configuration.GetConnectionString("APPLICATIONINSIGHTS_CONNECTION_STRING"),
            configureApplicationInsightsLoggerOptions: (options) => { }
    );

builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("your-category", LogLevel.Trace);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Lorsque le package NuGet est installé et que le fournisseur est inscrit avec l’injection de dépendances, l’application est prête pour la journalisation. Avec l’injection de constructeur, ILogger ou l’alternative de type générique ILogger<TCategoryName> est requis. Lorsque ces implémentations sont résolues, ApplicationInsightsLoggerProvider les fournit. Les messages enregistrés ou les exceptions sont envoyés à Application Insights.

Considérez l’exemple de contrôleur suivant :

public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

Pour plus d’informations, consultez Logging dans ASP.NET Core et Quel type de télémétrie Application Insights est généré à partir des journaux ILogger ? Où puis-je voir les journaux ILogger dans Application Insights ?.

Insérer des appels de journaux de diagnostic (System.Diagnostics.Trace / log4net / NLog)

Si vous utilisez System.Diagnostics.Trace, un appel classique serait :

System.Diagnostics.Trace.TraceWarning("Slow response - database01");

Si vous préférez log4net ou NLogutilisez :

    logger.Warn("Slow response - database01");

Utiliser les événements de EventSource

Vous pouvez configurer les événements System.Diagnostics.Tracing.EventSource à envoyer à Application Insights en tant que traces.

1. Installez le package NuGet Microsoft.ApplicationInsights.EventSourceListener.

2. Modifiez la TelemetryModules section du fichier ApplicationInsights.config :

       <Add Type="Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule, Microsoft.ApplicationInsights.EventSourceListener">
         <Sources>
           <Add Name="MyCompany" Level="Verbose" />
         </Sources>
       </Add>
   

Pour chaque source, vous pouvez définir les paramètres suivants :

• Le nom spécifie le nom de l’EventSource à collecter.
• Level spécifie le niveau de journalisation à collecter : Critique, Erreur, Informational, LogAlways, Verbose ou Warning.
• Les mots clés (facultatif) spécifient la valeur entière des combinaisons de mots clés à utiliser.

Utiliser des événements DiagnosticSource

Vous pouvez configurer les événements System.Diagnostics.DiagnosticSource à envoyer à Application Insights en tant que traces.

1. Installez le package NuGet Microsoft.ApplicationInsights.DiagnosticSourceListener.

2. Modifiez la TelemetryModules section du fichier ApplicationInsights.config :

       <Add Type="Microsoft.ApplicationInsights.DiagnosticSourceListener.DiagnosticSourceTelemetryModule, Microsoft.ApplicationInsights.DiagnosticSourceListener">
         <Sources>
           <Add Name="MyDiagnosticSourceName" />
         </Sources>
       </Add>
   

Pour chaque source de diagnostic que vous souhaitez tracer, ajoutez une entrée avec l’attribut Name défini sur le nom de votre source de diagnostic.

Utiliser des événements ETW

Vous pouvez configurer les événements de suivi pour Windows (ETW) pour envoyer à Application Insights sous forme de traces.

1. Installez le package NuGet Microsoft.ApplicationInsights.EtwCollector.

2. Modifiez la section « TelemetryModules » du fichier ApplicationInsights.config :

Note

Les événements ETW ne peuvent être collectés que si le processus qui héberge le Kit de développement logiciel (SDK) s’exécute sous une identité membre des utilisateurs ou administrateurs du journal des performances.

    <Add Type="Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule, Microsoft.ApplicationInsights.EtwCollector">
      <Sources>
        <Add ProviderName="MyCompanyEventSourceName" Level="Verbose" />
      </Sources>
    </Add>

Pour chaque source, vous pouvez définir les paramètres suivants :

• ProviderName est le nom du fournisseur ETW à collecter.
• ProviderGuid spécifie le GUID du fournisseur ETW à collecter. Il peut être utilisé au lieu de ProviderName.
• Level définit le niveau de journalisation à collecter. Ce niveau peut être Critical, Error, Informational, LogAlways, Verbose ou Warning.
• Les mots clés (facultatif) définissent la valeur entière des combinaisons de mots clés à utiliser.

Utiliser directement l’API Trace

Vous pouvez appeler directement l’API de trace Application Insights. Les adaptateurs de journalisation utilisent cette API. Par exemple:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow response - database01");

Un avantage de TrackTrace est que vous pouvez intégrer des données relativement longues dans le message. Par exemple, vous pouvez encoder les données POST là-bas.

Vous pouvez également ajouter un niveau de gravité à votre message. Et, comme d’autres données de télémétrie, vous pouvez ajouter des valeurs de propriété pour filtrer ou rechercher différents ensembles de traces. Par exemple:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow database response",
                            SeverityLevel.Warning,
                            new Dictionary<string, string> { { "database", "db.ID" } });

À présent, vous pouvez facilement filtrer dans La recherche tous les messages d’un niveau de gravité particulier lié à une base de données particulière.

Application console

Pour ajouter la journalisation Application Insights aux applications console, installez d’abord les packages NuGet suivants :

• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.Extensions.DependencyInjection

L’exemple suivant utilise le Microsoft.Extensions.Logging.ApplicationInsights package et illustre le comportement par défaut pour une application console. Le Microsoft.Extensions.Logging.ApplicationInsights package doit être utilisé dans une application console ou chaque fois que vous souhaitez une implémentation minimale d’Application Insights sans l’ensemble complet de fonctionnalités telles que les métriques, le suivi distribué, l’échantillonnage et les initialiseurs de télémétrie.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

using var channel = new InMemoryChannel();

try
{
    IServiceCollection services = new ServiceCollection();
    services.Configure<TelemetryConfiguration>(config => config.TelemetryChannel = channel);
    services.AddLogging(builder =>
    {
        // Only Application Insights is registered as a logger provider
        builder.AddApplicationInsights(
            configureTelemetryConfiguration: (config) => config.ConnectionString = "<YourConnectionString>",
            configureApplicationInsightsLoggerOptions: (options) => { }
        );
    });

    IServiceProvider serviceProvider = services.BuildServiceProvider();
    ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

    logger.LogInformation("Logger is working...");
}
finally
{
    // Explicitly call Flush() followed by Delay, as required in console apps.
    // This ensures that even if the application terminates, telemetry is sent to the back end.
    channel.Flush();

    await Task.Delay(TimeSpan.FromMilliseconds(1000));
}

Pour plus d’informations, consultez le type de télémétrie Application Insights généré à partir des journaux ILogger ? Où puis-je voir les journaux ILogger dans Application Insights ?.

Étendues de journalisation

Note

Les instructions suivantes s’appliquent aux scénarios ILogger (ASP.NET Core et console uniquement). Cela ne s'applique pas à ASP.NET classique.

ApplicationInsightsLoggingProvider prend en charge les étendues de journal, qui sont activées par défaut.

Si l’étendue est de type IReadOnlyCollection<KeyValuePair<string,object>>, chaque paire clé/valeur de la collection est ajoutée à la télémétrie Application Insights en tant que propriétés personnalisées. Dans l’exemple suivant, les journaux sont capturés en tant que TraceTelemetry et comportent ("MyKey", "MyValue") dans les propriétés.

using (_logger.BeginScope(new Dictionary<string, object> { ["MyKey"] = "MyValue" }))
{
    _logger.LogError("An example of an Error level message");
}

Si un autre type est utilisé comme étendue, il est stocké sous la propriété Scope dans la télémétrie Application Insights. Dans l’exemple suivant, TraceTelemetry a une propriété appelée Scope qui contient l’étendue.

using (_logger.BeginScope("hello scope"))
{
    _logger.LogError("An example of an Error level message");
}

Rechercher vos journaux de bord

Exécutez votre application en mode débogage ou déployez-la en direct.

Explorer dans la recherche

Dans le volet vue d’ensemble de votre application dans le portail Application Insights, sélectionnez Rechercher où vous pouvez :

• Filtrez sur les traces de journal ou sur les éléments avec des propriétés spécifiques.
• Inspectez un élément spécifique en détail.
• Recherchez d’autres données de journal système qui concernent la même requête utilisateur (a le même ID d’opération).
• Enregistrez la configuration d’une page en tant que favori.

Note

Si votre application envoie de grandes quantités de données et que vous utilisez le Kit de développement logiciel (SDK) Application Insights pour ASP.NET version 2.0.0-beta3 ou ultérieure, la fonctionnalité d'échantillonnage adaptée peut fonctionner et envoyer uniquement une partie de vos données de télémétrie. En savoir plus sur l’échantillonnage.

Explorer dans les journaux Azure Monitor

Les journaux ILogger apparaissent comme de la télémétrie de type trace (table traces dans Application Insights et AppTraces dans Log Analytics).

Exemple

Dans le portail Azure, accédez à Application Insights et exécutez :

traces
| where severityLevel >= 2 // 2=Warning, 1=Information, 0=Verbose
| take 50

Suivi distribué

Les architectures de cloud et de microservices modernes ont activé des services simples et déployables indépendamment qui réduisent les coûts tout en augmentant la disponibilité et le débit. Toutefois, il a rendu les systèmes globaux plus difficiles à raisonner et à déboguer. Le suivi distribué résout ce problème en fournissant un profileur de performances qui fonctionne comme des piles d’appels pour les architectures cloud et microservices.

Azure Monitor fournit deux expériences pour consommer des données de trace distribuées : les diagnostics de transaction pour une seule transaction/requête et la vue application pour montrer comment les systèmes interagissent.

Application Insights peut surveiller chaque composant séparément et détecter le composant responsable des défaillances ou de la dégradation des performances à l’aide de la corrélation de télémétrie distribuée. Cet article explique le modèle de données, les techniques de propagation de contexte, les protocoles et l’implémentation de tactiques de corrélation sur différents langages et plateformes utilisés par Application Insights.

Activer le suivi distribué grâce à Application Insights via l'autoinstrumentation ou les SDK.

Les agents et kits SDK Application Insights pour .NET, .NET Core, Java, Node.jset JavaScript prennent tous en charge le suivi distribué en mode natif.

Une fois que le SDK Application Insights approprié est installé et configuré, les informations de suivi sont automatiquement collectées pour les infrastructures, bibliothèques et technologies populaires par les sélecteurs automatiques de dépendances du SDK. La liste complète des technologies prises en charge est disponible dans la documentation sur la collecte automatique des dépendances.

Toute technologie peut également être suivie manuellement avec un appel à TrackDependency sur TelemetryClient.

Modèle de données pour la corrélation de télémétrie

Application Insights définit un modèle de données pour la corrélation de télémétrie distribuée. Pour associer la télémétrie à une opération logique, chaque élément de télémétrie a un champ de contexte appelé operation_Id. Chaque élément de télémétrie dans la trace distribuée partage cet identificateur. Ainsi, même si vous perdez des données de télémétrie d’une seule couche, vous pouvez toujours associer des données de télémétrie signalées par d’autres composants.

Une opération logique distribuée se compose généralement d’un ensemble d’opérations plus petites qui sont des requêtes traitées par l’un des composants. La télémétrie de requête définit ces opérations. Chaque élément de télémétrie de requête possède son propre id, qui l'identifie de façon unique et globale. Par ailleurs, tous les éléments de télémétrie (comme les traces et les exceptions) associés à la requête doivent définir le operation_parentId sur la valeur de l’id de la requête.

La télémétrie des dépendances représente chaque opération sortante, telle qu’un appel HTTP à un autre composant. Il définit également son propre id qui est globalement unique. La télémétrie des requêtes, lancée par cet appel de dépendances, utilise cet id comme operation_parentId.

Vous pouvez créer une vue de l’opération logique distribuée à l’aide de operation_Id, operation_parentId et request.id avec dependency.id. Ces champs définissent également l’ordre de causalité des appels de télémétrie.

Dans un environnement de microservices, les traces des composants peuvent accéder à différents éléments de stockage. Chaque composant peut avoir sa propre connection string dans Application Insights. Pour obtenir des données de télémétrie pour l’opération logique, Application Insights interroge les données de chaque élément de stockage.

Lorsque le nombre d'objets de stockage est élevé, vous avez besoin d'un indicateur sur l'endroit où chercher ensuite. Le modèle de données Application Insights définit deux champs pour résoudre ce problème : request.source et dependency.target. Le premier champ identifie le composant qui a lancé la demande de dépendance. Le deuxième champ identifie le composant qui a retourné la réponse de l’appel de dépendance.

Pour plus d'informations sur l'interrogation à partir de plusieurs instances disparates, consultez l'interrogation des données dans les espaces de travail, les applications et les ressources de Log Analytics dans Azure Monitor.

Exemple

Intéressons-nous à un exemple. Une application appelée Cours boursiers affiche le cours actuel du marché d’une action à l’aide d’une API externe appelée Stock. L’application Stock Prices a une page appelée Page Stock que le navigateur web client ouvre à l’aide de GET /Home/Stock. L’application interroge l’API Stock à l’aide de l’appel GET /api/stock/valueHTTP.

Vous pouvez analyser les données de télémétrie résultantes en exécutant une requête :

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

Dans les résultats, tous les éléments de télémétrie partagent la racine operation_Id. Lorsqu’un appel Ajax est effectué à partir de la page, un nouvel ID unique (qJSXU) est affecté à la télémétrie des dépendances et l’ID du pageView est utilisé comme operation_ParentId. La demande de serveur utilise ensuite l’ID Ajax comme operation_ParentId.

type d'article	nom	ID	operation_ParentId	identifiant_opération
pageView	Page de gestion des stocks	STYz		STYz
dépendance	GET /Home/Stock	qJSXU	STYz	STYz
request	GET Home/Stock	KqKwlrSt9PA=	qJSXU	STYz
dépendance	GET /api/stock/value	bBrf2L7mm2g=	KqKwlrSt9PA=	STYz

Lorsque l’appel GET /api/stock/value est effectué auprès d’un service externe, vous devez connaître l’identité de ce serveur afin de pouvoir définir le dependency.target champ de manière appropriée. Lorsque le service externe ne prend pas en charge la surveillance, target est défini sur le nom d’hôte du service. par exemple stock-prices-api.com. Toutefois, si le service s’identifie en retournant un en-tête HTTP prédéfini, target contient l’identité de service qui permet à Application Insights de générer une trace distribuée en interrogeant les données de télémétrie à partir de ce service.

En-têtes de corrélation à l’aide de W3C TraceContext

Application Insights passe au contexte de trace W3C, qui définit :

• traceparent: porte l’ID d’opération global unique et l’identificateur unique de l’appel.
• tracestate: Transporte le contexte de traçage spécifique au système.

La dernière version du Kit de développement logiciel (SDK) Application Insights prend en charge le protocole Trace-Context, mais vous devrez peut-être y participer. (La compatibilité descendante avec le protocole de corrélation précédent pris en charge par le Kit de développement logiciel (SDK) Application Insights est maintenue.)

Le protocole HTTP de corrélation, également appelé Request-Id, est déconseillé. Ce protocole définit deux en-têtes :

• Request-Id: porte l’ID global unique de l’appel.
• Correlation-Context: contient la collection de couples nom-valeur associée aux propriétés de trace distribuée.

Application Insights définit également l’extension pour le protocole HTTP de corrélation. Il utilise des paires nom-valeur Request-Context pour propager la collection de propriétés utilisée par l’appelant ou l’appelé. Le Kit de développement logiciel (SDK) Application Insights utilise cet en-tête pour définir les champs dependency.target et request.source.

Les modèles de données W3C Trace-Context et Application Insights sont mappés de la manière suivante :

Application Insights	W3C TraceContext (Contexte de trace W3C)
Id de Request et Dependency	parent-id
Operation_Id	trace-id
Operation_ParentId	parent-id de l’étendue parente de cette étendue. Ce champ doit être vide s’il s’agit d’une étendue racine.

Pour plus d’informations, consultez le modèle de données de télémétrie Application Insights.

Activer la prise en charge du suivi distribué W3C

Le suivi distribué basé sur W3C TraceContext est activé par défaut dans tous les kits de développement logiciel (SDK) récents .NET Framework/.NET Core, ainsi que la compatibilité descendante avec le protocole Request-Id hérité.

Corrélation des données de télémétrie

La corrélation est gérée par défaut lors de l’intégration d’une application. Aucune action spéciale n’est nécessaire.

.NET runtime prend en charge la distribution à l’aide de Activity et DiagnosticSource

Le SDK Application Insights .NET utilise DiagnosticSource et Activity pour collecter et mettre en corrélation les données de télémétrie.

Dépendances

Dépendances suivies automatiquement

Les sdk Application Insights pour .NET et .NET Core sont fournis avec DependencyTrackingTelemetryModule, qui est un module de télémétrie qui collecte automatiquement les dépendances. Le module DependencyTrackingTelemetryModule est expédié sous forme de package NuGet Microsoft.ApplicationInsights.DependencyCollector et est ajouté automatiquement lorsque vous utilisez le package NuGet Microsoft.ApplicationInsights.Web ou Microsoft.ApplicationInsights.AspNetCore.

Actuellement, DependencyTrackingTelemetryModule suit automatiquement les dépendances suivantes :

Dépendances	Détails
HTTP/HTTPS	Appels HTTP/HTTPS locaux ou distants.
Appels WCF	Suivi automatique uniquement si les liaisons HTTP sont utilisées.
SQL	Appels effectués avec SqlClient. Consultez la section Suivi SQL avancé pour obtenir la requête SQL complète pour capturer des requêtes SQL.
Stockage Blob Azure, Stockage Table ou Stockage File d’attente	Appels effectués avec le client Azure Storage.
Client SDK Azure Event Hubs	Utilisez le dernier package : https://nuget.org/packages/Azure.Messaging.EventHubs.
Kit de développement logiciel (SDK) client Azure Service Bus	Utilisez le dernier package : https://nuget.org/packages/Azure.Messaging.ServiceBus.
Azure Cosmos DB	Suivi automatique si HTTP/HTTPS est utilisé. Le suivi des opérations en mode direct avec TCP est capturé automatiquement à l’aide du package d’aperçu >= 3.33.0-preview. Pour plus de détails, visitez la documentation.

Si la dépendance n’est pas collectée automatiquement, vous pouvez la suivre manuellement avec un appel de suivi des dépendances.

Pour plus d’informations sur le fonctionnement du suivi des dépendances, consultez Suivi des dépendances dans Application Insights.

Comment fonctionne le suivi automatique des dépendances ?

• L'instrumentation du bytecode s'applique autour des méthodes sélectionnées à l'aide de InstrumentationEngine, et elle est activée via StatusMonitor ou l'extension Application Insights pour Azure App Service.

• Les rappels EventSource sont utilisés pour capturer les données de télémétrie des bibliothèques .NET qui émettent des événements structurés.

• Les rappels DiagnosticSource sont utilisés dans les SDK .NET et .NET Core plus récents pour collecter les données de télémétrie des bibliothèques qui prennent en charge le suivi distribué.

Configurer le suivi automatique des dépendances dans les applications console

Pour suivre automatiquement les dépendances à partir d’applications console .NET, installez le package NuGet Microsoft.ApplicationInsights.DependencyCollector et initialisez DependencyTrackingTelemetryModule :

    DependencyTrackingTelemetryModule depModule = new DependencyTrackingTelemetryModule();
    depModule.Initialize(TelemetryConfiguration.Active);

Note

Pour les applications console .NET Core, TelemetryConfiguration.Active est obsolète.

Suivi manuel des dépendances

Les exemples de dépendances suivants ne sont pas collectés automatiquement et nécessitent un suivi manuel :

• Azure Cosmos DB est suivi automatiquement uniquement si HTTP/HTTPS est utilisé. Le mode TCP n’est pas capturé automatiquement par Application Insights pour les versions du kit de développement logiciel (SDK) antérieures à 2.22.0-Beta1.
• Redis

Pour les dépendances qui ne sont pas collectées automatiquement par le SDK, vous pouvez les suivre manuellement en utilisant l'API TrackDependency utilisée par les modules de collecte automatique standard.

Exemple

Si vous construisez votre code avec un assemblée que vous n'avez pas écrit vous-même, vous pouvez chronométrer tous les appels à celui-ci. Ce scénario vous permet de déterminer la contribution qu’elle apporte à vos temps de réponse.

Pour afficher ces données dans les graphiques de dépendance d’Application Insights, envoyez-les en utilisant TrackDependency :

    var startTime = DateTime.UtcNow;
    var timer = System.Diagnostics.Stopwatch.StartNew();
    try
    {
        // making dependency call
        success = dependency.Call();
    }
    finally
    {
        timer.Stop();
        telemetryClient.TrackDependency("myDependencyType", "myDependencyCall", "myDependencyData", startTime, timer.Elapsed, success);
    }

Vous pouvez aussi utiliser les méthodes d’extension TelemetryClient et StartOperation fournies par StopOperation pour suivre les dépendances manuellement, comme cela est expliqué dans Suivi des dépendances sortantes.

Désactivation du module de suivi des dépendances standard

Pour plus d’informations, consultez Modules de télémétrie.

Suivi SQL avancé pour obtenir la requête SQL complète

Pour les appels SQL, le nom du serveur et de la base de données est toujours collecté et stocké comme nom du fichier DependencyTelemetry collecté. Un autre champ, appelé data, peut contenir le texte de la requête SQL complète.

Note

Azure Functions nécessite des paramètres distincts pour activer la collection de texte SQL. Pour plus d’informations, consultez Activer la collecte de requêtes SQL.

ASP.NET

Pour les applications ASP.NET, le texte de requête SQL complet est collecté à l’aide de l’instrumentation du code d’octet, ce qui nécessite l’utilisation du moteur d’instrumentation ou l’utilisation du Microsoft.Data.SqlClient package NuGet au lieu de la bibliothèque System.Data.SqlClient. Les étapes spécifiques à la plateforme pour activer la collecte complète de requêtes SQL sont décrites dans le tableau suivant.

Platform	Étapes nécessaires pour obtenir la requête SQL complète
Web Apps dans Azure App Service	Dans le panneau de configuration de votre application web, ouvrez le volet Application Insights et activez les commandes SQL sous .NET.
Serveur IIS (Azure Virtual Machines, local, et ainsi de suite)	Utilisez le package NuGet Microsoft.Data.SqlClient ou le module PowerShell Agent Application Insights pour installer le moteur d’instrumentation et redémarrer IIS.
Azure Cloud Services	Ajoutez une tâche de démarrage pour installer StatusMonitor. Votre application doit être intégrée au Kit de développement logiciel (SDK) ApplicationInsights au moment de la génération en installant des packages NuGet pour ASP.NET ou des applications ASP.NET Core.
IIS Express	Utilisez le package NuGet Microsoft.Data.SqlClient.
Tâches web dans Azure App Service	Utilisez le package NuGet Microsoft.Data.SqlClient.

En plus des étapes spécifiques à la plateforme ci-dessus, vous devez également choisir explicitement d’activer la collecte de commandes SQL en modifiant le fichier ApplicationInsights.config avec le code suivant :

<TelemetryModules>
  <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
    <EnableSqlCommandTextInstrumentation>true</EnableSqlCommandTextInstrumentation>
  </Add>

ASP.NET Core

Pour les applications ASP.NET Core, il est nécessaire d'activer la collecte SQL Text en utilisant :

services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module. EnableSqlCommandTextInstrumentation = true; });

Dans les cas ci-dessus, la bonne pratique pour vérifier que ce moteur d’instrumentation est correctement installé est de vous assurer que la version du SDK du DependencyTelemetry collecté est rddp. L’utilisation de dépendances rdddsd ou rddf indique que les dépendances sont collectées via des rappels DiagnosticSource ou EventSource, la requête SQL complète n’est donc pas capturée.

Exceptions

Les exceptions dans les applications Web peuvent être signalées avec Application Insights. Vous pouvez associer les demandes ayant échoué à des exceptions et à d’autres événements sur le client et le serveur, ce qui vous permet de diagnostiquer rapidement les causes. Dans cette section, vous apprenez à configurer la création de rapports d’exceptions, à signaler des exceptions explicitement, à diagnostiquer les défaillances, etc.

Configurer les rapports d’exceptions

Vous pouvez configurer Application Insights pour signaler les exceptions qui se produisent dans le serveur ou le client. En fonction de la plateforme dont dépend votre application, vous avez besoin de l’extension ou du kit de développement logiciel (SDK) appropriés.

Server-side

Pour que les exceptions soient signalées à partir de votre application côté serveur, tenez compte des scénarios suivants :

• Ajoutez l’extension Application Insights pour les applications web Azure.
• Ajoutez l’extension Application Monitoring pour les machines virtuelles Azure et les ensembles de machines virtuelles Azure hébergeant des applications IIS.
• Ajoutez le SDK Application Insights à votre code d'application, exécutez l'Agent Application Insights pour les serveurs web IIS, ou activez l'Agent Java pour les applications web Java.

Client-side

Le Kit de développement logiciel (SDK) JavaScript offre la possibilité de générer des rapports côté client sur les exceptions qui se produisent dans des navigateurs web. Pour configurer la création de rapports d’exceptions sur le client, consultez Application Insights pour pages web.

Infrastructures d’application

Avec certaines infrastructures d’application, une configuration supplémentaire est requise. Considérez les technologies suivantes :

• Formulaires web
• MVC
• API web 1.*
• API web 2.*
• WCF

Important

Cette section se concentre sur les applications .NET Framework à partir d’un exemple de code. Certaines des méthodes qui fonctionnent pour .NET Framework sont obsolètes dans le Kit de développement logiciel (SDK) .NET Core.

Diagnostiquer les défaillances et les exceptions

portail Azure

Application Insights est fourni avec une expérience Application Performance Management organisée pour vous aider à diagnostiquer les échecs dans les applications surveillées.

Pour obtenir des instructions détaillées, consultez Examiner les défaillances, le niveau de performance et les transactions avec Application Insights.

Visual Studio

1. Ouvrez la solution d’application dans Visual Studio. Exécutez l’application sur votre serveur ou sur votre ordinateur de développement à l’aide de la touche F5. Recréez l’exception.

2. Ouvrez la fenêtre de télémétrie Application Insights dans Visual Studio. Pendant le débogage, sélectionnez la liste déroulante Application Insights.

3. Sélectionnez un rapport d’exception pour afficher son arborescence des appels de procédure. Pour ouvrir le fichier de code approprié, sélectionnez une référence de ligne dans l’arborescence des appels de procédure.

   Si CodeLens est activé, vous voyez des données sur les exceptions :

   

Suivi personnalisé et données du journal

Pour obtenir des données de diagnostic propres à votre application, vous pouvez insérer le code pour envoyer vos propres données de télémétrie. Vos données de télémétrie ou de journal personnalisées sont affichées dans la recherche de diagnostic en même temps que la requête, la vue de page et d’autres données collectées automatiquement.

À l’aide de Microsoft.VisualStudio.ApplicationInsights.TelemetryClient, vous avez plusieurs API disponibles :

• TelemetryClient.TrackEvent sert généralement à surveiller les modèles d’utilisation, mais les données qu’il envoie apparaissent également sous Événements personnalisés dans Recherche de diagnostic. Les événements sont nommés et peuvent contenir des propriétés de type chaîne et des métriques numériques sur lesquels vous pouvez filtrer vos recherches de diagnostic.
• TelemetryClient.TrackTrace vous permet d’envoyer des données plus longues telles que des informations POST.
• TelemetryClient.TrackException envoie les détails de l’exception, tels que les arborescences des appels de procédure, à Application Insights.

Pour afficher ces événements, dans le menu de gauche, ouvrez Recherche. Sélectionnez le menu déroulant Types d’événements, puis choisissez Événement personnalisé, Trace ou Exception.

Note

Si votre application génère de grandes quantités de données de télémétrie, le module d’échantillonnage adaptatif réduit automatiquement le volume envoyé au portail en envoyant uniquement une fraction représentative des événements. Les événements qui font partie de la même opération sont sélectionnés ou désélectionnés en tant que groupe afin que vous puissiez naviguer entre les événements liés. Pour plus d’informations, consultez l’article Échantillonnage dans Application Insights.

Afficher les données POST de requête

Les détails de la demande n'incluent pas les données envoyées à votre application dans un appel POST. Pour que ces données soient signalées :

• Ajoutez le kit de développement logiciel (SDK) Application Insights au code de votre application.
• Insérez du code dans votre application pour appeler Microsoft.ApplicationInsights.TrackTrace(). Envoyez les données POST dans le paramètre du message. Étant donné qu’il existe une limite à la taille autorisée, vous deviez essayer de n’envoyer que les données essentielles.
• Lorsque vous examinez une demande ayant échoué, recherchez les traces associées.

Capturer les exceptions et les données de diagnostic connexes

Par défaut, toutes les exceptions qui provoquent des défaillances dans votre application apparaissent dans le portail. Si vous utilisez le kit de développement logiciel (SDK) JavaScript dans vos pages web, vous voyez des exceptions de navigateur. Toutefois, la plupart des exceptions côté serveur sont interceptées par IIS. Vous devez donc ajouter du code pour les capturer et les signaler.

Vous pouvez:

• Enregistrer explicitement des exceptions en insérant le code dans les gestionnaires d'exceptions pour signaler ces exceptions.
• Capturez automatiquement les exceptions en configurant votre framework ASP.NET. Les ajouts nécessaires sont différents selon les différents types d’infrastructure.

Signaler explicitement des exceptions

La façon la plus simple de signaler consiste à insérer un appel à trackException() dans un gestionnaire d’exceptions.

C#

var telemetry = new TelemetryClient();

try
{
    // ...
}
catch (Exception ex)
{
    var properties = new Dictionary<string, string>
    {
        ["Game"] = currentGame.Name
    };

    var measurements = new Dictionary<string, double>
    {
        ["Users"] = currentGame.Users.Count
    };

    // Send the exception telemetry:
    telemetry.TrackException(ex, properties, measurements);
}

JavaScript

try
{
    // ...
}
catch (ex)
{
    appInsights.trackException(ex, "handler loc",
    {
        Game: currentGame.Name,
        State: currentGame.State.ToString()
    });
}

Les paramètres de propriétés et de mesures sont facultatifs, mais sont utiles pour filtrer et ajouter des informations supplémentaires. Par exemple, si vous avez une application qui peut exécuter plusieurs jeux, vous pouvez trouver les rapports d’exception liés à un jeu particulier. Vous pouvez ajouter autant d’éléments que vous le souhaitez à chaque dictionnaire.

Exceptions du navigateur

La plupart des exceptions de navigateur sont signalées.

Si votre page web inclut des fichiers de script à partir de réseaux de distribution de contenu ou d’autres domaines, vérifiez que votre balise de script possède l’attribut crossorigin="anonymous"et que le serveur envoie des en-têtes CORS. Ce comportement vous permet d’obtenir une trace de pile et des détails pour les exceptions JavaScript non gérées à partir de ces ressources.

Réutiliser votre client de télémétrie

Note

Nous vous recommandons d’instancier le TelemetryClient une fois, et de le réutiliser tout au long de la vie d’une application.

Avec Dependency Injection (DI) dans .NET, le KIT de développement logiciel (SDK) .NET approprié et la configuration correcte d’Application Insights pour DI, vous pouvez exiger l'TelemetryClient en tant que paramètre de constructeur.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

    public ExampleController(TelemetryClient telemetryClient)
    {
        _telemetryClient = telemetryClient;
    }
}

Dans l’exemple précédent, TelemetryClient est injecté dans la classe ExampleController.

Formulaires web

Pour les formulaires web, le module HTTP est en mesure de collecter les exceptions lorsqu’aucune redirection n’est configurée avec CustomErrors. Cependant, quand vous avez des redirections actives, ajoutez les lignes suivantes à la fonction Application_Error dans Global.asax.cs.

void Application_Error(object sender, EventArgs e)
{
    if (HttpContext.Current.IsCustomErrorEnabled &&
        Server.GetLastError () != null)
    {
        _telemetryClient.TrackException(Server.GetLastError());
    }
}

Dans l’exemple précédent, _telemetryClient est une variable de portée de classe de type TelemetryClient.

MVC

À partir de la version 2.6 (version bêta 3 et versions ultérieures) du Kit de développement logiciel (SDK) web d’Application Insights, Application Insights collecte automatiquement les exceptions non prises en charge qui sont levées dans les méthodes des contrôleurs MVC 5+. Si vous avez précédemment ajouté un gestionnaire personnalisé pour suivre ces exceptions, vous pouvez le supprimer pour empêcher le double suivi des exceptions.

Il existe plusieurs scénarios dans lesquels un filtre d’exception ne peut pas gérer correctement les erreurs quand des exceptions sont levées :

• À partir de constructeurs de contrôleur.
• À partir de gestionnaires de messages.
• Lors du routage.
• Lors de la sérialisation du contenu de la réponse.
• Lors du démarrage de l’application.
• Dans des tâches en arrière-plan.

Toutes les exceptions prises en charge par l’application doivent toujours faire l’objet d’un suivi manuel. Les exceptions non prises en charge provenant de contrôleurs aboutissent généralement à une réponse « Erreur interne du serveur » 500. Si cette réponse est construite manuellement à la suite d’une exception prise en charge (ou d’aucune exception), elle est suivie dans la télémétrie de la demande correspondante avec le ResultCode 500. Toutefois, le Kit de développement logiciel (SDK) Application Insights n’est pas en mesure de suivre l’exception associée.

Prise en charge des versions antérieures

Si vous utilisez MVC 4 (ou une version antérieure) du Kit SDK web 2.5 d’Application Insights (ou une version antérieure), référez-vous aux exemples suivants pour effectuer le suivi des exceptions.

Développer pour afficher les instructions pour les versions antérieures

Si la configuration CustomErrors est Off, les exceptions sont disponibles pour être collectées par le module HTTP. Toutefois, si elle est définie sur RemoteOnly (par défaut) ou On, l’exception est effacée et n’est pas disponible pour que Application Insights la collecte automatiquement. Vous pouvez corriger ce comportement en substituant la classe System.Web.Mvc.HandleErrorAttribute et en appliquant la classe substituée comme indiqué pour les différentes versions de MVC ici (voir la source GitHub) :

using System;
using System.Web.Mvc;
using Microsoft.ApplicationInsights;

namespace MVC2App.Controllers
{
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)]
    public class AiHandleErrorAttribute : HandleErrorAttribute
    {
        public override void OnException(ExceptionContext filterContext)
        {
            if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
            {
                //The attribute should track exceptions only when CustomErrors setting is On
                //if CustomErrors is Off, exceptions will be caught by AI HTTP Module
                if (filterContext.HttpContext.IsCustomErrorEnabled)
                {   //Or reuse instance (recommended!). See note above.
                    var ai = new TelemetryClient();
                    ai.TrackException(filterContext.Exception);
                }
            }
            base.OnException(filterContext);
        }
    }
}

MVC 2

Remplacez l’attribut HandleError par votre nouvel attribut dans vos contrôleurs :

    namespace MVC2App.Controllers
    {
        [AiHandleError]
        public class HomeController : Controller
        {
            // Omitted for brevity
        }
    }

Exemple

MVC 3

Enregistrez AiHandleErrorAttribute en tant que filtre global dans Global.asax.cs :

public class MyMvcApplication : System.Web.HttpApplication
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        filters.Add(new AiHandleErrorAttribute());
    }
}

Exemple

MVC 4, MVC 5

Enregistrez AiHandleErrorAttribute en tant que filtre global dans Global.asax.cs :

public class FilterConfig
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        // Default replaced with the override to track unhandled exceptions
        filters.Add(new AiHandleErrorAttribute());
    }
}

Exemple

API Web

À partir de la version 2.6 (bêta 3 et versions ultérieures) du Kit de développement logiciel (SDK) web d’Application Insights, Application Insights collecte automatiquement les exceptions non prises en charge qui sont levées dans les méthodes de contrôleurs pour l’API Web 2+. Si vous avez précédemment ajouté un gestionnaire personnalisé pour suivre ces exceptions, comme décrit dans les exemples suivants, vous pouvez le supprimer pour empêcher le double suivi des exceptions.

Il existe des cas que les filtres d’exception ne peuvent pas gérer. Par exemple:

• Les exceptions lancées à partir des constructeurs de contrôleur.
• Les exceptions lancées à partir des gestionnaires de messages.
• Les exceptions lancées pendant le routage.
• Les exceptions lancées pendant la sérialisation du contenu de réponse.
• Exception levée lors du démarrage d’application.
• Exception levée dans les tâches en arrière-plan.

Toutes les exceptions prises en charge par l’application doivent toujours faire l’objet d’un suivi manuel. Les exceptions non prises en charge provenant de contrôleurs aboutissent généralement à une réponse « Erreur interne du serveur » 500. Si une telle réponse est construite manuellement à la suite d’une exception prise en charge (ou d’aucune exception), elle est suivie dans la télémétrie de la demande correspondante avec le ResultCode 500. Toutefois, le Kit de développement logiciel (SDK) Application Insights n’est pas en mesure de suivre une exception associée.

Prise en charge des versions antérieures

Si vous utilisez l’API Web 1 (ou une version antérieure) du Kit SDK web 2.5 d’Application Insights (ou une version antérieure), référez-vous aux exemples suivants pour effectuer le suivi des exceptions.

Développer pour afficher les instructions pour les versions antérieures

API Web 1.x

Écrasez System.Web.Http.Filters.ExceptionFilterAttribute :

using System.Web.Http.Filters;
using Microsoft.ApplicationInsights;

namespace WebAPI.App_Start
{
    public class AiExceptionFilterAttribute : ExceptionFilterAttribute
    {
    public override void OnException(HttpActionExecutedContext actionExecutedContext)
    {
        if (actionExecutedContext != null && actionExecutedContext.Exception != null)
        {  //Or reuse instance (recommended!). See note above.
            var ai = new TelemetryClient();
            ai.TrackException(actionExecutedContext.Exception);
        }
        base.OnException(actionExecutedContext);
    }
    }
}

Vous pouvez ajouter cet attribut remplacé à des contrôleurs spécifiques ou l’ajouter à la configuration du filtre global dans la classe WebApiConfig :

using System.Web.Http;
using WebApi1.x.App_Start;

namespace WebApi1.x
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });
    
            // ...
            config.EnableSystemDiagnosticsTracing();
    
            // Capture exceptions for Application Insights:
            config.Filters.Add(new AiExceptionFilterAttribute());
        }
    }
}

Exemple

API Web 2.x

Ajoutez une implémentation de IExceptionLogger :

using System.Web.Http.ExceptionHandling;
using Microsoft.ApplicationInsights;

namespace ProductsAppPureWebAPI.App_Start
{
    public class AiExceptionLogger : ExceptionLogger
    {
        public override void Log(ExceptionLoggerContext context)
        {
            if (context != null && context.Exception != null)
            {
                //or reuse instance (recommended!). see note above
                var ai = new TelemetryClient();
                ai.TrackException(context.Exception);
            }
            base.Log(context);
        }
    }
}

Ajoutez cet extrait de code aux services dans WebApiConfig :

using System.Web.Http;
using System.Web.Http.ExceptionHandling;
using ProductsAppPureWebAPI.App_Start;

namespace WebApi2WithMVC
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // Web API configuration and services
    
            // Web API routes
            config.MapHttpAttributeRoutes();
    
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });

            config.Services.Add(typeof(IExceptionLogger), new AiExceptionLogger());
        }
    }
}

Exemple

Alternativement, vous pouvez :

• Remplacez la seule instance ExceptionHandler par une implémentation personnalisée de IExceptionHandler. Ce gestionnaire d’exceptions est appelé uniquement lorsque l’infrastructure est toujours en mesure de choisir le message de réponse à envoyer, mais pas quand la connexion est abandonnée, par exemple.
• Utilisez des filtres d’exception, comme décrit dans la section précédente sur les contrôleurs de l’API Web 1.x, qui ne sont pas appelés dans tous les cas.

WCF

Ajoutez une classe qui étend Attribute et implémente IErrorHandler et IServiceBehavior.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.ServiceModel.Description;
    using System.ServiceModel.Dispatcher;
    using System.Web;
    using Microsoft.ApplicationInsights;

    namespace WcfService4.ErrorHandling
    {
      public class AiLogExceptionAttribute : Attribute, IErrorHandler, IServiceBehavior
      {
        public void AddBindingParameters(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase,
            System.Collections.ObjectModel.Collection<ServiceEndpoint> endpoints,
            System.ServiceModel.Channels.BindingParameterCollection bindingParameters)
        {
        }

        public void ApplyDispatchBehavior(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
            foreach (ChannelDispatcher disp in serviceHostBase.ChannelDispatchers)
            {
                disp.ErrorHandlers.Add(this);
            }
        }

        public void Validate(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
        }

        bool IErrorHandler.HandleError(Exception error)
        {//or reuse instance (recommended!). see note above
            var ai = new TelemetryClient();

            ai.TrackException(error);
            return false;
        }

        void IErrorHandler.ProvideFault(Exception error,
            System.ServiceModel.Channels.MessageVersion version,
            ref System.ServiceModel.Channels.Message fault)
        {
        }
      }
    }

Ajoutez l'attribut aux implémentations de service :

namespace WcfService4
{
    [AiLogException]
    public class Service1 : IService1
    {
        // Omitted for brevity
    }
}

Exemple

Compteurs de performance des exceptions

Si vous avez installé l'agent Azure Monitor Application Insights sur votre serveur, vous pouvez obtenir un graphique du taux d'exceptions mesuré par .NET. Les exceptions de .NET gérées et non gérées sont incluses.

Ouvrez un onglet Metrics Explorer et ajoutez un nouveau graphique. Sous Compteurs de performances, sélectionnez Taux d’exception.

L’infrastructure .NET calcule le taux en comptant le nombre d’exceptions dans un intervalle et en divisant la longueur de l’intervalle.

Ce nombre sera différent du nombre d’« exceptions » calculé par le portail Application Insights, qui est basé sur les rapports TrackException. Les intervalles d’échantillonnage sont différents et le Kit de développement logiciel (SDK) n’envoie pas de rapports TrackException pour toutes les exceptions gérées et non gérées.

Collecte de métriques personnalisée

Les kits de développement logiciel (SDK) Application Insights .NET Azure Monitor et .NET Core ont deux méthodes différentes de collecte de métriques personnalisées :

• La méthode TrackMetric(), qui n’a pas de préagrégation.
• La méthode GetMetric(), qui a une préagrégation.

Nous vous recommandons d’utiliser l’agrégation, donc TrackMetric()n’est plus la méthode préférée de collecte de métriques personnalisée. Cet article vous guide dans l'utilisation de la méthode GetMetric() et vous expliquera son fonctionnement.

Développez pour en savoir plus sur l’API de préagrégation par rapport à celle de non préagrégation

La méthode TrackMetric() envoie des données de télémétrie brutes indiquant une métrique. L’envoi d’un seul élément de télémétrie pour chaque valeur n’est pas efficace. La méthode TrackMetric() est également inefficace en termes de performances, car chaque TrackMetric(item) transite par le pipeline de SDK complet des initialiseurs et des processeurs de télémétrie.

Contrairement à TrackMetric(), GetMetric() gère la pré-agrégation locale pour vous et envoie ensuite seulement une métrique récapitulative agrégée à un intervalle fixe d’une minute. Si vous avez besoin de superviser étroitement une métrique personnalisée au niveau de la seconde ou même de la milliseconde, vous pouvez le faire tout en n’encourant que le coût de stockage et de trafic réseau de la supervision à intervalle d’une minute. Ce comportement réduit aussi considérablement le risque de limitation, car le nombre total d’éléments de télémétrie à envoyer pour une métrique agrégée est fortement réduit.

Dans Application Insights, les métriques personnalisées collectées par le biais de TrackMetric() et GetMetric() ne sont pas soumises à l’échantillonnage. L’échantillonnage des métriques importantes peut entraîner des scénarios où les alertes générées autour de ces métriques ne sont pas fiables. En n’échantillonnant jamais vos métriques personnalisées, vous pouvez généralement être sûr que quand vos seuils d’alerte sont enfreints, une alerte se déclenche. Parce que les métriques personnalisées ne sont pas échantillonnées, il existe des problèmes potentiels.

Le suivi des tendances dans une métrique chaque seconde, ou à un intervalle encore plus détaillé, peut secondes, ou à un intervalle encore plus granulaire, peut entraîner :

• Une augmentation des coûts de stockage de données. Il existe un coût associé à la quantité de données que vous envoyez à Azure Monitor. Plus vous envoyez de données, plus le coût global de supervision est élevé.
• Une augmentation du trafic réseau ou une surcharge de performance. Dans certains scénarios, cette surcharge peut avoir des conséquences en termes de performances d’application et un coût financier.
• Un risque de limitation de l’ingestion. Azure Monitor supprime (« limite ») des points de données quand votre application envoie un taux de télémétrie élevé dans un court laps de temps.

La limitation constitue une préoccupation car elle peut entraîner un non-signalement des alertes. La condition nécessaire au déclenchement d’une alerte peut se produire localement, puis être supprimée au point de terminaison d’ingestion en raison d’un trop grand nombre de données envoyées. Nous vous déconseillons d'utiliser TrackMetric() pour .NET et .NET Core, sauf si vous avez implémenté votre propre logique d'agrégation locale. Si vous essayez de suivre chaque occurrence d’un événement sur une période donnée, vous constaterez peut-être que TrackEvent() est plus adaptée. Toutefois, n’oubliez pas que contrairement aux métriques personnalisées, les événements personnalisés sont soumis à l’échantillonnage. Vous pouvez néanmoins toujours utiliser TrackMetric() même sans écrire votre propre pré-agrégation locale. Mais si vous le faites, soyez conscient des pièges.

En résumé, nous recommandons GetMetric(), car elle effectue une pré-agrégation : elle accumule les valeurs de tous les appels de Track() et envoie un résumé/agrégat une fois par minute. La méthode GetMetric() peut réduire considérablement le coût et l'impact sur les performances en envoyant moins de points de données, tout en recueillant néanmoins toutes les informations pertinentes.

Bien démarrer avec GetMetric

Pour nos exemples, nous allons utiliser une application de service worker de base .NET Core 3.1. Si vous souhaitez répliquer l’environnement de test utilisé avec ces exemples, suivez les étapes 1 à 6 sous .NET application Core Worker Service. Ces étapes permettent d'ajouter Application Insights à un modèle de projet de service worker de base. Ces concepts s’appliquent à toute application générale dans laquelle le SDK peut être utilisé, notamment les applications web et les applications de console.

Envoyer des mesures

Remplacez le contenu de votre fichier worker.cs par le code suivant :

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.ApplicationInsights;

namespace WorkerService3
{
    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;
        private TelemetryClient _telemetryClient;

        public Worker(ILogger<Worker> logger, TelemetryClient tc)
        {
            _logger = logger;
            _telemetryClient = tc;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {   // The following line demonstrates usages of GetMetric API.
            // Here "computersSold", a custom metric name, is being tracked with a value of 42 every second.
            while (!stoppingToken.IsCancellationRequested)
            {
                _telemetryClient.GetMetric("ComputersSold").TrackValue(42);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(1000, stoppingToken);
            }
        }
    }
}

Lorsque vous exécutez l’exemple de code, vous voyez la boucle while à plusieurs reprises s’exécutant sans télémétrie envoyée dans la fenêtre de sortie Visual Studio. Un seul élément de télémétrie est envoyé aux environs de la marque des 60 secondes, qui, dans notre test, se présente comme suit :

Application Insights Telemetry: {"name":"Microsoft.ApplicationInsights.Dev.00000000-0000-0000-0000-000000000000.Metric", "time":"2019-12-28T00:54:19.0000000Z",
"ikey":"00000000-0000-0000-0000-000000000000",
"tags":{"ai.application.ver":"1.0.0.0",
"ai.cloud.roleInstance":"Test-Computer-Name",
"ai.internal.sdkVersion":"m-agg2c:2.12.0-21496",
"ai.internal.nodeName":"Test-Computer-Name"},
"data":{"baseType":"MetricData",
"baseData":{"ver":2,"metrics":[{"name":"ComputersSold",
"kind":"Aggregation",
"value":1722,
"count":41,
"min":42,
"max":42,
"stdDev":0}],
"properties":{"_MS.AggregationIntervalMs":"42000",
"DeveloperMode":"true"}}}}

Cet élément de télémétrie unique représente une agrégation de 41 mesures de métriques distinctes. Puisque nous envoyions sans cesse la même valeur, nous avons un écart type (stDev) de 0 avec des valeurs maximale (max) et minimale (min) identiques. La propriété value représente une somme de toutes les valeurs individuelles qui ont été agrégées.

Note

La méthode GetMetric ne prend pas en charge le suivi de la dernière valeur (par exemple, gauge) ou le suivi des histogrammes ou des distributions.

Si nous examinons notre ressource Application Insights dans l’expérience Logs (Analytics), l’élément de télémétrie individuel ressemblerait à la capture d'écran suivante.

Note

Si l’élément de télémétrie brut ne contenait pas de champ ou de propriété de somme explicite une fois ingéré, nous en créons un pour vous. En l’occurrence, la propriété value et valueSum représentent la même chose.

Vous pouvez également accéder à vos données de télémétrie de métriques personnalisées dans la section Métriques du portail, à la fois en tant que métrique personnalisée et basée sur un journal. La capture d’écran suivante est un exemple de métrique basée sur un journal.

Référence de métrique de mise en cache pour une utilisation à haut débit

Des valeurs métriques peuvent être observées fréquemment dans certains cas. Par exemple, un service à haut débit qui traite 500 requêtes par seconde peut vouloir émettre 20 métriques de télémétrie pour chaque requête. Le résultat signifie qu’il faut effectuer le suivi de 10 000 valeurs par seconde. Dans de tels scénarios à haut débit, les utilisateurs peuvent avoir besoin d'aider le kit de développement logiciel (SDK) en évitant certaines recherches.

Par exemple, l’exemple ci-dessus a effectué une recherche pour un descripteur pour la métrique ComputersSold, puis a suivi une valeur observée 42. Au lieu de cela, le descripteur peut être mis en cache pour plusieurs appels de suivi :

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is where the cache is stored to handle faster lookup
            Metric computersSold = _telemetryClient.GetMetric("ComputersSold");
            while (!stoppingToken.IsCancellationRequested)
            {

                computersSold.TrackValue(42);

                computersSold.TrackValue(142);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

Outre la mise en cache du descripteur de métrique, l’exemple ci-dessus a également réduit Task.Delay à 50 millisecondes, de sorte que la boucle s’exécute plus fréquemment. Le résultat est 772 TrackValue() appels.

Métriques multidimensionnelles

Les exemples de la section précédente présentent des métriques à zéro dimension. Les métriques peuvent également être multidimensionnelles. Nous prenons actuellement en charge jusqu’à 10 dimensions.

Voici un exemple qui illustre comment créer une métrique unidimensionnelle :

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is an example of a metric with a single dimension.
            // FormFactor is the name of the dimension.
            Metric computersSold= _telemetryClient.GetMetric("ComputersSold", "FormFactor");

            while (!stoppingToken.IsCancellationRequested)
            {
                // The number of arguments (dimension values)
                // must match the number of dimensions specified while GetMetric.
                // Laptop, Tablet, etc are values for the dimension "FormFactor"
                computersSold.TrackValue(42, "Laptop");
                computersSold.TrackValue(20, "Tablet");
                computersSold.TrackValue(126, "Desktop");


                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

L’exécution de l’exemple de code pendant au moins 60 secondes entraîne l’envoi de trois éléments de télémétrie distincts à Azure. Chaque élément représente l’agrégation de l’un des trois facteurs de forme. Comme auparavant, vous pouvez les examiner plus en détail dans la vue Logs (Analytics) :

Dans l'explorateur de métriques :

Remarquez que vous ne pouvez pas diviser la métrique en fonction de votre nouvelle dimension personnalisée, ni afficher votre dimension personnalisée avec la vue des métriques.

Par défaut, les métriques multidimensionnelles dans l’explorateur de métriques ne sont pas activées dans les ressources Application Insights.

Activer les métriques multidimensionnelles

Pour activer les métriques multidimensionnelles pour une ressource Application Insights, sélectionnez Utilisation et estimation des coûts>Métriques personnalisées>Activer les alertes sur les dimensions des métriques personnalisées>OK. Pour plus d’informations, consultez Dimensions de métriques personnalisées et pré-agrégation.

Après avoir effectué cette modification et envoyé de nouvelles données de télémétrie multidimensionnelles, vous pouvez sélectionner Appliquer le fractionnement.

Note

Seules les métriques envoyées après l’activation de la fonctionnalité dans le portail auront des dimensions stockées.

Affichez vos agrégations de métriques pour chaque FormFactor dimension.

Utilisez MetricIdentifier lorsqu'il y a plus de trois dimensions

Actuellement, 10 dimensions sont supportées. L’utilisation de plus de trois dimensions nécessite l’utilisation de MetricIdentifier:

// Add "using Microsoft.ApplicationInsights.Metrics;" to use MetricIdentifier
// MetricIdentifier id = new MetricIdentifier("[metricNamespace]","[metricId],"[dim1]","[dim2]","[dim3]","[dim4]","[dim5]");
MetricIdentifier id = new MetricIdentifier("CustomMetricNamespace","ComputerSold", "FormFactor", "GraphicsCard", "MemorySpeed", "BatteryCapacity", "StorageCapacity");
Metric computersSold = _telemetryClient.GetMetric(id);
computersSold.TrackValue(110,"Laptop", "Nvidia", "DDR4", "39Wh", "1TB");

Configuration de métrique personnalisée

Si vous souhaitez modifier la configuration des métriques, vous devez apporter des modifications à l'endroit où la métrique est initialisée.

Noms de dimensions spéciales

Les métriques n’utilisent pas le contexte de télémétrie du TelemetryClient utilisé pour y accéder. Utiliser des noms de dimension spéciaux disponibles comme constantes dans la MetricDimensionNames classe est la meilleure solution de contournement pour cette limitation.

Les agrégats de métriques envoyés par la métrique suivante Special Operation Request Sizen’auront pas Context.Operation.Name défini sur Special Operation. La méthode TrackMetric() ou toute autre méthode TrackXXX() aura OperationName correctement défini sur Special Operation.

        //...
        TelemetryClient specialClient;
        private static int GetCurrentRequestSize()
        {
            // Do stuff
            return 1100;
        }
        int requestSize = GetCurrentRequestSize()

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                //...
                specialClient.Context.Operation.Name = "Special Operation";
                specialClient.GetMetric("Special Operation Request Size").TrackValue(requestSize);
                //...
            }
                   
        }

Dans cette situation, utilisez les noms de dimensions spéciales listés dans la classe MetricDimensionNames pour spécifier des valeurs TelemetryContext.

Par exemple, quand l’agrégation de métriques résultant de l’instruction suivante est envoyé au point de terminaison cloud Application Insights, son champ de données Context.Operation.Name est défini sur Special Operation :

_telemetryClient.GetMetric("Request Size", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation");

La valeur de cette dimension spéciale est copiée et TelemetryContext n’est pas utilisé comme dimension normale. Si vous souhaitez également conserver une dimension d’opération pour l’exploration normale des métriques, vous devez créer une dimension distincte à cet effet :

_telemetryClient.GetMetric("Request Size", "Operation Name", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation", "Special Operation");

Limitation des dimensions et des séries chronologiques

Pour empêcher que le sous-système de télémétrie n’utilise accidentellement vos ressources, vous pouvez contrôler la quantité maximale de séries de données par métrique. Les limites par défaut sont un maximum de 1 000 séries de données au total par métrique, et un maximum de 100 valeurs différentes par dimension.

Important

Utilisez des valeurs cardinales faibles pour les dimensions afin d’éviter la limitation.

Dans le contexte de la limitation des séries chronologiques et des dimensions, nous utilisons Metric.TrackValue(..) pour nous assurer que les limites sont respectées. Si les limites sont déjà atteintes, Metric.TrackValue(..) retourne False et la valeur n’est pas suivie. Sinon, Trueest retourné. Ce comportement est utile si les données d’une métrique proviennent d’une entrée d’utilisateur.

Le constructeur MetricConfiguration accepte certaines options relatives à la façon de gérer différentes séries au sein de la métrique et un objet d’une classe implémentant IMetricSeriesConfiguration qui spécifie le comportement d’agrégation pour chaque série de la métrique :

var metConfig = new MetricConfiguration(seriesCountLimit: 100, valuesPerDimensionLimit:2,
                new MetricSeriesConfigurationForMeasurement(restrictToUInt32Values: false));

Metric computersSold = _telemetryClient.GetMetric("ComputersSold", "Dimension1", "Dimension2", metConfig);

// Start tracking.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value1");
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value2");

// The following call gives 3rd unique value for dimension2, which is above the limit of 2.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3");
// The above call doesn't track the metric, and returns false.

• seriesCountLimit est la quantité maximale de séries chronologiques de données qu’une métrique peut contenir. Lorsque cette limite atteinte, les appels à TrackValue() qui aboutissent normalement à une nouvelle série renvoient false.
• valuesPerDimensionLimit limite le nombre de valeurs distinctes par dimension d’une manière similaire.
• restrictToUInt32Values détermine si seules les valeurs entières non négatives doivent être suivies.

Voici un exemple qui illustre comment envoyer un message pour savoir si les limites sont dépassées :

if (! computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3"))
{
// Add "using Microsoft.ApplicationInsights.DataContract;" to use SeverityLevel.Error
_telemetryClient.TrackTrace("Metric value not tracked as value of one of the dimension exceeded the cap. Revisit the dimensions to ensure they are within the limits",
SeverityLevel.Error);
}

Suivi des opérations personnalisé

Les SDK Application Insights effectuent automatiquement le suivi des appels et demandes HTTP entrants à des services dépendants, par exemple, des requêtes HTTP ou des requêtes SQL. Le suivi et la corrélation des demandes et des dépendances vous offrent une meilleure visibilité de la réactivité et de la fiabilité de l’application entière sur l’ensemble des micro-services qui combinent cette application.

Il existe une classe de modèles d’application qui ne peuvent pas être pris en charge de façon générique. La surveillance appropriée de ces modèles requiert une instrumentation manuelle du code. Cet article traite de quelques modèles qui peuvent requérir une instrumentation manuelle, tels que le traitement de file d’attente personnalisé et l’exécution de tâches en arrière-plan à long terme.

Cet article fournit des conseils sur la façon d’effectuer le suivi d’opérations personnalisées avec le kit de développement logiciel (SDK) Application Insights.

Aperçu

Une opération est un élément de travail logique exécuté par une application. Il a un nom, une heure de début, une durée, un résultat et un contexte d’exécution tel qu’un nom d’utilisateur, des propriétés et un résultat. Si l’opération A a été initiée par l’opération B, l’opération B est alors définie en tant que parent pour A. Une opération ne peut avoir qu’un seul parent, mais il peut avoir de nombreuses opérations enfants. Pour plus d’informations sur les opérations et la corrélation de télémétrie, consultez Corrélation de télémétrie d’Application Insights.

Dans le Kit de développement logiciel (SDK) Application Insights .NET, l’opération est décrite par la classe abstraite OperationTelemetry et ses descendants RequestTelemetry et DependencyTelemetry.

Suivi des opérations entrantes

Le Kit de développement logiciel (SDK) web Application Insights collecte automatiquement les requêtes HTTP pour les applications ASP.NET qui s’exécutent dans un pipeline IIS et toutes les applications ASP.NET Core. Il existe des solutions prises en charge par la communauté pour les autres plateformes et infrastructures. Si l’application n’est prise en charge par aucune solution standard ni prise en charge par la communauté, vous pouvez l’instrumenter manuellement.

Un autre exemple nécessitant un suivi personnalisé est le Worker qui reçoit des éléments de la file d’attente. Pour certaines files d’attente, l’appel visant à ajouter un message à cette file d’attente est comptabilisé en tant que dépendance. L’opération de haut niveau qui décrit le traitement des messages n’est pas collectée automatiquement.

Voyons à présent comment ces opérations pourraient être suivies.

À un niveau élevé, la tâche consiste à créer RequestTelemetry et à définir les propriétés connues. Une fois l’opération terminée, vous réalisez un suivi de la télémétrie. L’exemple suivant illustre ce cas de figure.

Requête HTTP dans une application Owin auto-hébergée

Dans cet exemple, le contexte du suivi est propagé conformément au protocole HTTP de corrélation. Attendez-vous à recevoir les en-têtes décrites ici.

Développer pour afficher le code

public class ApplicationInsightsMiddleware : OwinMiddleware
{
    // You may create a new TelemetryConfiguration instance, reuse one you already have,
    // or fetch the instance created by Application Insights SDK.
    private readonly TelemetryConfiguration telemetryConfiguration = TelemetryConfiguration.CreateDefault();
    private readonly TelemetryClient telemetryClient = new TelemetryClient(telemetryConfiguration);
    
    public ApplicationInsightsMiddleware(OwinMiddleware next) : base(next) {}

    public override async Task Invoke(IOwinContext context)
    {
        // Let's create and start RequestTelemetry.
        var requestTelemetry = new RequestTelemetry
        {
            Name = $"{context.Request.Method} {context.Request.Uri.GetLeftPart(UriPartial.Path)}"
        };

        // If there is a Request-Id received from the upstream service, set the telemetry context accordingly.
        if (context.Request.Headers.ContainsKey("Request-Id"))
        {
            var requestId = context.Request.Headers.Get("Request-Id");
            // Get the operation ID from the Request-Id (if you follow the HTTP Protocol for Correlation).
            requestTelemetry.Context.Operation.Id = GetOperationId(requestId);
            requestTelemetry.Context.Operation.ParentId = requestId;
        }

        // StartOperation is a helper method that allows correlation of 
        // current operations with nested operations/telemetry
        // and initializes start time and duration on telemetry items.
        var operation = telemetryClient.StartOperation(requestTelemetry);

        // Process the request.
        try
        {
            await Next.Invoke(context);
        }
        catch (Exception e)
        {
            requestTelemetry.Success = false;
            requestTelemetry.ResponseCode;
            telemetryClient.TrackException(e);
            throw;
        }
        finally
        {
            // Update status code and success as appropriate.
            if (context.Response != null)
            {
                requestTelemetry.ResponseCode = context.Response.StatusCode.ToString();
                requestTelemetry.Success = context.Response.StatusCode >= 200 && context.Response.StatusCode <= 299;
            }
            else
            {
                requestTelemetry.Success = false;
            }

            // Now it's time to stop the operation (and track telemetry).
            telemetryClient.StopOperation(operation);
        }
    }
    
    public static string GetOperationId(string id)
    {
        // Returns the root ID from the '|' to the first '.' if any.
        int rootEnd = id.IndexOf('.');
        if (rootEnd < 0)
            rootEnd = id.Length;

        int rootStart = id[0] == '|' ? 1 : 0;
        return id.Substring(rootStart, rootEnd - rootStart);
    }
}

Le protocole HTTP pour la corrélation déclare également l’en-tête Correlation-Context. Il est omis ici par souci de simplicité.

Instrumentation des files d’attente

Bien qu’il existe une norme W3C Trace Context et un protocole HTTP pour la corrélation pour transmettre les détails de la corrélation avec la requête HTTP, chaque protocole de file d’attente doit définir la façon dont ces détails seront transmis à travers le message de file d’attente. Certains protocoles de file d’attente, tels que AMQP, permettent de transmettre davantage de métadonnées. D'autres protocoles, tels que Azure Storage Queue, nécessitent que le contexte soit encodé dans la charge utile du message.

Note

Le suivi de plusieurs composants n’est pas encore pris en charge pour les files d’attente.

Avec HTTP, si votre producteur et votre consommateur envoient des données de télémétrie à différentes ressources Application Insights, Transaction Diagnostics Experience et Application Map affichent les transactions et le mappage de bout en bout. Pour les files d’attente, cette fonctionnalité n’est pas encore prise en charge.

file d'attente de Service Bus

Pour plus d’informations sur le suivi, consultez Distributed tracing and correlation through Azure Service Bus messaging.

file d’attente Azure Storage

L’exemple suivant montre comment suivre la file d’attente Azure Storage et mettre en corrélation les données de télémétrie entre le producteur, le consommateur et Azure Storage.

La file d’attente de stockage dispose d’une API HTTP. Tous les appels vers la file d’attente sont suivis par le collecteur de dépendance Application Insights pour les requêtes HTTP. Il est configuré par défaut sur les applications ASP.NET et ASP.NET Core. Pour d’autres types d’applications, consultez la documentation des applications console.

Vous pouvez également mettre en corrélation l’ID d’opération Application Insights avec l’ID de demande de stockage. Pour plus d’informations sur la définition et l’obtention d’un client de demande de stockage et d’un ID de demande de serveur, consultez Monitor, diagnostiquer et résoudre les problèmes Azure Storage.

Enqueue (empiler)

Étant donné que les files d’attente de stockage prennent en charge l’API HTTP, toutes les opérations mettant en jeu la file d’attente sont automatiquement suivies par Application Insights. Dans de nombreux cas, cette instrumentation doit être suffisante. Pour mettre en corrélation les traces côté client avec les traces du producteur, vous devez transmettre un contexte de corrélation de façon similaire à la manière utilisée dans le Protocole HTTP pour la corrélation.

Cet exemple montre comment effectuer le suivi de l’opération Enqueue. Vous pouvez:

• Mettre en corrélation les nouvelles tentatives (le cas échéant) : elles ont toutes un parent commun qui est l’opération Enqueue. Dans le cas contraire, elles sont comptabilisées en tant qu’enfants de la demande entrante. S’il existe plusieurs demandes logiques pour la file d’attente, il pourrait être difficile de trouver quel appel a généré de nouvelles tentatives.
• Mettre en corrélation les journaux d’activité de stockage Azure (si nécessaire) : elles sont mises en corrélation avec la télémétrie Application Insights.

L’opération Enqueue est l’enfant d’une opération parente. Par exemple, une requête HTTP entrante. L’appel de dépendance HTTP est l’enfant de l’opération Enqueue et le petit-enfant de la demande entrante :

public async Task Enqueue(CloudQueue queue, string message)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("enqueue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Enqueue " + queue.Name;

    // MessagePayload represents your custom message and also serializes correlation identifiers into payload.
    // For example, if you choose to pass payload serialized to JSON, it might look like
    // {'RootId' : 'some-id', 'ParentId' : '|some-id.1.2.3.', 'message' : 'your message to process'}
    var jsonPayload = JsonConvert.SerializeObject(new MessagePayload
    {
        RootId = operation.Telemetry.Context.Operation.Id,
        ParentId = operation.Telemetry.Id,
        Payload = message
    });
    
    CloudQueueMessage queueMessage = new CloudQueueMessage(jsonPayload);

    // Add operation.Telemetry.Id to the OperationContext to correlate Storage logs and Application Insights telemetry.
    OperationContext context = new OperationContext { ClientRequestID = operation.Telemetry.Id};

    try
    {
        await queue.AddMessageAsync(queueMessage, null, null, new QueueRequestOptions(), context);
    }
    catch (StorageException e)
    {
        operation.Telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.Telemetry.Success = false;
        operation.Telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}  

Pour réduire la quantité de données de télémétrie que votre application signale ou si vous ne souhaitez pas suivre l’opération Enqueue pour d’autres raisons, utilisez directement l’API Activity :

• Créez (et démarrez) une nouvelle opération Activity au lieu de démarrer l’opération Application Insights. Vous n’avez pas besoin d’attribuer de propriétés sur celle-ci, à l’exception du nom de l’opération.
• Sérialisez yourActivity.Id dans la charge utile du message à la place de operation.Telemetry.Id. Vous pouvez également utiliser Activity.Current.Id.

Dequeue (Enlever de la file d’attente)

Comme avec Enqueue, une requête HTTP réelle à la file d’attente de stockage est automatiquement suivie par Application Insights. L’opération Enqueue se produit vraisemblablement dans le contexte parent, par exemple un contexte de demande entrant. Les kits SDK d’Application Insights mettent automatiquement en corrélation cette opération (et sa partie HTTP) avec la demande parent et d’autres données de télémétrie signalées dans le même cadre.

L’opération Dequeue est compliquée. Le kit SDK d’Application Insights effectue automatiquement le suivi des demandes HTTP. Toutefois, il ne connaît pas le contexte de corrélation avant que le message ne soit analysé. Il n’est pas possible de mettre en corrélation la requête HTTP afin d’obtenir le message avec le reste des données de télémétrie, surtout lorsque plusieurs messages ont été reçus.

public async Task<MessagePayload> Dequeue(CloudQueue queue)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("dequeue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Dequeue " + queue.Name;

    try
    {
        var message = await queue.GetMessageAsync();
    }
    catch (StorageException e)
    {
        operation.telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.telemetry.Success = false;
        operation.telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }

    return null;
}

Process

Dans l’exemple suivant, un message entrant est tracé de la même façon qu’une requête HTTP entrante :

public async Task Process(MessagePayload message)
{
    // After the message is dequeued from the queue, create RequestTelemetry to track its processing.
    RequestTelemetry requestTelemetry = new RequestTelemetry { Name = "process " + queueName };
    
    // It might also make sense to get the name from the message.
    requestTelemetry.Context.Operation.Id = message.RootId;
    requestTelemetry.Context.Operation.ParentId = message.ParentId;

    var operation = telemetryClient.StartOperation(requestTelemetry);

    try
    {
        await ProcessMessage();
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        throw;
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}

De même, les autres opérations de file d’attente peuvent être instrumentées. Une opération d’aperçu doit être instrumentée de façon similaire à un retrait de la file d’attente. L’instrumentation des opérations de gestion de file d’attente n’est pas nécessaire. Application Insights effectue le suivi d’opérations telles que HTTP et, dans la plupart des cas, cela suffit.

Lors de l’instrumentation d’une suppression de message, assurez-vous de définir les identificateurs de l’opération (corrélation). Vous pouvez également utiliser l’API Activity. Vous n’avez alors pas besoin de définir des identificateurs d’opérations sur les éléments de télémétrie, car le Kit SDK Application Insights le fait pour vous :

• Créez une nouvelle API Activity une fois que vous avez un élément à partir de la file d’attente.
• Utilisez Activity.SetParentId(message.ParentId) pour mettre en corrélation les journaux d’activité du consommateur et du producteur.
• Démarrez Activity.
• Effectuez le suivi des opérations de retrait de file d’attente, de traitement et de suppression à l’aide des programmes d’assistance Start/StopOperation. Procédez à partir du même flux de contrôle asynchrone (contexte d’exécution). De cette manière, elles sont correctement mises en corrélation.
• Arrêtez Activity.
• Utilisez Start/StopOperation ou appelez manuellement la télémétrie Track.

Types de dépendance

Application Insights utilise un type de dépendance pour personnaliser les expériences d’interface utilisateur. Pour les files d'attente, il reconnaît les types suivants de DependencyTelemetry qui améliorent l'expérience de diagnostic des transactions :

• Azure queue pour les files d'attente de Azure Storage
• Azure Event Hubs pour Azure Event Hubs
• Azure Service Bus pour Azure Service Bus

Traitement par lots

Avec des files d’attente, vous pouvez retirer plusieurs messages de la file d’attente avec une seule demande. Le traitement de ces messages est vraisemblablement indépendant et appartient à différentes opérations logiques. Il n’est pas possible de mettre en corrélation l’opération Dequeue avec un traitement de message particulier.

Chaque traitement de message doit être traité dans son propre flux de contrôle asynchrone. Pour plus d’informations, consultez la section Suivi des dépendances sortantes.

Tâches en arrière-plan à long terme

Certaines applications démarrent des opérations à long terme qui peuvent être dues à des demandes de l’utilisateur. Du point de vue du traçage/de l’instrumentation, ce n’est pas différent de l’instrumentation des demandes ou des dépendances :

async Task BackgroundTask()
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>(taskName);
    operation.Telemetry.Type = "Background";
    try
    {
        int progress = 0;
        while (progress < 100)
        {
            // Process the task.
            telemetryClient.TrackTrace($"done {progress++}%");
        }
        // Update status code and success as appropriate.
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        // Update status code and success as appropriate.
        throw;
    }
    finally
    {
        telemetryClient.StopOperation(operation);
    }
}

Dans cet exemple, telemetryClient.StartOperation crée DependencyTelemetry et remplit le contexte de corrélation. Supposons que vous avez une opération parent qui a été créée par les demandes entrantes qui ont planifié l’opération. Tant que BackgroundTask démarre dans le même flux de contrôle asynchrone en tant que demande entrante, elle est mise en corrélation avec cette opération parent. BackgroundTask et tous les éléments de télémétrie imbriqués sont automatiquement mis en corrélation avec la demande à son origine, même après la fin de la demande.

Lorsque la tâche démarre à partir du thread en arrière-plan qui n’a pas d’opération (Activity) associée, BackgroundTask n’a pas de parent. Toutefois, il peut avoir plusieurs opérations imbriquées. Tous les éléments de télémétrie signalés à partir de la tâche sont mis en corrélation avec l’élément DependencyTelemetry créé dans l’élément BackgroundTask.

Suivi des dépendances sortantes

Vous pouvez effectuer le suivi de votre propre genre de dépendance ou d’une opération qui n’est pas prise en charge par Application Insights.

La méthode Enqueue dans la file d’attente Service Bus ou la file d’attente de stockage peut servir d’exemples pour ce suivi personnalisé.

L’approche générale utilisée pour le suivi personnalisé des dépendances est la suivante :

• Appelez la méthode TelemetryClient.StartOperation (extension) qui remplit les propriétés DependencyTelemetry nécessaires pour la corrélation et d’autres propriétés (heure de début, durée).
• Définissez d’autres propriétés personnalisées sur l’élément DependencyTelemetry, comme le nom et tout autre contexte dont vous avez besoin.
• Effectuez un appel de dépendance et attendez les résultats.
• Arrêtez l’opération avec StopOperation lorsqu’elle est terminée.
• Traitez les exceptions.

public async Task RunMyTaskAsync()
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>("task 1"))
    {
        try 
        {
            var myTask = await StartMyTaskAsync();
            // Update status code and success as appropriate.
        }
        catch(...) 
        {
            // Update status code and success as appropriate.
        }
    }
}

L’opération de suppression entraîne l’arrêt de l’opération. Vous pouvez donc l’utiliser au lieu d’appeler StopOperation.

Avertissement

Dans certains cas, une exception non gérée peut empêcherfinally l’appel, de sorte que les opérations peuvent ne pas être suivies.

Suivi et traitement d’opérations parallèles

L’appel de StopOperation ne peut arrêter que l’opération qui a été lancée. Si l’opération en cours d’exécution actuelle ne correspond pas à celle que vous souhaitez arrêter, StopOperation ne fait rien. Cette situation peut se produire si vous démarrez plusieurs opérations en parallèle dans le même contexte d’exécution.

var firstOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 1");
var firstTask = RunMyTaskAsync();

var secondOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 2");
var secondTask = RunMyTaskAsync();

await firstTask;

// FAILURE!!! This will do nothing and will not report telemetry for the first operation
// as currently secondOperation is active.
telemetryClient.StopOperation(firstOperation); 

await secondTask;

Veillez à toujours appeler StartOperation et à traiter l’opération à l’aide de la même méthode asynchrone pour isoler les opérations exécutées en parallèle. Si l’opération est synchrone (et non asynchrone), incluez le processus dans un wrapper et effectuez le suivi avec Task.Run.

public void RunMyTask(string name)
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>(name))
    {
        Process();
        // Update status code and success as appropriate.
    }
}

public async Task RunAllTasks()
{
    var task1 = Task.Run(() => RunMyTask("task 1"));
    var task2 = Task.Run(() => RunMyTask("task 2"));
    
    await Task.WhenAll(task1, task2);
}

Opérations ApplicationInsights vs System.Diagnostics.Activity

System.Diagnostics.Activity représente le contexte de suivi distribué et est utilisé par les infrastructures et les bibliothèques pour créer et propager le contexte à l’intérieur et à l’extérieur du processus et mettre en corrélation les éléments de télémétrie. Activity fonctionne conjointement avec System.Diagnostics.DiagnosticSource, le mécanisme de notification entre l’infrastructure/la bibliothèque pour notifier les événements intéressants (demandes entrantes ou sortantes et les exceptions).

Les activités sont des fonctionnalités de niveau supérieur dans Application Insights. La dépendance automatique et la collecte des requêtes s’appuient fortement sur elles, ainsi que sur les événements DiagnosticSource. Si vous avez créé Activity dans votre application, cela n’entraîne pas la création de télémétrie Application Insights. Application Insights doit recevoir DiagnosticSource des événements et connaître les noms et charges utiles des événements à traduire Activity en données de télémétrie.

Chaque opération Application Insights (demande ou dépendance) implique Activity. Quand StartOperation est appelé, il crée Activity en dessous. StartOperation est la méthode recommandée pour suivre manuellement les télémétrie de requête ou de dépendance et garantir que tout est corrélé.

Compteurs

Application Insights prend en charge les compteurs de performance et les compteurs d’événement. Ce guide fournit une vue d’ensemble des deux, notamment leur objectif, leur configuration et leur utilisation dans .NET applications.

• les compteurs Performance sont intégrés au système d’exploitation Windows et offrent des métriques prédéfinies telles que l’utilisation du processeur, la consommation de mémoire et l’activité de disque. Ces compteurs sont idéaux pour surveiller les indicateurs de performance standard avec une configuration minimale. Ils permettent de suivre l'utilisation des ressources ou de résoudre les goulots d'étranglement au niveau du système dans les applications Windows, mais ne prennent pas en charge les métriques personnalisées spécifiques aux applications.

• les compteurs Event fonctionnent sur plusieurs plateformes, notamment Windows, Linux et macOS. Ils permettent aux développeurs de définir et de surveiller des mesures légères et personnalisables propres à l’application, offrant plus de flexibilité que les compteurs de performances. Les compteurs d’événements sont utiles lorsque les mesures système sont insuffisantes ou lorsque des données de télémétrie détaillées sont nécessaires dans les applications multiplateformes. Ils nécessitent une implémentation et une configuration explicites, ce qui rend la configuration plus intensive.

Compteurs de performance

Windows fournit différents compteurs performance tels que ceux utilisés pour collecter les statistiques d’utilisation du processeur, de la mémoire et des disques. Vous pouvez également définir vos propres compteurs de performances.

Votre application prend en charge la collecte de compteurs de performances si elle s’exécute sous Internet Information Server (IIS) sur un hôte local ou une machine virtuelle disposant d’un accès administratif. Les applications s'exécutant en tant que Azure Web Apps ne peuvent pas accéder directement aux compteurs de performances, mais Application Insights collecte un sous-ensemble de compteurs disponibles.

Conseil / Astuce

Comme d’autres mesures, vous pouvez définir une alerte pour avertir si un compteur dépasse une limite spécifiée. Pour définir une alerte, ouvrez le volet Alertes et cliquez sur Ajouter une alerte.

Conditions préalables

Accordez au compte de service du pool d’applications l’autorisation de surveiller les compteurs de performance en l’ajoutant au groupe Performance Monitor Users.

net localgroup "Performance Monitor Users" /add "IIS APPPOOL\NameOfYourPool"

Afficher des compteurs

Le volet Métriques affiche un ensemble de compteurs de performances par défaut.

ASP.NET

Compteurs par défaut pour les applications web ASP.NET :

• % du processus\Temps du processeur
• % du processus\Temps du processeur normalisé
• Mémoire\octets disponibles
• Demandes ASP.NET/seconde
• Exceptions levées par seconde dans le runtime .NET Common Language Runtime (CLR)
• ASP.NET Temps d'exécution des demandes d'applications
• Processus\Octets privés
• Processus\Nombre d'octets de données E/S par s
• ASP.NET Applications\Demandes dans la file d’attente d’applications
• Processor(_Total)\% de temps de processeur

ASP.NET Core

Compteurs par défaut pour les applications web ASP.NET Core :

• % du processus\Temps du processeur
• % du processus\Temps du processeur normalisé
• Mémoire\octets disponibles
• Processus\Octets privés
• Processus\Nombre d'octets de données E/S par s
• Processor(_Total)\% de temps de processeur

Note

La prise en charge des compteurs de performances dans ASP.NET Core est limitée :

• SDK versions 2.4.1 et ultérieures collectent les compteurs de performances si l’application s’exécute dans Azure Web Apps (Windows).
• Les versions 2.7.1 et ultérieures du Kit de Développement Logiciel (SDK) collectent des compteurs de performance si l'application s'exécute sur Windows et cible la version NETSTANDARD2.0 ou une version ultérieure.
• Pour les applications qui ciblent l’infrastructure .NET, toutes les versions du Kit de développement logiciel (SDK) prennent en charge les compteurs de performances.
• Les versions 2.8.0 et ultérieures du kit de développement logiciel (SDK) prennent en charge le compteur processeur/mémoire dans Linux. Aucun autre compteur n’est pris en charge dans Linux. Pour obtenir des compteurs système dans Linux (et d’autres environnements non Windows), utilisez des compteurs d’événements.

Ajouter des compteurs

Si le compteur de performances que vous souhaitez n’est pas inclus dans la liste des métriques, vous pouvez l’y ajouter.

ASP.NET

Option 1 : configuration dans ApplicationInsights.config

1. Découvrez les compteurs disponibles sur votre serveur à l’aide de la commande PowerShell suivante sur le serveur local :

   Get-Counter -ListSet *
   

   Pour plus d’informations, consultez Get-Counter.

2. Ouvrez ApplicationInsights.config.

   Si vous avez ajouté Application Insights à votre application pendant le développement :

   1. Modifiez ApplicationInsights.config dans votre projet.
   2. Redéployez-le sur vos serveurs.

3. Modifiez la directive du collecteur de performances :

   
       <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector">
         <Counters>
           <Add PerformanceCounter="\Objects\Processes"/>
           <Add PerformanceCounter="\Sales(photo)\# Items Sold" ReportAs="Photo sales"/>
         </Counters>
       </Add>
   

Vous capturez les compteurs standard et ceux que vous implémentez vous-même. \Objects\Processes est un exemple de compteur standard disponible sur tous les systèmes Windows. \Sales(photo)\# Items Sold est un exemple de compteur personnalisé qui peut être implémenté dans un service web.

Le format est le suivant : \Category(instance)\Counter ou, pour les catégories qui ne présentent aucune instance : \Category\Counter, tout simplement.

Le paramètre ReportAs est requis pour les noms de compteurs qui ne correspondent pas à [a-zA-Z()/-_ \.]+.

Si vous spécifiez une instance, elle devient une dimension CounterInstanceName de la mesure signalée.

Option 2 : configuration dans le code

Voir la section suivante.

ASP.NET Core

Configurez PerformanceCollectorModule après la WebApplication.CreateBuilder() méthode dans Program.cs:

using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures PerformanceCollectorModule.

builder.Services.ConfigureTelemetryModule<PerformanceCollectorModule>((module, o) =>
    {
        // The application process name could be "dotnet" for ASP.NET Core self-hosted applications.
        module.Counters.Add(new PerformanceCounterCollectionRequest(@"\Process([replace-with-application-process-name])\Page Faults/sec", "DotnetPageFaultsPerfSec"));
    });

var app = builder.Build();

Collecter des compteurs de performances dans le code pour les applications web ASP.NET ou les applications console .NET/.NET Core

Pour collecter les compteurs de performances système et les envoyer à Application Insights, vous pouvez adapter l’extrait de code suivant :

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Process([replace-with-application-process-name])\Page Faults/sec", "PageFaultsPerfSec"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

Ou vous pouvez effectuer la même opération avec les mesures personnalisées que vous avez créées :

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Sales(photo)\# Items Sold", "Photo sales"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

Compteurs de performances pour les applications s’exécutant dans des conteneurs Azure Web Apps et Windows sur Azure App Service

Les applications ASP.NET et ASP.NET Core déployées sur Azure Web Apps s’exécutent dans un environnement de bac à sable spécial. Les applications déployées sur Azure App Service peuvent utiliser un conteneur Windows ou être hébergées dans un environnement de bac à sable. Si l’application est déployée dans un conteneur Windows, tous les compteurs de performances standard sont disponibles dans l’image conteneur.

L’environnement de bac à sable ne permet pas l’accès direct aux compteurs de performances du système. Cependant, un sous-ensemble limité de compteurs sont exposés en tant que variables d’environnement comme décrit dans Compteurs de performances exposés en tant que variables d’environnement. Seul un sous-ensemble de compteurs est disponible dans cet environnement.

Le SDK Application Insights pour ASP.NET et ASP.NET Core détecte si le code est déployé sur une application web ou un conteneur non Windows. La détection détermine s’il collecte des compteurs de performances dans un environnement de bac à sable ou utilise le mécanisme de collecte standard lorsqu’il est hébergé sur un conteneur ou une machine virtuelle Windows.

Log Analytics requêtes pour les compteurs de performances

Vous pouvez rechercher et afficher des rapports de compteur de performances dans Log Analytics.

Le schéma compteur de performances expose les noms category, counter et instance nom de chaque compteur de performance. Dans les données de télémétrie de chaque application, vous voyez uniquement les compteurs de cette application. Par exemple, pour voir les compteurs disponibles :

performanceCounters | summarize count(), avg(value) by category, instance, counter

Ici, Instance fait ici référence à l’instance de compteur de performances, pas à l’instance de rôle ou de machine serveur. Le nom d’instance de compteur de performances segmente généralement les compteurs comme le temps processeur par le nom du processus ou de l’application.

Pour obtenir un graphique présentant la mémoire disponible sur une période récente :

performanceCounters | where counter == "Available Bytes" | summarize avg(value), min(value) by bin(timestamp, 1h) | render timechart

Comme les autres données de télémétrie, performanceCounters possède également une colonne cloud_RoleInstance qui indique l’identité de l’instance de serveur hôte sur lequel votre application est en cours d’exécution. Par exemple, pour comparer les performances de votre application sur des ordinateurs différents :

performanceCounters | where counter == "% Processor Time" and instance == "SendMetrics" | summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1d)

FAQ sur les compteurs de performance

Pour examiner les questions fréquemment posées (FAQ), consultez les FAQ sur les compteurs de performance.

Compteurs d’événements

EventCounter est un mécanisme de .NET/.NET Core permettant de publier et de consommer des compteurs ou des statistiques. EventCounters est pris en charge dans toutes les plateformes de système d’exploitation : Windows, Linux et macOS. Il peut être considéré comme un équivalent multiplateforme pour les PerformanceCounters pris en charge uniquement dans les systèmes Windows.

Bien que les utilisateurs puissent publier tous les compteurs d’événements personnalisés pour répondre à leurs besoins, .NET publie un ensemble de ces compteurs par défaut. Ce document décrit les étapes requises pour collecter et afficher les compteurs d’événements (définis par le système ou définis par l’utilisateur) dans Azure Application Insights.

Conseil / Astuce

Comme d’autres mesures, vous pouvez définir une alerte pour avertir si un compteur dépasse une limite spécifiée. Pour définir une alerte, ouvrez le volet Alertes et cliquez sur Ajouter une alerte.

Utilisation d’Application Insights pour collecter des compteurs d’événements

Application Insights prend en charge la collecte de EventCounters avec son EventCounterCollectionModule, qui fait partie du package NuGet récemment publié Microsoft.ApplicationInsights.EventCounterCollector. EventCounterCollectionModule est automatiquement activé dès que vous utilisez AspNetCore ou WorkerService. EventCounterCollectionModule collecte les compteurs selon une fréquence de collecte non configurable de 60 secondes. Aucune autorisation spéciale n’est nécessaire pour collecter des compteurs d’événements. Pour les applications ASP.NET Core, vous souhaitez également ajouter le package Microsoft.ApplicationInsights.AspNetCore.

dotnet add package Microsoft.ApplicationInsights.EventCounterCollector
dotnet add package Microsoft.ApplicationInsights.AspNetCore

Compteurs par défaut collectés

À partir de la version 2.15.0 du Kit de développement logiciel (SDK) AspNetCore et du Kit de développement logiciel (SDK) WorkerService, aucun compteur n’est collecté par défaut. Le module lui-même est activé, les utilisateurs peuvent donc ajouter les compteurs souhaités pour les collecter.

Pour obtenir la liste des compteurs connus publiés par le runtime .NET, consultez le document Available Counters.

Personnalisation des compteurs à collecter

L’exemple suivant montre comment ajouter/supprimer des compteurs. Cette personnalisation est effectuée dans le cadre de la configuration de votre service d’application une fois que la collecte de données de télémétrie Application Insights est activée en utilisant AddApplicationInsightsTelemetry() ou AddApplicationInsightsWorkerService(). Voici un exemple de code d’une application ASP.NET Core. Pour d’autres types d’applications, reportez-vous à la configuration des modules de télémétrie.

using Microsoft.ApplicationInsights.Extensibility.EventCounterCollector;
using Microsoft.Extensions.DependencyInjection;

builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>(
        (module, o) =>
        {
            // Removes all default counters, if any.
            module.Counters.Clear();

            // Adds a user defined counter "MyCounter" from EventSource named "MyEventSource"
            module.Counters.Add(
                new EventCounterCollectionRequest("MyEventSource", "MyCounter"));

            // Adds the system counter "gen-0-size" from "System.Runtime"
            module.Counters.Add(
                new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        }
    );

Désactivation du module de collecte EventCounter

EventCounterCollectionModule peut être désactivé avec ApplicationInsightsServiceOptions.

L’exemple suivant utilise le Kit de développement logiciel (SDK) ASP.NET Core.

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.Extensions.DependencyInjection;

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

Une approche similaire peut également être utilisée pour le Kit de développement logiciel (SDK) du service Worker, mais l’espace de noms doit être modifié comme indiqué dans l’exemple suivant.

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.Extensions.DependencyInjection;

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

requêtes Log Analytics pour les compteurs d’événements

Vous pouvez rechercher et afficher des rapports de compteur d’événements dans Log Analytics, dans la table customMetrics.

Par exemple, exécutez la requête suivante pour voir quels compteurs sont collectés et disponibles pour la requête :

customMetrics | summarize avg(value) by name

Pour obtenir un graphique d’un compteur spécifique (par exemple, ThreadPool Completed Work Item Count) sur la période récente, exécutez la requête suivante.

customMetrics 
| where name contains "System.Runtime|ThreadPool Completed Work Item Count"
| where timestamp >= ago(1h)
| summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1m)
| render timechart

Comme les autres données de télémétrie, customMetrics possède également une colonne cloud_RoleInstance qui indique l’identité de l’instance de serveur hôte sur lequel votre application est en cours d’exécution. La requête précédente montre la valeur de compteur par instance et peut servir à comparer les performances des différentes instances de serveur.

FAQ sur les compteurs d’événement

Pour examiner les questions fréquentes (FAQ), consultez les FAQ sur les compteurs d’événement.

Collecte d’instantanés

Pour savoir comment configurer la collecte d’instantanés pour les applications ASP.NET et ASP.NET Core, consultez Activer le débogueur d'instantané pour les applications .NET dans Azure Service Fabric, services cloud et machines virtuelles.

Node.js

Dans cette section

• Métriques temps réel
• Suivi distribué
• Dépendances
• Métriques étendues
• TelemetryClient API

Métriques temps réel

Les métriques en direct peuvent être utilisées pour vérifier rapidement si la supervision de l’application avec Application Insights est correctement configurée. La télémétrie peut prendre quelques minutes pour apparaître dans le portail Azure, mais le volet des métriques actives affiche l’utilisation du processeur du processus en cours d’exécution en quasi-temps réel. Elle peut également afficher d’autres données de télémétrie comme les requêtes, les dépendances et les traces.

Activer les métriques actives

1. Pour activer l’envoi de métriques actives de votre application à Azure, utilisez setSendLiveMetrics(true).

2. Ouvrez la ressource Application Insights pour votre application dans le portail Azure. Sélectionnez Live Metrics répértorié sous Examiner dans le menu de gauche.

3. Sécurisez le canal de contrôle en activant l'authentification Microsoft Entra en cas d'utilisation de filtres personnalisés.

   Note

   Le filtrage des métriques en temps réel dans le portail n’est actuellement pas pris en charge.

Fonctionnalités prises en charge

Métriques de base	Mesures de performances	Filtrage personnalisé	Exemple de télémétrie	Répartition du CPU par processus
Pris en charge (V1.3.0 et versions ultérieures)	Pris en charge (V1.3.0 et versions ultérieures)	Pris en charge (V1.3.0 et versions ultérieures)	Pris en charge (V1.3.0 et versions ultérieures)	Non pris en charge

Les métriques de base incluent les requêtes, les dépendances et le taux d’exceptions. Les métriques du niveau de performance (compteurs de performances) incluent la mémoire et l’UC. L’exemple de télémétrie montre un flux d’informations détaillées pour les demandes et les dépendances ayant échoué, les exceptions, les événements et les traces.

Suivi distribué

Les architectures de cloud et de microservices modernes ont activé des services simples et déployables indépendamment qui réduisent les coûts tout en augmentant la disponibilité et le débit. Toutefois, il a rendu les systèmes globaux plus difficiles à raisonner et à déboguer. Le suivi distribué résout ce problème en fournissant un profileur de performances qui fonctionne comme des piles d’appels pour les architectures cloud et microservices.

Azure Monitor fournit deux expériences pour consommer des données de trace distribuées : les diagnostics de transaction pour une seule transaction/requête et la vue application pour montrer comment les systèmes interagissent.

Application Insights peut surveiller chaque composant séparément et détecter le composant responsable des défaillances ou de la dégradation des performances à l’aide de la corrélation de télémétrie distribuée. Cet article explique le modèle de données, les techniques de propagation de contexte, les protocoles et l’implémentation de tactiques de corrélation sur différents langages et plateformes utilisés par Application Insights.

Activer le suivi distribué grâce à Application Insights via l'autoinstrumentation ou les SDK.

Les agents et kits SDK Application Insights pour .NET, .NET Core, Java, Node.jset JavaScript prennent tous en charge le suivi distribué en mode natif.

Une fois que le SDK Application Insights approprié est installé et configuré, les informations de suivi sont automatiquement collectées pour les infrastructures, bibliothèques et technologies populaires par les sélecteurs automatiques de dépendances du SDK. La liste complète des technologies prises en charge est disponible dans la documentation sur la collecte automatique des dépendances.

Toute technologie peut également être suivie manuellement avec un appel à TrackDependency sur TelemetryClient.

Modèle de données pour la corrélation de télémétrie

Application Insights définit un modèle de données pour la corrélation de télémétrie distribuée. Pour associer la télémétrie à une opération logique, chaque élément de télémétrie a un champ de contexte appelé operation_Id. Chaque élément de télémétrie dans la trace distribuée partage cet identificateur. Ainsi, même si vous perdez des données de télémétrie d’une seule couche, vous pouvez toujours associer des données de télémétrie signalées par d’autres composants.

Une opération logique distribuée se compose généralement d’un ensemble d’opérations plus petites qui sont des requêtes traitées par l’un des composants. La télémétrie de requête définit ces opérations. Chaque élément de télémétrie de requête possède son propre id, qui l'identifie de façon unique et globale. Par ailleurs, tous les éléments de télémétrie (comme les traces et les exceptions) associés à la requête doivent définir le operation_parentId sur la valeur de l’id de la requête.

La télémétrie des dépendances représente chaque opération sortante, telle qu’un appel HTTP à un autre composant. Il définit également son propre id qui est globalement unique. La télémétrie des requêtes, lancée par cet appel de dépendances, utilise cet id comme operation_parentId.

Vous pouvez créer une vue de l’opération logique distribuée à l’aide de operation_Id, operation_parentId et request.id avec dependency.id. Ces champs définissent également l’ordre de causalité des appels de télémétrie.

Dans un environnement de microservices, les traces des composants peuvent accéder à différents éléments de stockage. Chaque composant peut avoir sa propre connection string dans Application Insights. Pour obtenir des données de télémétrie pour l’opération logique, Application Insights interroge les données de chaque élément de stockage.

Lorsque le nombre d'objets de stockage est élevé, vous avez besoin d'un indicateur sur l'endroit où chercher ensuite. Le modèle de données Application Insights définit deux champs pour résoudre ce problème : request.source et dependency.target. Le premier champ identifie le composant qui a lancé la demande de dépendance. Le deuxième champ identifie le composant qui a retourné la réponse de l’appel de dépendance.

Pour plus d'informations sur l'interrogation à partir de plusieurs instances disparates, consultez l'interrogation des données dans les espaces de travail, les applications et les ressources de Log Analytics dans Azure Monitor.

Exemple

Intéressons-nous à un exemple. Une application appelée Cours boursiers affiche le cours actuel du marché d’une action à l’aide d’une API externe appelée Stock. L’application Stock Prices a une page appelée Page Stock que le navigateur web client ouvre à l’aide de GET /Home/Stock. L’application interroge l’API Stock à l’aide de l’appel GET /api/stock/valueHTTP.

Vous pouvez analyser les données de télémétrie résultantes en exécutant une requête :

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

Dans les résultats, tous les éléments de télémétrie partagent la racine operation_Id. Lorsqu’un appel Ajax est effectué à partir de la page, un nouvel ID unique (qJSXU) est affecté à la télémétrie des dépendances et l’ID du pageView est utilisé comme operation_ParentId. La demande de serveur utilise ensuite l’ID Ajax comme operation_ParentId.

type d'article	nom	ID	operation_ParentId	identifiant_opération
pageView	Page de gestion des stocks	STYz		STYz
dépendance	GET /Home/Stock	qJSXU	STYz	STYz
request	GET Home/Stock	KqKwlrSt9PA=	qJSXU	STYz
dépendance	GET /api/stock/value	bBrf2L7mm2g=	KqKwlrSt9PA=	STYz

Lorsque l’appel GET /api/stock/value est effectué auprès d’un service externe, vous devez connaître l’identité de ce serveur afin de pouvoir définir le dependency.target champ de manière appropriée. Lorsque le service externe ne prend pas en charge la surveillance, target est défini sur le nom d’hôte du service. par exemple stock-prices-api.com. Toutefois, si le service s’identifie en retournant un en-tête HTTP prédéfini, target contient l’identité de service qui permet à Application Insights de générer une trace distribuée en interrogeant les données de télémétrie à partir de ce service.

En-têtes de corrélation à l’aide de W3C TraceContext

Application Insights passe au contexte de trace W3C, qui définit :

• traceparent: porte l’ID d’opération global unique et l’identificateur unique de l’appel.
• tracestate: Transporte le contexte de traçage spécifique au système.

La dernière version du Kit de développement logiciel (SDK) Application Insights prend en charge le protocole Trace-Context, mais vous devrez peut-être y participer. (La compatibilité descendante avec le protocole de corrélation précédent pris en charge par le Kit de développement logiciel (SDK) Application Insights est maintenue.)

Le protocole HTTP de corrélation, également appelé Request-Id, est déconseillé. Ce protocole définit deux en-têtes :

• Request-Id: porte l’ID global unique de l’appel.
• Correlation-Context: contient la collection de couples nom-valeur associée aux propriétés de trace distribuée.

Application Insights définit également l’extension pour le protocole HTTP de corrélation. Il utilise des paires nom-valeur Request-Context pour propager la collection de propriétés utilisée par l’appelant ou l’appelé. Le Kit de développement logiciel (SDK) Application Insights utilise cet en-tête pour définir les champs dependency.target et request.source.

Les modèles de données W3C Trace-Context et Application Insights sont mappés de la manière suivante :

Application Insights	W3C TraceContext (Contexte de trace W3C)
Id de Request et Dependency	parent-id
Operation_Id	trace-id
Operation_ParentId	parent-id de l’étendue parente de cette étendue. Ce champ doit être vide s’il s’agit d’une étendue racine.

Pour plus d’informations, consultez le modèle de données de télémétrie Application Insights.

Activer la prise en charge du suivi distribué W3C

Par défaut, le SDK envoie des en-têtes comprises par d’autres applications/services instrumentés avec un SDK Application Insights. Vous pouvez activer l’envoi et la réception d’en-têtes de contexte de trace W3C en plus des en-têtes AI existants. De cette façon, vous ne rompez pas la corrélation avec vos services hérités existants.

L’activation des en-têtes W3C permettra à votre application de se mettre en corrélation avec d’autres services qui ne sont pas instrumentés avec Application Insights mais adoptant ce standard W3C.

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

Dépendances

Dépendances suivies automatiquement

Une liste des derniers modules actuellement pris en charge est conservée dans Éditeurs de canal de diagnostic.

Comment fonctionne le suivi automatique des dépendances ?

• L'instrumentation du bytecode s'applique autour des méthodes sélectionnées à l'aide de InstrumentationEngine, et elle est activée via StatusMonitor ou l'extension Application Insights pour Azure App Service.

• Les rappels EventSource sont utilisés pour capturer les données de télémétrie des bibliothèques .NET qui émettent des événements structurés.

• Les rappels DiagnosticSource sont utilisés dans les SDK .NET et .NET Core plus récents pour collecter les données de télémétrie des bibliothèques qui prennent en charge le suivi distribué.

Suivi manuel des dépendances

Pour obtenir des instructions, consultez Suivre vos dépendances.

Métriques étendues

Note

La possibilité d’envoyer des métriques natives étendues a été ajoutée dans la version 1.4.0.

Pour activer l’envoi de métriques natives étendues de votre application à Azure, installez le package de métriques natives distinct. Une fois installé, le kit de développement logiciel (SDK) se charge automatiquement et démarre la collecte des métriques natives de Node.js.

npm install applicationinsights-native-metrics

Actuellement, le package de mesures natives effectue la collecte automatique du temps processeur du nettoyage de la mémoire, des cycles de boucle d’événements et de l’utilisation du tas :

• Nettoyage de la mémoire : La quantité de temps processeur passée sur chaque type de nettoyage de la mémoire, et le nombre d’occurrences de chaque type.
• Boucle d’événements : Le nombre de cycles qui se sont produits et le temps processeur passé au total.
• Avec ou sans tas : quantité de mémoire de votre application utilisée avec ou sans le tas.

TelemetryClient API

Pour une description complète de l’API TelemetryClient, consultez API Application Insights pour les événements et les mesures personnalisés.

Vous pouvez suivre les requêtes, les événements, les métriques ou les exceptions à l’aide de la bibliothèque de client Application Insights pour Node.js. L’exemple de code suivant présente certaines des API que vous pouvez utiliser :

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

Suivez vos dépendances

Utilisez le code suivant pour effectuer le suivi de vos dépendances :

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

Un exemple d’utilitaire utilisant trackMetric pour mesurer le temps nécessaire à la planification de la boucle d’événements :

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

Ajouter une propriété personnalisée à tous les événements

Utilisez le code suivant pour ajouter une propriété personnalisée à tous les événements :

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

Suivre les demandes HTTP GET

Utilisez le code suivant pour effectuer le suivi manuel des demandes HTTP GET :

Note

• Toutes les demandes sont suivies par défaut. Pour désactiver la collecte automatique, appelez .setAutoCollectRequests(false) avant d’appeler start().
• Les demandes d’API fetch natives ne sont pas automatiquement suivies par Application Insights classique ; le suivi manuel des dépendances est requis.

appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

Vous pouvez aussi suivre les requêtes en utilisant la méthode trackNodeHttpRequest :

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

Suivre le temps de démarrage du serveur

Utilisez le code suivant pour effectuer le suivi du temps de démarrage du serveur :

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

Vider

Par défaut, la télémétrie est mise en mémoire tampon pendant 15 secondes avant d’être envoyée au serveur d’ingestion. Si votre application a une durée de vie courte, par exemple un outil CLI, il peut être nécessaire de vider manuellement votre télémétrie mise en mémoire tampon quand l’application se termine en utilisant appInsights.defaultClient.flush().

Si le SDK détecte un plantage de votre application, il exécute la commande flush pour vous en utilisant appInsights.defaultClient.flush({ isAppCrashing: true }). Avec l’option de vidage isAppCrashing, votre application est présumée être dans un état anormal, non adapté à l’envoi de la télémétrie. Au lieu de cela, le kit de développement logiciel (SDK) enregistre toutes les données de télémétrie en mémoire tampon dans un stockage persistant et permet la fermeture de votre application. Lors du redémarrage de votre application, celle-ci tente d’envoyer toutes les données de télémétrie sauvegardées sur le stockage persistant.

Traitement et filtrage des données de télémétrie

.NET

Dans cette section

• Filtrer et prétraiter les données de télémétrie
• Initialiseurs de télémétrie
• Processeur de télémétrie
• Échantillonnage
• Enrichir des données via HTTP

Filtrer et prétraiter les données de télémétrie

Vous pouvez écrire du code pour filtrer, modifier ou enrichir vos données de télémétrie avant d’être envoyées à partir du Kit de développement logiciel (SDK). Le traitement inclut les données envoyées à partir des modules de télémétrie standard, tels que la collecte de requêtes HTTP et la collecte de dépendances.

• Le filtrage peut modifier ou ignorer les données de télémétrie avant qu’elles ne soient envoyées à partir du Kit de développement logiciel (SDK) en implémentant ITelemetryProcessor. Par exemple, vous pouvez réduire le volume de données de télémétrie en excluant les demandes des robots. Contrairement à l’échantillonnage, vous avez un contrôle total sur ce qui est envoyé ou ignoré, mais il affecte toutes les métriques basées sur les journaux agrégés. Selon la façon dont vous supprimez les éléments, vous risquez également de perdre la capacité de naviguer entre les éléments associés.

• Ajoutez ou modifiez des propriétés à toutes les données de télémétrie envoyées à partir de votre application en implémentant un ITelemetryInitializer. Par exemple, vous pouvez ajouter des valeurs calculées ou des numéros de version pour filtrer les données dans le portail.

• L’échantillonnage réduit le volume de données de télémétrie sans affecter vos statistiques. Il conserve les points de données associés afin que vous puissiez naviguer entre eux lorsque vous diagnostiquez un problème. Dans le portail, le nombre total est multiplié pour compenser l’échantillonnage.

Note

L’API sdk est utilisée pour envoyer des événements et des métriques personnalisés.

Filtrage

Cette technique vous permet de contrôler directement ce qui est inclus ou exclu du flux de télémétrie. Le filtrage peut être utilisé pour empêcher l'envoi des éléments de télémétrie à Application Insights. Vous pouvez utiliser le filtrage avec l’échantillonnage ou séparément.

Pour filtrer les données de télémétrie, vous écrivez un processeur de télémétrie et l’inscrivez auprès de TelemetryConfiguration. Toutes les données de télémétrie passent par votre processeur. Vous pouvez choisir de le supprimer du flux ou de le donner au processeur suivant dans la chaîne. Les données de télémétrie des modules standard, telles que le collecteur de requêtes HTTP et le collecteur de dépendances, et les données de télémétrie que vous avez suivies vous-même sont incluses. Vous pouvez, par exemple, filtrer la télémétrie concernant les requêtes émanant de robots ou les appels de dépendance réussis.

Avertissement

Le filtrage des données de télémétrie envoyées à partir du Kit de développement logiciel (SDK) à l’aide de processeurs peut fausser les statistiques que vous voyez dans le portail et compliquer le suivi des éléments connexes.

Au lieu de cela, envisagez d’utiliser l’échantillonnage.

ITelemetryProcessor et ITelemetryInitializer

Quelle est la différence entre les processeurs de télémétrie et les initialiseurs de télémétrie ?

• Il y a des chevauchements dans ce que vous pouvez faire avec eux. Les deux peuvent être utilisés pour ajouter ou modifier des propriétés de télémétrie, bien que nous vous recommandons d’utiliser des initialiseurs à cet effet.
• Les initialiseurs de télémétrie s’exécutent toujours avant les processeurs de télémétrie.
• Les initialiseurs de télémétrie peuvent être appelés plusieurs fois. Par convention, ils ne définissent aucune propriété qui a déjà été définie.
• Les processeurs de télémétrie vous permettent de remplacer ou d’ignorer complètement un élément de télémétrie.
• Tous les initialiseurs de télémétrie inscrits sont appelés pour chaque élément de télémétrie. Pour les processeurs de télémétrie, le SDK garantit l’appel du premier processeur de télémétrie. Si le reste des processeurs est appelé ou non est décidé par les processeurs de télémétrie précédents.
• Utilisez des initialiseurs de télémétrie pour enrichir les données de télémétrie avec davantage de propriétés ou remplacer un initialiseur existant. Utilisez un processeur de télémétrie pour filtrer les données de télémétrie.

Ajouter/modifier des propriétés

Utilisez des initialiseurs de télémétrie pour enrichir les données de télémétrie avec des informations supplémentaires ou pour remplacer les propriétés de télémétrie définies par les modules de télémétrie standard.

Par exemple, Application Insights pour un package web collecte des données de télémétrie sur les requêtes HTTP. Par défaut, il signale toute requête avec un code >de réponse =400 comme ayant échoué. Si vous souhaitez plutôt traiter 400 comme un succès, vous pouvez fournir un initialiseur de télémétrie qui configure la propriété de succès.

Si vous fournissez un initialiseur de télémétrie, il est appelé chaque fois que l’une des méthodes Track*() est appelée. Cet initialiseur inclut des Track() méthodes appelées par les modules de télémétrie standard. Par convention, ces modules ne définissent aucune propriété qui a déjà été définie par un initialiseur. Les initialiseurs de télémétrie sont appelés avant d’appeler des processeurs de télémétrie. Les enrichissements effectués par les initialiseurs sont donc visibles par les processeurs.

Initialiseurs de télémétrie

Pour enrichir les données de télémétrie avec des informations supplémentaires ou remplacer les propriétés de télémétrie définies par les modules de télémétrie standard, utilisez des initialiseurs de télémétrie.

Les initialiseurs de télémétrie définissent les propriétés de contexte envoyées avec chaque élément de télémétrie. Vous pouvez écrire vos propres initialiseurs pour définir des propriétés de contexte.

Les initialiseurs standard sont tous définis par les packages NuGet web ou WindowsServer :

Initialiseur	Descriptif
AccountIdTelemetryInitializer	Définit la propriété AccountId.
AuthenticatedUserIdTelemetryInitializer	Définit la propriété AuthenticatedUserId déterminée par le kit de développement logiciel (SDK) JavaScript.
AzureRoleEnvironmentTelemetryInitializer	Met à jour les propriétés RoleName et RoleInstance du contexte Device pour tous les éléments de télémétrie avec des informations extraites de l’environnement d’exécution Azure.
BuildInfoConfigComponentVersionTelemetryInitializer	Met à jour la propriété Version du contexte Component pour tous les éléments de télémétrie avec la valeur extraite du fichier BuildInfo.config produit par MS Build.
ClientIpHeaderTelemetryInitializer	Met à jour la propriété Ip du contexte Location de tous les éléments de télémétrie en fonction de l’en-tête HTTP X-Forwarded-For de la requête.
DeviceTelemetryInitializer	Met à jour les propriétés suivantes du contexte Device pour tous les éléments de télémétrie : • Type est défini sur PC. • Id est défini sur le nom de domaine de l'ordinateur sur lequel l'application web s’exécute. • OemName est défini sur la valeur extraite du champ Win32_ComputerSystem.Manufacturer en utilisant WMI. • Model est défini sur la valeur extraite du champ Win32_ComputerSystem.Model en utilisant WMI. • NetworkType est défini sur la valeur extraite de la propriété NetworkInterface. • Language est défini sur le nom de la propriété CurrentCulture.
DomainNameRoleInstanceTelemetryInitializer	Met à jour la propriété RoleInstance du contexte Device pour tous les éléments de télémétrie avec le nom de domaine de l'ordinateur sur lequel l'application web s’exécute.
OperationNameTelemetryInitializer	Met à jour la propriété Name de RequestTelemetry et la propriété Name du contexte Operation de tous les éléments de télémétrie basés sur la méthode HTTP, ainsi que les noms du contrôleur de ASP.NET MVC et de l’action appelée pour traiter la requête.
OperationIdTelemetryInitializer ou OperationCorrelationTelemetryInitializer	Met à jour la propriété du contexte Operation.Id de tous les éléments de télémétrie suivis lors de la gestion d’une requête avec la RequestTelemetry.Id générée automatiquement.
SessionTelemetryInitializer	Met à jour la propriété Id du contexte Session pour tous les éléments de télémétrie avec la valeur extraite du cookie ai_session généré par le code d’instrumentation JavaScript ApplicationInsights en cours d'exécution dans le navigateur de l'utilisateur.
SyntheticTelemetryInitializer ou SyntheticUserAgentTelemetryInitializer	Met à jour les propriétés de contexte User, Session et Operation de tous les éléments de télémétrie suivis lors du traitement d'une requête émanant d'une source synthétique, comme un test de disponibilité ou un robot de moteur de recherche. Par défaut, Metrics Explorer n'affiche pas la télémétrie synthétique. Ensemble de <Filters> qui identifie les propriétés des requêtes.
UserTelemetryInitializer	Met à jour les propriétés Id et AcquisitionDate du contexte User pour tous les éléments de télémétrie avec les valeurs extraites du cookie ai_user généré par le code d’instrumentation JavaScript Application  Insights en cours d'exécution dans le navigateur de l'utilisateur.
WebTestTelemetryInitializer	Définit l’ID utilisateur, l’ID de session et les propriétés de source synthétiques pour les requêtes HTTP provenant des tests de disponibilité. Ensemble de <Filters> qui identifie les propriétés des requêtes.

Note

Pour .NET applications s’exécutant dans Azure Service Fabric, vous pouvez inclure le package NuGet Microsoft.ApplicationInsights.ServiceFabric. Ce package comprend une propriété FabricTelemetryInitializer, qui ajoute des propriétés Service Fabric pour les éléments de télémétrie. Pour plus d’informations, consultez la page GitHub sur les propriétés ajoutées par ce package NuGet.

Ajouter ITelemetryInitializer

Ce blog décrit un projet pour diagnostiquer les problèmes de dépendance en envoyant automatiquement des pings réguliers aux dépendances.

1. Définir votre initialiseur

   using System;
   using Microsoft.ApplicationInsights.Channel;
   using Microsoft.ApplicationInsights.DataContracts;
   using Microsoft.ApplicationInsights.Extensibility;
   
   namespace MvcWebRole.Telemetry
   {
     /*
      * Custom TelemetryInitializer that overrides the default SDK
      * behavior of treating response codes >= 400 as failed requests
      *
      */
       public class MyTelemetryInitializer : ITelemetryInitializer
       {
           public void Initialize(ITelemetry telemetry)
           {
               var requestTelemetry = telemetry as RequestTelemetry;
               // Is this a TrackRequest() ?
               if (requestTelemetry == null) return;
               int code;
               bool parsed = Int32.TryParse(requestTelemetry.ResponseCode, out code);
               if (!parsed) return;
               if (code >= 400 && code < 500)
               {
                   // If we set the Success property, the SDK won't change it:
                   requestTelemetry.Success = true;
   
                   // Allow us to filter these requests in the portal:
                   requestTelemetry.Properties["Overridden400s"] = "true";
               }
               // else leave the SDK to set the Success property
           }
       }
   }
   

2. Charger votre initialiseur

ASP.NET

Option 1 : configuration dans le code

protected void Application_Start()
{
    // ...
    TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
}

Option 2 : configuration dans ApplicationInsights.config

<ApplicationInsights>
    <TelemetryInitializers>
    <!-- Fully qualified type name, assembly name: -->
    <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/>
    ...
    </TelemetryInitializers>
</ApplicationInsights>

Pour en savoir plus, consultez cet exemple.

Note

Vérifiez que le fichier applicationinsights.config se trouve dans votre répertoire de sortie et contient les modifications récentes.

ASP.NET Core

L'ajout d'un initialiseur à l'aide de ApplicationInsights.config ou TelemetryConfiguration.Active n'est pas valide pour les applications ASP.NET Core.

Pour les applications écrites à l’aide de ASP.NET Core, l’ajout d’un nouvel initialiseur de télémétrie est effectué en l’ajoutant au conteneur DependencyInjection, comme indiqué. Effectuez cette étape dans la Startup.ConfigureServices méthode.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

Note

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); fonctionne pour les initialiseurs simples. Pour les autres, builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); est nécessaire.

Supprimer initialiseurs de télémétrie

Par défaut, les initialiseurs de télémétrie sont présents. Pour supprimer tout ou partie des initialiseurs de télémétrie, utilisez l’exemple de code suivant après avoir appelé AddApplicationInsightsTelemetry().

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

// Remove all initializers
// This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.RemoveAll(typeof(ITelemetryInitializer));

var app = builder.Build();

Service Worker

L’ajout d’un initialiseur à l’aide ApplicationInsights.config ou TelemetryConfiguration.Active n’est pas valide pour le Kit de développement logiciel (SDK) du service Worker.

Pour les applications écrites à l’aide du service Worker, l’ajout d’un nouvel initialiseur de télémétrie est effectué en l’ajoutant au DependencyInjection conteneur, comme indiqué. Effectuez cette étape dans la Startup.ConfigureServices méthode.

    using Microsoft.ApplicationInsights.Extensibility;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
        services.AddApplicationInsightsTelemetryWorkerService();
    }

Supprimer initialiseurs de télémétrie

Les initialiseurs de télémétrie sont présents par défaut. Pour supprimer tout ou partie des initialiseurs de télémétrie, utilisez l’exemple de code suivant après avoir appelé AddApplicationInsightsTelemetryWorkerService().

   public void ConfigureServices(IServiceCollection services)
   {
        services.AddApplicationInsightsTelemetryWorkerService();
        // Remove a specific built-in telemetry initializer.
        var tiToRemove = services.FirstOrDefault<ServiceDescriptor>
                            (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
        if (tiToRemove != null)
        {
            services.Remove(tiToRemove);
        }

        // Remove all initializers.
        // This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
        services.RemoveAll(typeof(ITelemetryInitializer));
   }

Exemple ITelemetryInitializers

Ajouter une propriété personnalisée

L’exemple d’initialiseur suivant ajoute une propriété personnalisée à chaque télémétrie suivie.

public void Initialize(ITelemetry item)
{
    var itemProperties = item as ISupportProperties;
    if(itemProperties != null && !itemProperties.Properties.ContainsKey("customProp"))
    {
        itemProperties.Properties["customProp"] = "customValue";
    }
}

Ajouter un nom de rôle cloud et une instance de rôle cloud

Étape 1 : Écrire un telemetryInitializer personnalisé

L’exemple d’initialiseur suivant assigne le nom du rôle cloud pour toutes les données de télémétrie suivies.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;

namespace CustomInitializer.Telemetry
{
    public class MyTelemetryInitializer : ITelemetryInitializer
    {
        public void Initialize(ITelemetry telemetry)
        {
            if (string.IsNullOrEmpty(telemetry.Context.Cloud.RoleName))
            {
                //set custom role name here
                telemetry.Context.Cloud.RoleName = "Custom RoleName";
                telemetry.Context.Cloud.RoleInstance = "Custom RoleInstance";
            }
        }
    }
}

Étape 2 : Charger un initialiseur dans TelemetryConfiguration

ASP.NET

Dans le fichier ApplicationInsights.config :

    <ApplicationInsights>
      <TelemetryInitializers>
        <!-- Fully qualified type name, assembly name: -->
        <Add Type="CustomInitializer.Telemetry.MyTelemetryInitializer, CustomInitializer"/>
        ...
      </TelemetryInitializers>
    </ApplicationInsights>

Une autre méthode pour ASP.NET applications web consiste à instancier l’initialiseur dans le code. L’exemple suivant montre le code dans le fichier Global.aspx.cs :

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;

    protected void Application_Start()
    {
        // ...
        TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
    }

ASP.NET Core

Pour ajouter une nouvelle instance TelemetryInitializer, vous l’ajoutez au conteneur d’injection de dépendances. L’exemple suivant montre cette approche. Ajoutez ce code dans la ConfigureServices méthode de votre Startup.cs classe.

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;
 public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyTelemetryInitializer>();
}

Contrôler l’adresse IP du client utilisée pour les mappages de géolocalisation

L’exemple d’initialiseur suivant définit l’adresse IP du client, qui est utilisée pour le mappage de géolocalisation, au lieu de l’adresse IP du socket client, pendant l’ingestion de télémétrie.

public void Initialize(ITelemetry telemetry)
{
    var request = telemetry as RequestTelemetry;
    if (request == null) return true;
    request.Context.Location.Ip = "{client ip address}"; // Could utilize System.Web.HttpContext.Current.Request.UserHostAddress;   
    return true;
}

Processeurs de télémétrie

Les processeurs de télémétrie peuvent filtrer et modifier chaque élément de télémétrie avant son envoi au portail à partir du Kit de développement logiciel (SDK).

Implémentez ITelemetryProcessor

Les processeurs de télémétrie construisent une chaîne de traitement. Lorsque vous instanciez un processeur de télémétrie, vous obtenez une référence au processeur suivant dans la chaîne. Lorsqu’un point de données de télémétrie est passé à la méthode de processus, il effectue son travail, puis appelle (ou n’appelle pas) le processeur de télémétrie suivant dans la chaîne.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.DataContracts;

public class SuccessfulDependencyFilter : ITelemetryProcessor
{
    private ITelemetryProcessor Next { get; set; }

    // next will point to the next TelemetryProcessor in the chain.
    public SuccessfulDependencyFilter(ITelemetryProcessor next)
    {
        this.Next = next;
    }

    public void Process(ITelemetry item)
    {
        // To filter out an item, return without calling the next processor.
        if (!OKtoSend(item)) { return; }

        this.Next.Process(item);
    }

    // Example: replace with your own criteria.
    private bool OKtoSend (ITelemetry item)
    {
        var dependency = item as DependencyTelemetry;
        if (dependency == null) return true;

        return dependency.Success != true;
    }
}

Ajouter votre processeur

ASP.NET

Insérez cet extrait de code dans ApplicationInsights.config:

<TelemetryProcessors>
    <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9">
    <!-- Set public property -->
    <MyParamFromConfigFile>2-beta</MyParamFromConfigFile>
    </Add>
</TelemetryProcessors>

Vous pouvez transmettre des valeurs de chaîne à partir du fichier .config en fournissant des propriétés nommées publiques dans votre classe.

Avertissement

Veillez à faire correspondre le nom de type et tous les noms de propriétés du fichier .config aux noms de classe et de propriété dans le code. Si le fichier .config fait référence à un type ou à une propriété inexistants, le Kit de développement logiciel (SDK) peut échouer en mode silencieux pour envoyer des données de télémétrie.

Vous pouvez également initialiser le filtre dans le code. Dans une classe d’initialisation appropriée, par exemple, AppStart in Global.asax.cs, insérez votre processeur dans la chaîne :

Note

L’exemple de code suivant est obsolète, mais est mis à disposition ici pour la postérité. Envisagez de bien démarrer avec OpenTelemetry ou de migrer vers OpenTelemetry.

var builder = TelemetryConfiguration.Active.DefaultTelemetrySink.TelemetryProcessorChainBuilder;
builder.Use((next) => new SuccessfulDependencyFilter(next));

// If you have more processors:
builder.Use((next) => new AnotherProcessor(next));

builder.Build();

Les clients de télémétrie créés après ce point utilisent vos processeurs.

Processeur de télémétrie d'échantillonnage adaptatif (à partir de 2.0.0-beta3)

Cette fonctionnalité est activée par défaut. Si votre application envoie beaucoup de télémétrie, ce processeur en supprime une partie.

    <TelemetryProcessors>
        <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
        </Add>
    </TelemetryProcessors>

Le paramètre fournit la cible que l'algorithme essaie d'atteindre. Chaque instance du Kit de développement logiciel (SDK) fonctionne de manière indépendante. Ainsi, si votre serveur est un cluster de plusieurs ordinateurs, le volume réel des données de télémétrie est multiplié en conséquence.

En savoir plus sur l’échantillonnage.

Processeur de télémétrie d'échantillonnage à taux fixe (à partir de 2.0.0-beta1)

Il existe également un processeur de télémétrie d’échantillonnage standard (à partir de la version 2.0.1) :

    <TelemetryProcessors>
        <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

        <!-- Set a percentage close to 100/N where N is an integer. -->
        <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
        <SamplingPercentage>10</SamplingPercentage>
        </Add>
    </TelemetryProcessors>

ASP.NET Core

Note

L'ajout d'un processeur à l'aide de ApplicationInsights.config ou TelemetryConfiguration.Active n'est pas valide pour les applications ASP.NET Core ou si vous utilisez le Kit de développement logiciel (SDK) Microsoft.ApplicationInsights.WorkerService.

Pour ASP.NET Core, l’ajout d’un nouveau processeur de télémétrie est effectué à l’aide de la méthode d’extension AddApplicationInsightsTelemetryProcessor sur IServiceCollection, comme indiqué. Cette méthode est appelée dans la ConfigureServices méthode de votre Startup.cs classe.

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

Pour inscrire des processeurs de télémétrie qui ont besoin de paramètres dans ASP.NET Core, créez une classe personnalisée implémentant ITelemetryProcessorFactory. Appelez le constructeur avec les paramètres souhaités dans la méthode Create , puis utilisez AddSingleton<ITelemetryProcessorFactory, MyTelemetryProcessorFactory>().

Service Worker

Note

L'ajout d'un processeur à l'aide de ApplicationInsights.config ou TelemetryConfiguration.Active n'est pas valide pour les applications ASP.NET Core ou si vous utilisez le Kit de développement logiciel (SDK) Microsoft.ApplicationInsights.WorkerService.

Pour le service Worker, l’ajout d’un nouveau processeur de télémétrie est effectué à l’aide de la AddApplicationInsightsTelemetryProcessor méthode d’extension sur IServiceCollection, comme indiqué. Cette méthode est appelée dans la ConfigureServices méthode de votre Startup.cs classe.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();
        // If you have more processors:
        services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();
    }

Exemples de filtres

Demandes synthétiques

Filtrez les bots et les tests web. Bien que Metrics Explorer vous donne la possibilité de filtrer les sources synthétiques, cette option réduit la taille du trafic et de l’ingestion en les filtrant au niveau du SDK lui-même.

public void Process(ITelemetry item)
{
    if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
    
    // Send everything else:
    this.Next.Process(item);
}

Échec de l’authentification

Filtrez les requêtes avec une réponse « 401 ».

public void Process(ITelemetry item)
{
    var request = item as RequestTelemetry;

    if (request != null &&
    request.ResponseCode.Equals("401", StringComparison.OrdinalIgnoreCase))
    {
        // To filter out an item, return without calling the next processor.
        return;
    }

    // Send everything else
    this.Next.Process(item);
}

Excluez les appels de dépendance à distance rapides.

Si vous souhaitez diagnostiquer uniquement les appels lents, filtrez les appels rapides.

Note

Ce filtrage fausse les statistiques que vous voyez sur le portail.

public void Process(ITelemetry item)
{
    var request = item as DependencyTelemetry;

    if (request != null && request.Duration.TotalMilliseconds < 100)
    {
        return;
    }
    this.Next.Process(item);
}

Échantillonnage

Pour savoir comment configurer l’échantillonnage pour les applications ASP.NET et ASP.NET Core, consultez Sampling dans Application Insights.

Service Worker

Le Kit de développement logiciel (SDK) Application Insights pour Le service Worker prend en charge l’échantillonnage à débit fixe et l’échantillonnage adaptatif. L’échantillonnage adaptatif est activé par défaut. L’échantillonnage peut être désactivé à l’aide de l’option EnableAdaptiveSampling dans ApplicationInsightsServiceOptions.

Pour configurer d’autres paramètres d’échantillonnage, vous pouvez utiliser l’exemple suivant :

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.ApplicationInsights.Extensibility;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<TelemetryConfiguration>(telemetryConfiguration =>
{
   var telemetryProcessorChainBuilder = telemetryConfiguration.DefaultTelemetrySink.TelemetryProcessorChainBuilder;

   // Using adaptive sampling
   telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond: 5);

   // Alternately, the following configures adaptive sampling with 5 items per second, and also excludes DependencyTelemetry from being subject to sampling:
   // telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond:5, excludedTypes: "Dependency");
});

builder.Services.AddApplicationInsightsTelemetryWorkerService(new ApplicationInsightsServiceOptions
{
   EnableAdaptiveSampling = false,
});

var app = builder.Build();

Enrichir des données via HTTP

ASP.NET

var requestTelemetry = HttpContext.Current?.Items["Microsoft.ApplicationInsights.RequestTelemetry"] as RequestTelemetry;

if (requestTelemetry != null)
{
    requestTelemetry.Properties["myProp"] = "someData";
}

ASP.NET Core

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

Node.js

Dans cette section

• Filtrer et prétraiter les données de télémétrie
• Initialiseurs de télémétrie
• Processeur de télémétrie
• Échantillonnage
• Plusieurs rôles pour les applications multi-composants

Filtrer et prétraiter les données de télémétrie

Vous pouvez écrire du code pour filtrer, modifier ou enrichir vos données de télémétrie avant d’être envoyées à partir du Kit de développement logiciel (SDK). Le traitement inclut les données envoyées à partir des modules de télémétrie standard, tels que la collecte de requêtes HTTP et la collecte de dépendances.

• Le filtrage peut modifier ou ignorer les données de télémétrie avant qu’elles ne soient envoyées à partir du Kit de développement logiciel (SDK) en implémentant ITelemetryProcessor. Par exemple, vous pouvez réduire le volume de données de télémétrie en excluant les demandes des robots. Contrairement à l’échantillonnage, vous avez un contrôle total sur ce qui est envoyé ou ignoré, mais il affecte toutes les métriques basées sur les journaux agrégés. Selon la façon dont vous supprimez les éléments, vous risquez également de perdre la capacité de naviguer entre les éléments associés.

• Ajoutez ou modifiez des propriétés à toutes les données de télémétrie envoyées à partir de votre application en implémentant un ITelemetryInitializer. Par exemple, vous pouvez ajouter des valeurs calculées ou des numéros de version pour filtrer les données dans le portail.

• L’échantillonnage réduit le volume de données de télémétrie sans affecter vos statistiques. Il conserve les points de données associés afin que vous puissiez naviguer entre eux lorsque vous diagnostiquez un problème. Dans le portail, le nombre total est multiplié pour compenser l’échantillonnage.

Note

L’API sdk est utilisée pour envoyer des événements et des métriques personnalisés.

Filtrage

Cette technique vous permet de contrôler directement ce qui est inclus ou exclu du flux de télémétrie. Le filtrage peut être utilisé pour empêcher l'envoi des éléments de télémétrie à Application Insights. Vous pouvez utiliser le filtrage avec l’échantillonnage ou séparément.

Pour filtrer les données de télémétrie, vous écrivez un processeur de télémétrie et l’inscrivez auprès de TelemetryConfiguration. Toutes les données de télémétrie passent par votre processeur. Vous pouvez choisir de le supprimer du flux ou de le donner au processeur suivant dans la chaîne. Les données de télémétrie des modules standard, telles que le collecteur de requêtes HTTP et le collecteur de dépendances, et les données de télémétrie que vous avez suivies vous-même sont incluses. Vous pouvez, par exemple, filtrer la télémétrie concernant les requêtes émanant de robots ou les appels de dépendance réussis.

Avertissement

Le filtrage des données de télémétrie envoyées à partir du Kit de développement logiciel (SDK) à l’aide de processeurs peut fausser les statistiques que vous voyez dans le portail et compliquer le suivi des éléments connexes.

Au lieu de cela, envisagez d’utiliser l’échantillonnage.

ITelemetryProcessor et ITelemetryInitializer

Quelle est la différence entre les processeurs de télémétrie et les initialiseurs de télémétrie ?

• Il y a des chevauchements dans ce que vous pouvez faire avec eux. Les deux peuvent être utilisés pour ajouter ou modifier des propriétés de télémétrie, bien que nous vous recommandons d’utiliser des initialiseurs à cet effet.
• Les initialiseurs de télémétrie s’exécutent toujours avant les processeurs de télémétrie.
• Les initialiseurs de télémétrie peuvent être appelés plusieurs fois. Par convention, ils ne définissent aucune propriété qui a déjà été définie.
• Les processeurs de télémétrie vous permettent de remplacer ou d’ignorer complètement un élément de télémétrie.
• Tous les initialiseurs de télémétrie inscrits sont appelés pour chaque élément de télémétrie. Pour les processeurs de télémétrie, le SDK garantit l’appel du premier processeur de télémétrie. Si le reste des processeurs est appelé ou non est décidé par les processeurs de télémétrie précédents.
• Utilisez des initialiseurs de télémétrie pour enrichir les données de télémétrie avec davantage de propriétés ou remplacer un initialiseur existant. Utilisez un processeur de télémétrie pour filtrer les données de télémétrie.

Ajouter/modifier des propriétés

Utilisez des initialiseurs de télémétrie pour enrichir les données de télémétrie avec des informations supplémentaires ou pour remplacer les propriétés de télémétrie définies par les modules de télémétrie standard.

Par exemple, Application Insights pour un package web collecte des données de télémétrie sur les requêtes HTTP. Par défaut, il signale toute requête avec un code >de réponse =400 comme ayant échoué. Si vous souhaitez plutôt traiter 400 comme un succès, vous pouvez fournir un initialiseur de télémétrie qui configure la propriété de succès.

Si vous fournissez un initialiseur de télémétrie, il est appelé chaque fois que l’une des méthodes Track*() est appelée. Cet initialiseur inclut des Track() méthodes appelées par les modules de télémétrie standard. Par convention, ces modules ne définissent aucune propriété qui a déjà été définie par un initialiseur. Les initialiseurs de télémétrie sont appelés avant d’appeler des processeurs de télémétrie. Les enrichissements effectués par les initialiseurs sont donc visibles par les processeurs.

Processeurs de télémétrie

Vous pouvez traiter et filtrer les données collectées avant leur envoi pour les conserver en utilisant des processeurs de télémétrie. Les processeurs de télémétrie sont appelés un par un dans l’ordre dans lequel ils ont été ajoutés avant l’envoi de l’élément de télémétrie vers le cloud.

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

Si un processeur de télémétrie renvoie false, cet élément de télémétrie ne sera pas envoyé.

Tous les processeurs de télémétrie reçoivent des données de télémétrie et leur enveloppe à inspecter et à modifier. Ils reçoivent également un objet de contexte. Le contenu de cet objet est défini par le paramètre contextObjects lors de l’appel d’une méthode de suivi pour la télémétrie suivie manuellement. Pour les données de télémétrie collectées automatiquement, cet objet est rempli avec les informations de requête disponibles et le contenu des requêtes persistantes, tel qu’il est fourni par appInsights.getCorrelationContext() (si la corrélation de dépendance automatique est activée).

Le type de TypeScript pour un processeur de télémétrie est le suivant :

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

Par exemple, un processeur qui supprime les données de trace des exceptions peut être écrit et ajouté comme suit :

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

Ajouter un nom de rôle cloud et une instance de rôle cloud

Définissez le nom du rôle cloud via des balises de contexte directes :

var appInsights = require("applicationinsights");
appInsights.setup('CONNECTION_STRING').start();
appInsights.defaultClient.context.tags["ai.cloud.role"] = "your role name";
appInsights.defaultClient.context.tags["ai.cloud.roleInstance"] = "your role instance";

Définissez le nom du rôle cloud via le processeur de télémétrie :

var appInsights = require("applicationinsights");
appInsights.setup('CONNECTION_STRING').start();

appInsights.defaultClient.addTelemetryProcessor(envelope => {
    envelope.tags["ai.cloud.role"] = "your role name";
    envelope.tags["ai.cloud.roleInstance"] = "your role instance"
});

Échantillonnage

Par défaut, le Kit de développement logiciel (SDK) envoie toutes les données collectées au service Application Insights. Si vous souhaitez activer l’échantillonnage afin de réduire la quantité de données, définissez le champ samplingPercentage sur l’objet config d’un client. Définir samplingPercentage sur 100 (la valeur par défaut) signifie que toutes les données seront envoyées ; le définir sur 0 signifie que rien ne sera envoyé.

Si vous utilisez la corrélation automatique, toutes les données associées à une requête unique sont incluses ou exclues en tant qu’unité.

Ajoutez du code tel que le suivant pour activer l’échantillonnage :

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

Plusieurs rôles pour les applications multi-composants

Dans certains scénarios, votre application peut se composer de plusieurs composants que vous souhaitez instrumenter avec la même connection string. Vous voulez néanmoins toujours voir ces composants comme des unités distinctes dans le portail, comme s’ils utilisaient des chaînes de connexion distinctes. Ce serait par exemple le cas de nœuds distincts sur Cartographie d’application. Vous devez configurer manuellement le champ RoleName pour distinguer la télémétrie d’un composant des autres composants qui envoient des données à votre ressource Application Insights.

Utilisez le code suivant pour définir le champ RoleName :

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

Configuration du kit de développement logiciel (SDK)

.NET

Dans cette section

• Canaux de télémétrie
• Modules de télémétrie
• Désactiver la télémétrie
• chaîne de connexion
• Fournisseur ApplicationId

Vous pouvez personnaliser le Kit de développement logiciel (SDK) Application Insights pour ASP.NET, ASP.NET Core et Le service Worker pour modifier la configuration par défaut.

ASP.NET

Le kit SDK Application Insights .NET se compose de nombreux packages NuGet. Le package principal fournit l'API pour l'envoi des données télémétriques à Application Insights. Des packages supplémentaires fournissent les modules et les initialiseurs de télémétrie pour le suivi télémétrique automatique de votre application et de son contexte. La modification du fichier config permet d’activer ou de désactiver les modules et initialiseurs de télémétrie. Vous pouvez également définir les paramètres pour certains d’entre eux.

Le fichier config est nommé ApplicationInsights.config ou ApplicationInsights.xml. Le nom dépend du type de votre application. Il est automatiquement ajouté à votre projet lorsque vous installez la plupart des versions du kit de développement logiciel (SDK).

Par défaut, lorsque vous utilisez l’expérience automatisée à partir des projets de modèle Visual Studio qui prennent en charge Add>Application Insights Telemetry, le fichier ApplicationInsights.config est créé dans le dossier racine du projet. Après compilation, il est copié dans le dossier bin. Il est également ajouté à une application web par l’agent Application Insights sur un serveur IIS.

Important

Le fichier config est ignoré si l’extension pour les sites web Azure ou l’extension pour les machines virtuelles Azure et les groupes de machines virtuelles Azure identiques est utilisée.

Il n’existe aucun fichier équivalent permettant de contrôler le kit de développement logiciel (SDK) dans une page web.

ASP.NET Core

Dans ASP.NET Core applications, toutes les modifications de configuration sont apportées dans la méthode ConfigureServices() de votre classe Startup.cs, sauf indication contraire.

Note

Dans ASP.NET Core applications, la modification de la configuration en modifiant TelemetryConfiguration.Active n'est pas prise en charge.

Service Worker

La TelemetryConfiguration par défaut utilisée par le Kit de développement logiciel (SDK) Worker Service est similaire à la configuration automatique utilisée dans une application ASP.NET ou ASP.NET Core, moins les initialiseurs de télémétrie utilisés pour enrichir les données de télémétrie à partir de HttpContext.

Vous pouvez personnaliser le Kit de développement logiciel (SDK) Application Insights pour le service Worker afin de modifier la configuration par défaut. Les utilisateurs du Kit de développement logiciel (SDK) Application Insights ASP.NET Core peuvent être familiarisés avec la modification de la configuration à l’aide de l'injection de dépendances intégrée d'ASP.NET Core . Le Kit de développement logiciel (SDK) du service Worker est également basé sur des principes similaires. Apportez presque toutes les modifications de configuration dans la ConfigureServices() section en appelant les méthodes IServiceCollectionappropriées, comme indiqué dans la section suivante.

Note

Lorsque vous utilisez le Kit de développement logiciel (SDK) du service Worker, modifier la configuration via TelemetryConfiguration.Active n'est pas pris en charge et les modifications ne seront pas reflétées.

Canaux de télémétrie

Les canaux de télémétrie font partie intégrante des SDK Azure Application Insights. Ils gèrent la mise en mémoire tampon des données de télémétrie et leur transmission au service Application Insights. Les versions .NET et .NET Core des kits sdk ont deux canaux de télémétrie intégrés : InMemoryChannel et ServerTelemetryChannel. Cette section décrit chaque canal et montre comment personnaliser le comportement du canal.

Note

Pour examiner les questions fréquentes (FAQ), consultez les FAQ sur les canaux de télémétrie

Que sont les canaux de télémétrie ?

Les canaux de télémétrie gèrent la mise en mémoire tampon des éléments de télémétrie et la transmission de ces éléments au service Application Insights, où ils sont stockés pour être interrogés et analysés. Un canal de télémétrie est une classe qui implémente l’interface Microsoft.ApplicationInsights.ITelemetryChannel.

La méthode Send(ITelemetry item) d’un canal de télémétrie est appelée une fois que tous les initialiseurs et processeurs de télémétrie ont été appelés. Par conséquent, tous les éléments supprimés par un processeur de télémétrie n’atteignent pas le canal. La méthode Send() n’envoie généralement pas instantanément les éléments au back-end. Il les place généralement en mémoire tampon et les envoie par lots pour optimiser leur transmission.

Évitez d’appeler Flush(), sauf s’il est essentiel d’envoyer immédiatement des données de télémétrie mises en mémoire tampon. Utilisez-le uniquement dans des scénarios tels que l’arrêt de l’application, la gestion des exceptions ou lors de l’utilisation de processus de courte durée, tels que des travaux en arrière-plan ou des outils en ligne de commande. Dans les applications web ou les services de longue durée, le kit de développement logiciel (SDK) gère automatiquement l’envoi de données de télémétrie. Appeler Flush() inutilement peut entraîner des problèmes de niveau de performance.

Le flux de métriques temps réel a également un canal personnalisé pour le streaming en direct des données de télémétrie. Le présent document ne s’applique pas à ce canal, qui est indépendant du canal de télémétrie standard.

Canaux de télémétrie intégrés

Les kits SDK Application Insights .NET et .NET Core sont fournis avec deux canaux intégrés :

• InMemoryChannel : canal léger qui met en mémoire tampon les éléments en attendant qu’ils soient envoyés. Les éléments sont mis en mémoire tampon et vidés toutes les 30 secondes, ou dès que la mémoire tampon atteint 500 éléments. Ce canal offre des garanties de fiabilité minimales, car il ne retente pas l’envoi des éléments de télémétrie après un échec. Ce canal ne conserve pas non plus les éléments sur le disque. Ainsi, tous les éléments non envoyés sont perdus définitivement lors de l’arrêt de l’application, qu’il soit approprié ou non. Il implémente une méthode Flush() qui permet de forcer le vidage synchrone des éléments de télémétrie de la mémoire. Ce canal convient bien pour les applications d’exécution de courte durée où un vidage synchrone est la meilleure option.

  Ce canal fait partie du package NuGet Microsoft.ApplicationInsights plus grand et constitue le canal par défaut utilisé par le SDK si aucune autre configuration n’a été spécifiée.

• ServerTelemetryChannel : canal plus avancé qui offre des stratégies de nouvelles tentatives et la capacité de stocker des données sur un disque local. Ce canal retente d’envoyer les données de télémétrie si des erreurs temporaires se produisent. Il utilise également le stockage sur disque local pour conserver les éléments sur le disque durant les pannes réseau ou la génération de gros volumes de données de télémétrie. Grâce aux stratégies de nouvelles tentatives et au stockage sur disque local, ce canal est considéré comme plus fiable. Nous le recommandons pour tous les scénarios de production. Ce canal est la valeur par défaut pour les applications ASP.NET et ASP.NET Core configurées conformément à la documentation officielle. Il est optimisé pour les scénarios de serveur exécutant des processus de longue durée. La méthode Flush() implémentée par ce canal n’est pas synchrone.

  Ce canal est fourni dans le package NuGet Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel et est activé automatiquement quand vous utilisez le package NuGet Microsoft.ApplicationInsights.Web ou Microsoft.ApplicationInsights.AspNetCore.

Configurer un canal de télémétrie

Vous configurez un canal de télémétrie en l’ajoutant à la configuration de télémétrie active. Pour les applications ASP.NET, la configuration implique de définir l’instance de canal de télémétrie sur TelemetryConfiguration.Active ou en modifiant ApplicationInsights.config. Pour ASP.NET Core applications, la configuration implique l’ajout du canal au conteneur d’injection de dépendances.

Les sections suivantes présentent des exemples de configuration du paramètre StorageFolder pour le canal dans différents types d’applications. StorageFolder est juste l’un des paramètres configurables. Pour obtenir la liste complète des paramètres de configuration, consultez la section des paramètres configurables dans les canaux plus loin dans cet article.

ASP.NET

Option 1 : configuration dans le code

Le code suivant configure une instance ServerTelemetryChannel avec le paramètre StorageFolder défini à un emplacement personnalisé. Ajoutez ce code au début de l’application, généralement dans la méthode Application_Start() dans Global.aspx.cs.

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
protected void Application_Start()
{
    var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
    serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
    TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;
}

Option 2 : configuration dans ApplicationInsights.config

L’extrait suivant du fichier ApplicationInsights.config montre le canal ServerTelemetryChannel dont le paramètre StorageFolder est défini à un emplacement personnalisé :

    <TelemetrySinks>
        <Add Name="default">
            <TelemetryProcessors>
                <!-- Telemetry processors omitted for brevity -->
            </TelemetryProcessors>
            <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
                <StorageFolder>d:\temp\applicationinsights</StorageFolder>
            </TelemetryChannel>
        </Add>
    </TelemetrySinks>

ASP.NET Core

Modifiez la méthode ConfigureServices de la classe Startup.cs comme indiqué ici :

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

public void ConfigureServices(IServiceCollection services)
{
    // This sets up ServerTelemetryChannel with StorageFolder set to a custom location.
    services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() {StorageFolder = @"d:\temp\applicationinsights" });

    services.AddApplicationInsightsTelemetry();
}

Important

La configuration du canal à l'aide de TelemetryConfiguration.Active n'est pas prise en charge pour les applications ASP.NET Core.

Remplacement du ServerTelemetryChannel

Le canal de télémétrie par défaut est ServerTelemetryChannel. L'exemple suivant montre comment le remplacer.

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

// Use the following to replace the default channel with InMemoryChannel.
// This can also be applied to ServerTelemetryChannel.
builder.Services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

Note

Si vous voulez vider la mémoire tampon, consultez Vidage des données. Par exemple, vous pouvez avoir besoin de vider la mémoire tampon si vous utilisez le SDK dans une application qui s’arrête.

Service Worker

Le canal par défaut est ServerTelemetryChannel. Vous pouvez le remplacer comme l’illustre l’exemple suivant :

using Microsoft.ApplicationInsights.Channel;

    public void ConfigureServices(IServiceCollection services)
    {
        // Use the following to replace the default channel with InMemoryChannel.
        // This can also be applied to ServerTelemetryChannel.
        services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

        services.AddApplicationInsightsTelemetryWorkerService();
    }

Configuration dans le code pour les applications console

Pour les applications console, le code est identique pour .NET et .NET Core :

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

Détails du fonctionnement de ServerTelemetryChannel

ServerTelemetryChannel stocke les éléments entrants dans la mémoire tampon. Les éléments sont sérialisés, compressés et stockés dans une instance Transmission toutes les 30 secondes, ou dès que la mémoire tampon atteint 500 éléments. Une seule instance Transmission peut contenir jusqu’à 500 éléments de télémétrie, constituant un lot qui est envoyé au service Application Insights par le biais d’un appel HTTPS unique.

Par défaut, un maximum de 10 instances Transmission peuvent être envoyées en parallèle. Si les données de télémétrie arrivent à un rythme plus rapide, ou si le réseau ou le serveur back-end Application Insights est lent, les instances Transmission sont mises en mémoire tampon. La capacité par défaut de cette mémoire tampon Transmission est de 5 Mo. En cas de dépassement de la capacité mémoire, les instances Transmission sont stockées sur le disque local à hauteur de 50 Mo.

Les instances Transmission sont également stockées sur le disque local quand des problèmes réseau se produisent. Seuls les éléments stockés sur un disque local sont conservés après un plantage de l’application. Ils sont envoyés au redémarrage de l’application. Si les problèmes réseau persistent, ServerTelemetryChannel utilise une logique d’interruption exponentielle allant de 10 secondes à 1 heure avant de réessayer d’envoyer des données de télémétrie.

Paramètres configurables dans les canaux

Pour obtenir la liste complète des paramètres configurables de chaque canal, consultez :

• InMemoryChannel
• ServerTelemetryChannel

Voici les paramètres les plus couramment utilisés pour ServerTelemetryChannel :

• MaxTransmissionBufferCapacity : quantité de mémoire maximale, en octets, utilisée par le canal pour mettre les transmissions en mémoire tampon. Quand cette limite de capacité est atteinte, les nouveaux éléments sont stockés directement sur le disque local. La valeur par défaut est 5 Mo. Si vous définissez une valeur plus élevée pour réduire l’utilisation du disque, n’oubliez pas que les éléments en mémoire sont perdus en cas de plantage de l’application.

• MaxTransmissionSenderCapacity : nombre maximal d’instances Transmission envoyées simultanément à Application Insights. La valeur par défaut est 10. Ce paramètre peut être défini à un nombre plus élevé, ce qui est d’ailleurs recommandé si un gros volume de données de télémétrie doit être généré. Cette situation se produit habituellement pendant les tests de charge ou quand l’échantillonnage est désactivé.

• StorageFolder : dossier utilisé par le canal pour stocker les éléments sur le disque en fonction des besoins. Dans Windows, %LOCALAPPDATA% ou %TEMP% est utilisé si aucun autre chemin n’est spécifié explicitement. Dans les environnements autres que Windows, par défaut, les emplacements suivants sont utilisés (dans l’ordre) : %TMPDIR%, /var/tmp/ ou /tmp/.

Quel canal dois-je utiliser ?

Nous recommandons ServerTelemetryChannel pour la plupart des scénarios de production qui impliquent des applications de longue durée. Pour plus d’informations sur l’effacement des données de télémétrie, lisez l’article concernant l’utilisation de Flush().

Quand utiliser Flush()

La méthode Flush() envoie immédiatement toutes les données de télémétrie mises en mémoire tampon. Toutefois, elle ne doit être utilisée que dans des scénarios spécifiques.

Utilisez Flush() quand :

• L’application est sur le point d’arrêter et vous souhaitez vous assurer que la télémétrie est envoyée avant la sortie.
• Vous êtes dans un gestionnaire d’exceptions et devez vous assurer de la transmission de la télémétrie.
• Vous écrivez un processus de courte durée comme un travail en arrière-plan ou un outil CLI qui se termine rapidement.

Évitez d’utiliser Flush() dans des applications longues telles que des services web. Le kit de développement logiciel (SDK) gère automatiquement la mise en mémoire tampon et la transmission. Appeler Flush() inutilement peut entraîner des problèmes de niveau de performance et ne garantit pas que toutes les données sont envoyées, en particulier lors de l’utilisation de ServerTelemetryChannel, qui ne se vide pas de manière synchrone.

Modules de télémétrie

Application Insights collecte automatiquement des informations de télémétrie sur des charges de travail spécifiques sans qu’un suivi manuel ne soit nécessaire par l’utilisateur.

Par défaut, les modules de collecte automatique suivants sont activés. Vous pouvez les désactiver ou les configurer pour modifier leur comportement par défaut.

ASP.NET

Chaque module de télémétrie collecte un type de données précis et utilise l'API de base pour envoyer les données. Les modules sont installés par différents packages NuGet, qui ajoutent également les lignes requises dans le fichier .config.

Area	Descriptif
Suivi des requêtes	Collecte les données de télémétrie des requêtes (temps de réponse, code de résultat) pour les requêtes web entrantes. Module:Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule NuGet :Microsoft.ApplicationInsights.Web
Suivi des dépendances	Collecte les données de télémétrie sur les dépendances sortantes (appels HTTP, appels SQL). Pour travailler dans IIS, installez l’agent Application Insights. Vous pouvez également écrire un suivi des dépendances personnalisé en utilisant l’API TrackDependency. Prend en charge l’autoinstrumentation avec App Service et machines virtuelles et la surveillance des groupes de machines virtuelles identiques. Module:Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule NuGet :Microsoft.ApplicationInsights.DependencyCollector
Compteurs de performances	Collecte des compteurs de performance Windows (processeur, mémoire, charge réseau à partir des installations d'IIS). Spécifiez les compteurs (y compris les compteurs personnalisés). Pour plus d’informations, consultez Collecte les compteurs de performance système. Module:Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule NuGet :Microsoft.ApplicationInsights.PerfCounterCollector
Compteurs d’événements	Collecte .NET EventCounters. Recommandé pour ASP.NET Core et cross-platforme à la place des compteurs de performances Windows. Module:EventCounterCollectionModule (SDK ≥ 2.8.0)
Métriques en direct (QuickPulse)	Collecte les données de télémétrie pour le volet Métriques en direct. Module:QuickPulseTelemetryModule
Pulsations (App Service)	Envoie des pulsations et des métriques personnalisées pour l’environnement App Service. Module:AppServicesHeartbeatTelemetryModule
Pulsations (machines virtuelles et de groupes de machines virtuelles identiques)	Envoie des signaux de pulsation et des métriques personnalisées pour l’environnement des machines virtuelles Azure. Module:AzureInstanceMetadataTelemetryModule
Télémétrie des diagnostics	Signale des erreurs dans le code d’instrumentation Application Insights (par exemple, compteurs manquants, exceptions ITelemetryInitializer). La télémétrie de trace s’affiche dans Recherche de diagnostic. Module:Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule NuGet :Microsoft.ApplicationInsights Remarque : si vous installez simplement ce package, le fichier ApplicationInsights.config n’est pas automatiquement créé.
Mode développeur (débogueur attaché)	Force TelemetryChannel à envoyer des éléments immédiatement lorsque le débogueur est attaché. Réduit la latence, mais augmente la surcharge processeur/réseau. Module:Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule NuGet :Application Insights Windows Server
Suivi des exceptions (web)	Suit le nombre d’exceptions non traitées dans les applications web. Consultez Échecs et exceptions. Module:Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule NuGet :Microsoft.ApplicationInsights.Web
Suivi des exceptions (non observé/non géré)	Effectue le suivi des exceptions de tâche non traitées et des exceptions non gérées pour les rôles de travail, les services Windows et les applications console. Modules :  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule NuGet :Microsoft.ApplicationInsights.WindowsServer
Suivi EventSource	Envoie les événements EventSource configurés à Application Insights en tant que traces. Module:Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule NuGet :Microsoft.ApplicationInsights.EventSourceListener
Collecteur ETW	Envoie des événements du fournisseur ETW configurés à Application Insights en tant que traces. Module:Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule NuGet :Microsoft.ApplicationInsights.EtwCollector
API principale (pas un module)	API principale utilisée par d’autres composants de télémétrie et pour la télémétrie personnalisée. Module:Microsoft.ApplicationInsights package NuGet :Microsoft.ApplicationInsights Remarque : si vous installez simplement ce package, le fichier ApplicationInsights.config n’est pas automatiquement créé.

ASP.NET Core

Area	Descriptif
Suivi des requêtes	Suivi des demandes intégré via l'intégration d'Application Insights avec ASP.NET Core. Module :Aucune classe de module distincte. NuGet :Microsoft.ApplicationInsights.AspNetCore
Suivi des dépendances	Via le collecteur de dépendance. NuGet :Microsoft.ApplicationInsights.DependencyCollector
Compteurs de performances	Windows uniquement ! Sur plusieurs plateformes, utilisez EventCounterCollectionModule (voir la ligne suivante). NuGet :Microsoft.ApplicationInsights.PerfCounterCollector
Compteurs d’événements	Collecte .NET EventCounters. Recommandé pour ASP.NET Core et cross-platforme à la place des compteurs de performances Windows. Module :EventCounterCollectionModule (kit de développement logiciel (SDK) 2.8.0 et versions ultérieures) NuGet :Microsoft.ApplicationInsights.EventCounterCollector
Métriques en direct (QuickPulse)	Live Metrics activées dans l'intégration d'Application Insights avec ASP.NET Core. Module :Aucune classe de module distincte. NuGet :Microsoft.ApplicationInsights.AspNetCore
Collecteur de pulsations (App Service)	Envoie des pulsations (en tant que métriques personnalisées) avec des détails sur l’environnement App Service. Intégré via le kit de développement logiciel (SDK) de base lorsqu’il est hébergé dans App Service. Module :Aucune classe de module distincte. NuGet :Microsoft.ApplicationInsights.AspNetCore
Collecteur de pulsations (machines virtuelles et groupes de machines virtuelles identiques)	Envoie des pulsations (en tant que métriques personnalisées) avec des détails sur l’environnement de machine virtuelle Azure. Intégré par défaut via le SDK de base lorsqu’il est hébergé sur des machines virtuelles Azure ou des groupes de machines virtuelles identiques Azure. Module :Aucune classe de module distincte. NuGet :Microsoft.ApplicationInsights.AspNetCore
Télémétrie des diagnostics	Signale des erreurs dans le code d’instrumentation Application Insights lui-même (par exemple, ne peut pas accéder aux compteurs de performance, ITelemetryInitializer lève une exception). La télémétrie de trace s’affiche dans Recherche de diagnostic. Module:Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule NuGet :Microsoft.ApplicationInsights
Mode développeur (débogueur attaché)	Même comportement disponible ; la classe fait partie du package Windows Server. Module:Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule NuGet :Microsoft.ApplicationInsights.WindowsServer
Suivi des exceptions (web)	Intégration d’Application Insights pour le suivi automatique des exceptions dans ASP.NET Core Module :Aucune classe de module distincte. NuGet :Microsoft.ApplicationInsights.AspNetCore
Suivi des exceptions (non observé/non géré)	Comportement similaire via ASP.NET Core runtime/intégration ; les noms de classes sont Windows Server spécifiques. NuGet :Microsoft.ApplicationInsights.WindowsServer
Suivi EventSource	Envoie les événements EventSource configurés à Application Insights en tant que traces. Module:Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule NuGet :Microsoft.ApplicationInsights.EventSourceListener
Collecteur ETW	Windows uniquement (ETW). Envoie des événements du fournisseur ETW configurés à Application Insights en tant que traces. Module:Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule NuGet :Microsoft.ApplicationInsights.EtwCollector
API principale (pas un module)	API principale utilisée par d’autres composants de télémétrie et pour la télémétrie personnalisée. Module:Microsoft.ApplicationInsights package NuGet :Microsoft.ApplicationInsights

Configurer des modules de télémétrie

ASP.NET

Utilisez la section TelemetryModules dans ApplicationInsights.config pour configurer, ajouter ou supprimer des modules. Les exemples suivants :

• Configurer DependencyTrackingTelemetryModule (activer l’injection d’en-tête W3C).
• Configurer EventCounterCollectionModule (effacer les valeurs par défaut et ajouter un compteur unique).
• Désactiver la collecte des compteurs de performance en supprimant PerformanceCollectorModule.

<ApplicationInsights>
  <TelemetryModules>

    <!-- Dependency tracking -->
    <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
      <!-- Match Core example: enable W3C header injection -->
      <EnableW3CHeadersInjection>true</EnableW3CHeadersInjection>
    </Add>

    <!-- EventCounterCollectionModule: add a single counter (if you use event counters) -->
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.EventCounterCollectionModule, Microsoft.AI.PerfCounterCollector">
      <Counters>
        <!-- Mirrors Core example: only collect 'gen-0-size' from System.Runtime -->
        <Add ProviderName="System.Runtime" CounterName="gen-0-size" />
      </Counters>
    </Add>

    <!-- PerformanceCollectorModule (classic Windows performance counters).
         To DISABLE perf-counter collection, do NOT include this module.
         If it already exists in your file, remove or comment it out.
         Example of the line you would remove:
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector" />
    -->

  </TelemetryModules>
</ApplicationInsights>

Note

L’ensemble exact de modules présents dans votre ApplicationInsights.config dépend des packages SDK que vous avez installés.

ASP.NET Core

Option 1 : configurer des modules de télémétrie en utilisant ConfigureTelemetryModule

Pour configurer tout TelemetryModule par défaut, utilisez la méthode d’extension ConfigureTelemetryModule<T> sur IServiceCollection, comme illustré dans l’exemple suivant :

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

// The following removes PerformanceCollectorModule to disable perf-counter collection.
// Similarly, any other default modules can be removed.
var performanceCounterService = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

Option 2 : configurer des modules de télémétrie en utilisant ApplicationInsightsServiceOptions

Dans les versions 2.12.2 et ultérieures du kit de développement logiciel (SDK), vous pouvez modifier quelques paramètres courants en passant ApplicationInsightsServiceOptions à AddApplicationInsightsTelemetry, comme dans cet exemple :

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables live metrics (also known as QuickPulse).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

Cette table comprend la liste complète des paramètres ApplicationInsightsServiceOptions :

Réglage	Descriptif	Par défaut
EnablePerformanceCounterCollectionModule	Activer/désactiver PerformanceCounterCollectionModule.	Vrai
Activer le module de télémétrie de suivi des requêtes	Activer/désactiver RequestTrackingTelemetryModule.	Vrai
EnableEventCounterCollectionModule	Activer/désactiver EventCounterCollectionModule.	Vrai
Activer le module de télémétrie de suivi des dépendances	Activer/désactiver DependencyTrackingTelemetryModule.	Vrai
Activer le Module de Télémétrie "Heartbeat" des Services Applicatifs	Activer/désactiver AppServicesHeartbeatTelemetryModule.	Vrai
Activer le module de télémétrie des métadonnées d'instance Azure	Activer/désactiver AzureInstanceMetadataTelemetryModule.	Vrai
EnableQuickPulseMetricStream	Active/désactive la fonctionnalité LiveMetrics.	Vrai
ActiverÉchantillonnageAdaptatif	Active/désactive l’échantillonnage adaptatif.	Vrai
Activer le battement de cœur	Active/désactive la fonctionnalité des pulsations. Il envoie régulièrement (par défaut, 15 minutes) une métrique personnalisée nommée HeartbeatState avec des informations sur le runtime comme .NET version et les informations d’environnement Azure, le cas échéant.	Vrai
AddAutoCollectedMetricExtractor	Activez/désactivez le AutoCollectedMetrics extractor. Ce processeur de télémétrie envoie des métriques préagrégées relatives aux requêtes/dépendances avant l’échantillonnage.	Vrai
RequestCollectionOptions.TrackExceptions	Active/désactive la création de rapports de suivi des exceptions non gérées par le module de collecte des requêtes.	False dans netstandard2.0 (car les exceptions sont suivies avec ApplicationInsightsLoggerProvider). True sinon.
Activer le module de télémétrie de diagnostics	Activer/désactiver DiagnosticsTelemetryModule. Si l’élément est désactivé, les paramètres suivants sont ignorés : EnableHeartbeat, EnableAzureInstanceMetadataTelemetryModule et EnableAppServicesHeartbeatTelemetryModule.	Vrai

Pour obtenir la liste la plus à jour, consultez les paramètres configurables dans ApplicationInsightsServiceOptions.

Recommandation de configuration pour le kit de développement logiciel (SDK) Microsoft.ApplicationInsights.AspNetCore 2.15.0 et versions ultérieures

Dans le SDK Microsoft.ApplicationInsights.AspNetCore 2.15.0 et versions ultérieures, configurez tous les paramètres disponibles dans ApplicationInsightsServiceOptions, y compris ConnectionString. Utilisez l’instance IConfiguration de l’application. Les paramètres doivent se trouver sous la section ApplicationInsights, comme indiqué dans l’exemple suivant. La section suivante de appsettings.json configure le connection string et désactive l’échantillonnage adaptatif et la collecte de compteurs de performances.

{
    "ApplicationInsights": {
    "ConnectionString": "<YOUR-CONNECTION-STRING>",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

Si builder.Services.AddApplicationInsightsTelemetry(aiOptions) pour ASP.NET Core 6.0 ou services.AddApplicationInsightsTelemetry(aiOptions) pour ASP.NET Core 3.1 et versions antérieures est utilisé, il remplace les paramètres de Microsoft.Extensions.Configuration.IConfiguration.

Service Worker

Option 1 : configurer des modules de télémétrie en utilisant ConfigureTelemetryModule

Application Insights utilise des modules de télémétrie pour collecter automatiquement des données de télémétrie sur des charges de travail spécifiques sans nécessiter de suivi manuel.

Les modules de collecte automatique suivants sont activés par défaut. Ces modules sont chargés de collecter automatiquement les données de télémétrie. Vous pouvez les désactiver ou les configurer pour modifier leur comportement par défaut.

• DependencyTrackingTelemetryModule
• PerformanceCollectorModule
• QuickPulseTelemetryModule
• AppServicesHeartbeatTelemetryModule (il existe actuellement un problème impliquant ce module de télémétrie. Pour obtenir une solution de contournement temporaire, consultez GitHub Problème 1689.)
• AzureInstanceMetadataTelemetryModule

Pour configurer n’importe quel module de télémétrie par défaut, utilisez la méthode d'extension ConfigureTelemetryModule sur IServiceCollection, comme illustré dans l’exemple suivant :

    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();

            // The following configures QuickPulseTelemetryModule.
            // Similarly, any other default modules can be configured.
            services.ConfigureTelemetryModule<QuickPulseTelemetryModule>((module, o) =>
            {
                module.AuthenticationApiKey = "<YOUR-API-KEY-HERE>";
            });

            // The following removes PerformanceCollectorModule to disable perf-counter collection.
            // Similarly, any other default modules can be removed.
            var performanceCounterService = services.FirstOrDefault<ServiceDescriptor>
                                        (t => t.ImplementationType == typeof(PerformanceCollectorModule));
            if (performanceCounterService != null)
            {
                services.Remove(performanceCounterService);
            }
    }

Option 2 : configurer des modules de télémétrie en utilisant ApplicationInsightsServiceOptions

Vous pouvez modifier quelques paramètres courants en passant de ApplicationInsightsServiceOptions à AddApplicationInsightsTelemetryWorkerService, comme dans cet exemple :

using Microsoft.ApplicationInsights.WorkerService;

public void ConfigureServices(IServiceCollection services)
{
    var aiOptions = new ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

    // Disables live metrics (also known as QuickPulse).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetryWorkerService(aiOptions);
}

Le ApplicationInsightsServiceOptions de ce KIT de développement logiciel (SDK) se trouve dans l’espace de noms Microsoft.ApplicationInsights.WorkerService par opposition à Microsoft.ApplicationInsights.AspNetCore.Extensions dans le kit SDK ASP.NET Core.

Le tableau suivant répertorie les paramètres couramment utilisés dans ApplicationInsightsServiceOptions.

Réglage	Descriptif	Par défaut
EnableQuickPulseMetricStream	Activez/désactivez la fonctionnalité de métriques actives.	Vrai
ActiverÉchantillonnageAdaptatif	Active/désactive l’échantillonnage adaptatif.	Vrai
Activer le battement de cœur	Activez/désactivez la fonctionnalité Pulsations, qui envoie périodiquement (15 minutes par défaut) une métrique personnalisée nommée « HeartBeatState » avec des informations sur le runtime comme .NET version et l’environnement Azure, le cas échéant.	Vrai
AddAutoCollectedMetricExtractor	Activez/Désactivez l'extracteur AutoCollectedMetrics, qui est un processeur de télémétrie envoyant des métriques préagrégées sur les requêtes/dépendances avant l’échantillonnage.	Vrai
Activer le module de télémétrie de diagnostics	Activer/désactiver DiagnosticsTelemetryModule. La désactivation de ce paramètre entraîne l’ignorer des paramètres suivants : EnableHeartbeat, EnableAzureInstanceMetadataTelemetryModuleet EnableAppServicesHeartbeatTelemetryModule.	Vrai

Pour obtenir la liste la plus récente, consultez les paramètres configurables dans ApplicationInsightsServiceOptions.

Désactiver la télémétrie

ASP.NET

Il existe un nœud dans le fichier de configuration pour chaque module. Pour désactiver un module, supprimez le nœud ou commentez-le.

ASP.NET Core

Si vous souhaitez désactiver la télémétrie de manière conditionnelle et dynamique, vous pouvez résoudre l’instance TelemetryConfiguration avec un conteneur d’injection de dépendances ASP.NET Core n’importe où dans votre code et définir l’indicateur DisableTelemetry sur celui-ci.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

L’exemple de code précédent empêche l’envoi de données de télémétrie à Application Insights. Il n'empêche pas les modules de collecte automatique de collecter des données de télémétrie. Si vous voulez supprimer un module de collecte automatique particulier, consultez les modules de télémétrie.

Service Worker

Si vous souhaitez désactiver la télémétrie de manière conditionnelle et dynamique, vous pouvez résoudre l’instance TelemetryConfiguration avec un conteneur d’injection de dépendances ASP.NET Core n’importe où dans votre code et définir l’indicateur DisableTelemetry sur celui-ci.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
    {
        configuration.DisableTelemetry = true;
        ...
    }

chaîne de connexion

Ce paramètre détermine la ressource Application Insights dans laquelle vos données s’affichent. En règle générale, vous créez une ressource distincte, avec un connection string distinct, pour chacune de vos applications.

Consultez Chaînes de connexion dans Application Insights pour obtenir des exemples de code.

Si vous souhaitez définir l’connection string dynamiquement, par exemple, pour envoyer des résultats de votre application à différentes ressources, vous pouvez omettre le connection string du fichier de configuration et le définir dans le code à la place.

ASP.NET

Pour définir la connection string pour toutes les instances de TelemetryClient, y compris les modules de télémétrie standard, effectuez cette étape dans une méthode d’initialisation, telle que global.aspx.cs dans un service ASP.NET :

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.ConnectionString = "<YOUR-CONNECTION-STRING>";
        var telemetryClient = new TelemetryClient(configuration);

Si vous souhaitez simplement envoyer un ensemble spécifique d’événements à une autre ressource, vous pouvez définir la clé pour un client de télémétrie spécifique :

    var tc = new TelemetryClient();
    tc.Context.ConnectionString = "<YOUR-CONNECTION-STRING>";
    tc.TrackEvent("myEvent");
    // ...

Pour obtenir une nouvelle connection string, créer une nouvelle ressource dans le portail Application Insights.

ASP.NET Core

Dans ASP.NET Core, configurez la chaîne de connexion dans Program.cs lors du démarrage de l’application en utilisant le TelemetryConfiguration fourni par le conteneur d'injection de dépendance (DI) :

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

// Resolve TelemetryConfiguration from DI and set the connection string
var config = app.Services.GetRequiredService<TelemetryConfiguration>();
config.ConnectionString = "<YOUR-CONNECTION-STRING>";

app.Run();

Si vous souhaitez envoyer un ensemble spécifique d’événements à une autre ressource, vous pouvez créer une instance TelemetryClient et définir son connection string explicitement :

using Microsoft.ApplicationInsights;

var tc = new TelemetryClient();
tc.Context.ConnectionString = "<YOUR-CONNECTION-STRING>";
tc.TrackEvent("myEvent");
// ...

Fournisseur ApplicationId

Note

Pour ASP.NET, ce fournisseur est disponible à partir du Kit de développement logiciel (SDK) v2.6.0*.

L’objectif de ce fournisseur est de rechercher un ID d’application basé sur un connection string. L’ID d’application est inclus dans RequestTelemetry et DependencyTelemetry, et est utilisé pour déterminer la corrélation dans le portail.

Cette fonctionnalité est disponible en définissant TelemetryConfiguration.ApplicationIdProvider.

Interface : IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string connectionString, out string applicationId);
}

Nous fournissons deux implémentations dans le kit de développement logiciel (SDK) Microsoft.ApplicationInsights : ApplicationInsightsApplicationIdProvider et DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Ce wrapper est destiné à notre API de profil. Il limite les demandes et les résultats du cache. Ce fournisseur est inclus automatiquement lorsque vous installez Microsoft.ApplicationInsights.DependencyCollector ou Microsoft.ApplicationInsights.Web.

La classe expose une propriété facultative appelée ProfileQueryEndpoint. https://dc.services.visualstudio.com/api/profiles/{0}/appId est sélectionné par défaut.

Si vous devez configurer un proxy, nous vous recommandons de rediriger l’adresse de base via proxy et de vérifier que le chemin inclut /api/profiles/{0}/appId. Au moment de l’exécution, {0} est remplacé par la connection string pour chaque requête.

ASP.NET

Exemple de configuration via ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Exemple de configuration en utilisant du code

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

ASP.NET Core

Note

Dans ASP.NET Core, il n'existe aucun fichier ApplicationInsights.config. La configuration est effectuée via l’injection de dépendances (DI) dans Program.cs ou Startup.cs.

Vous pouvez remplacer le fournisseur par défaut ou personnaliser son ProfileQueryEndpoint.

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

// Replace default provider with custom configuration
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new ApplicationInsightsApplicationIdProvider
    {
        ProfileQueryEndpoint = "https://custom-proxy/api/profiles/{0}/appId"
    });

var app = builder.Build();
app.Run();

DictionaryApplicationIdProvider

Ce fournisseur statique s’appuie sur vos paires connection string/ID d’application configurées.

Cette classe a la propriété Defined, qui est une Dictionary<string,string> de paires de chaînes de connexion et d'identifiants d'application.

Cette classe a la propriété facultative Next, qui peut être utilisée pour configurer un autre fournisseur à utiliser lorsqu'un connection string est demandé qui n'existe pas dans votre configuration.

ASP.NET

Exemple de configuration via ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="ConnectionString_1" value="ApplicationId_1"/>
            <Type key="ConnectionString_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Exemple de configuration en utilisant du code

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"ConnectionString_1", "ApplicationId_1"},
        {"ConnectionString_2", "ApplicationId_2"}
    }
};

ASP.NET Core

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Register DictionaryApplicationIdProvider
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new DictionaryApplicationIdProvider
    {
        Defined = new Dictionary<string, string>
        {
            { "ConnectionString_1", "ApplicationId_1" },
            { "ConnectionString_2", "ApplicationId_2" }
        },
        Next = new ApplicationInsightsApplicationIdProvider() // optional fallback
    });

var app = builder.Build();
app.Run();

Node.js

Dans cette section

• chaîne de connexion
• Option de configuration avancée
• Instrumentation tierce automatique

L’objet appInsights fournit de nombreuses méthodes de configuration. Elles sont répertoriées dans l’extrait de code suivant avec leurs valeurs par défaut.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

Pour mettre pleinement en corrélation les événements dans un service, veillez à définir .setAutoDependencyCorrelation(true). Lorsque cette option est définie, le kit de développement logiciel (SDK) peut effectuer le suivi de contexte entre les rappels asynchrones dans Node.js.

Passez en revue leurs descriptions dans les indications des types intégrés de l’IDE ou dans applicationinsights.ts pour obtenir des informations détaillées et des arguments secondaires facultatifs.

Note

Par défaut setAutoCollectConsole est configuré pour exclure les appels à console.log et à d’autres méthodes de console. Seuls les appels aux enregistreurs d’événements tiers pris en charge (par exemple, winston et bunyan) sont collectés. Vous pouvez modifier ce comportement pour inclure des appels aux méthodes console à l’aide de setAutoCollectConsole(true, true).

chaîne de connexion

Ce paramètre détermine la ressource Application Insights dans laquelle vos données s’affichent. En règle générale, vous créez une ressource distincte, avec un connection string distinct, pour chacune de vos applications.

Consultez Chaînes de connexion dans Application Insights pour obtenir des exemples de code.

Si vous souhaitez définir l’connection string dynamiquement, par exemple, pour envoyer des résultats de votre application à différentes ressources, vous pouvez omettre le connection string du fichier de configuration et le définir dans le code à la place.

Utiliser plusieurs chaînes de connexion

Vous pouvez créer plusieurs ressources Application Insights et envoyer différentes données à chacune d’entre elles à l’aide de leurs chaînes de connexion respectives.

Par exemple:

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

Options de configuration avancées

L’objet client contient une propriété config avec de nombreux paramètres facultatifs pour les scénarios avancés. Pour les définir, utilisez :

client.config.PROPERTYNAME = VALUE;

Ces propriétés étant spécifiques au client, vous pouvez configurer appInsights.defaultClient séparément des clients créés avec new appInsights.TelemetryClient().

Propriété	Descriptif
connectionString	Un identificateur pour votre ressource Application Insights.
endpointUrl	Le point de terminaison d’ingestion auquel envoyer les charges utiles de télémétrie.
quickPulseHost	L’hôte Flux de métriques temps réel auquel envoyer la télémétrie des métriques en temps réel.
proxyHttpUrl	Serveur proxy pour le trafic HTTP du SDK. (Facultatif. La valeur par défaut est extraite de la variable d’environnement http_proxy.)
proxyHttpsUrl	Serveur proxy pour le trafic HTTPS du SDK. (Facultatif. La valeur par défaut est extraite de la variable d’environnement https_proxy.)
httpAgent	Agent HTTP à utiliser pour le trafic HTTP du SDK. (Facultatif. La valeur par défaut n’est pas définie.)
httpsAgent	Agent HTTPS à utiliser pour le trafic HTTPS du SDK. (Facultatif. La valeur par défaut n’est pas définie.)
maxBatchSize	Le nombre maximal d’éléments de télémétrie à inclure dans une charge utile pour le point de terminaison d’ingestion. (La valeur par défaut est 250.)
maxBatchIntervalMs	Délai d’attente maximal pour qu’une charge utile atteigne maxBatchSize. (La valeur par défaut est 15000.)
DésactiverAppInsights	Indicateur spécifiant si la transmission de la télémétrie est désactivée. (La valeur par défaut est false.)
pourcentage d'échantillonnage	Le pourcentage d’éléments de télémétrie suivis qui doivent être transmis. (La valeur par défaut est 100.)
correlationIdRetryIntervalMs	Délai d’attente avant une nouvelle tentative de récupération de l’ID pour la corrélation entre composants. (La valeur par défaut est 30000.)
Domaines exclus de l'en-tête de corrélation	Liste des domaines à exclure de l’injection d’en-tête de corrélation entre composants. (Valeur par défaut. Voir Config.ts.)

Instrumentation tierce automatique

Pour suivre le contexte entre les appels asynchrones, certaines modifications sont nécessaires dans les bibliothèques de tiers, comme MongoDB et Redis. Par défaut, Application Insights utilisera diagnostic-channel-publishers afin de créer des MonkeyPatch pour certaines de ces bibliothèques. Cette fonctionnalité peut être désactivée en définissant la variable d’environnement APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL.

Note

En définissant cette variable d’environnement, les événements peuvent ne plus être associés correctement à l’opération appropriée.

Les MonkeyPatch individuels peuvent être désactivés en définissant la variable d’environnement APPLICATION_INSIGHTS_NO_PATCH_MODULES sur une liste séparée par des virgules de packages à désactiver. Par exemple, utilisez APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis pour éviter la mise à jour corrective des packages console et redis.

Il y a actuellement neuf packages instrumentés : bunyan, console, mongodb, mongodb-core, mysql, redis, winston, pg et pg-pool. Pour plus d’informations sur la version exacte de ces packages corrigés, consultez le fichier README de diagnostic-channel-publishers.

Les correctifs bunyan, winston et console génèrent des événements de suivi Application Insights selon si setAutoCollectConsole est activé ou non. Le reste génère des événements de dépendance Application Insights selon si setAutoCollectDependencies est activé ou non.

Ajout d’une surveillance côté client

.NET

Les sections précédentes ont fourni des indications sur les méthodes permettant de configurer automatiquement et manuellement l’analyse côté serveur. Pour ajouter l’analyse côté client, utilisez notre Kit de développement logiciel (SDK) JavaScript côté client. Vous pouvez monitorer les transactions côté client d’une page web en ajoutant un Script de chargement du Kit de développement logiciel (SDK) JavaScript (web) avant la balise </head> de clôture du HTML de la page.

Bien qu’il soit possible d’ajouter manuellement le script de chargement du kit de développement logiciel (SDK) JavaScript (web) à l’en-tête de chaque page HTML, nous vous recommandons plutôt d’ajouter le script de chargement du kit de développement logiciel (SDK) JavaScript (web) à une page principale. Cette action introduit le script de chargement du kit de développement logiciel (SDK) JavaScript (web) dans toutes les pages d’un site.

ASP.NET

Pour l’application ASP.NET MVC basée sur un modèle à partir de cet article, le fichier que vous devez modifier est _Layout.cshtml. Vous pouvez le retrouver sous Affichage>Partagé. Pour ajouter l’analyse côté client, ouvrez le fichier _Layout.cshtml et suivez les instructions de configuration basées sur le script de chargement du kit de développement logiciel (SDK) JavaScript (web) de l’article sur la configuration du kit de développement logiciel (SDK) JavaScript côté client.

ASP.NET Core

Si votre application comporte des composants côté client, suivez les étapes suivantes pour commencer à collecter les données de télémétrie d’utilisation par l'injection de script de chargement du SDK JavaScript (Web) via la configuration.

1. Dans _ViewImports.cshtml, ajoutez l’injection :

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

2. Dans _Layout.cshtml, insérez HtmlHelper à la fin de la section <head>, mais avant tout autre script. Si vous souhaitez signaler les données de télémétrie JavaScript personnalisées à partir de la page, injectez-la par après cet extrait de code :

       @Html.Raw(JavaScriptSnippet.FullScript)
   </head>
   

En guise d’alternative à l’utilisation de FullScript, ScriptBody est disponible à partir du Kit de développement logiciel (SDK) Application Insights pour ASP.NET Core version 2.14. Utilisez ScriptBody si vous devez contrôler la balise <script> pour définir une stratégie de sécurité de contenu :

<script> // apply custom changes to this script tag.
    @Html.Raw(JavaScriptSnippet.ScriptBody)
</script>

Les noms de fichier .cshtml mentionnés précédemment proviennent d’un modèle d’application MVC par défaut. Enfin, si vous souhaitez activer correctement le monitoring côté client pour votre application, le Script de chargement du Kit de développement logiciel (SDK) (web) JavaScript doit apparaître dans la section <head> de chaque page de votre application que vous souhaitez monitorer. Ajoutez le Script de chargement du Kit de développement logiciel (SDK) (web) JavaScript à _Layout.cshtml dans un modèle d’application pour activer le monitoring côté client.

Si votre projet ne comporte pas _Layout.cshtml, vous pouvez toujours ajouter le monitoring côté client en ajoutant le Script de chargement du Kit de développement logiciel (SDK) (web) JavaScript à un fichier équivalent qui contrôle la section <head> de toutes les pages de votre application. Vous pouvez également ajouter le Script de chargement du SDK JavaScript (Web) à plusieurs pages, mais nous le déconseillons.

Note

L’injection JavaScript fournit une expérience de configuration par défaut. Si vous avez besoin de configuration au-delà de la définition de la chaîne de connexion, vous devez supprimer l'autoinjection, comme décrit, et d'ajouter manuellement le SDK JavaScript.

Node.js

Note

Disponible en préversion publique. Conditions d'utilisation supplémentaires pour les préversions de Microsoft Azure

L’instrumentation web automatique peut être activée pour le serveur de nœud via l’injection de script du Loader SDK JavaScript (web) par configuration.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

ou en définissant la variable d’environnement APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = true.

L’instrumentation web est activée sur des réponses du serveur de nœud une fois toutes les conditions suivantes remplies :

• La réponse a un code d’état 200.
• La méthode de réponse est GET.
• La réponse du serveur contient un fichier html Content-Type.
• La réponse de serveur contient à la fois les balises <head> et </head>.
• Si la réponse est compressée, elle ne doit avoir qu’un seul type Content-Encoding et le type d’encodage doit être un de gzip, br ou deflate.
• La réponse ne contient aucun point de terminaison CDN d’instrumentation web /backup actuels. (points de terminaison CDN d’instrumentation web actuels et de sauvegarde ici)

Le point de terminaison CDN Web Instrumentation peut être modifié en définissant la variable APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints"d’environnement. La chaîne de connexion de l'instrumentation web peut être modifiée en définissant la variable d’environnement APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

Note

L’instrumentation web peut ralentir le temps de réponse du serveur, en particulier si la taille de la réponse est élevée ou si la réponse est compressée. Dans le cas où certaines couches intermédiaires sont appliquées, il est possible que l’instrumentation web ne fonctionne pas et que la réponse d’origine soit retournée.

API principale pour les événements et métriques personnalisés

Insérez quelques lignes de code dans votre application pour savoir ce que les utilisateurs font avec lui ou pour aider à diagnostiquer les problèmes. Vous pouvez envoyer des données de télémétrie à partir d’applications d’appareil et de bureau, de clients web et de serveurs web. Utilisez l’API de télémétrie principale Application Insights pour envoyer des événements et des métriques personnalisés et vos propres versions de données de télémétrie standard. Cette API est la même API que celle utilisée par les collecteurs de données Application Insights standard.

Résumé de l’API

L’API principale est uniforme sur toutes les plateformes, à l’exception de quelques variantes telles que GetMetric (.NET uniquement).

Méthode	Utilisé pour
TrackPageView	Pages, écrans, volets ou formulaires.
TrackEvent	Actions utilisateur et autres événements. Permet de suivre le comportement de l’utilisateur ou d’analyser les performances.
GetMetric	Métriques zéro et multidimensionnelle, agrégation configurée de manière centralisée, C# uniquement.
TrackMetric	Mesures de performances telles que les longueurs de file d’attente non liées à des événements spécifiques.
TrackException	Journalisation des exceptions pour le diagnostic. Effectuez un suivi lorsqu’ils se produisent par rapport à d’autres événements et examinez les arborescences des appels de procédure.
TrackRequest	Journalisation de la fréquence et de la durée des demandes de serveur pour l’analyse des performances.
TrackTrace	Messages du journal de diagnostic des ressources. Vous pouvez également capturer des journaux tiers.
TrackDependency	Journalisation de la durée et de la fréquence des appels à des composants externes dont dépend votre application.

Vous pouvez attacher des propriétés et des métriques à la plupart de ces appels de télémétrie.

Conditions préalables

Si vous n’avez pas encore de référence sur le Kit de développement logiciel (SDK) Application Insights :

1. Ajoutez le Kit de développement logiciel (SDK) Application Insights à votre projet.

2. Dans le code de votre appareil ou serveur web, incluez :

   .NET

   using Microsoft.ApplicationInsights;
   

   Node.js

   var applicationInsights = require("applicationinsights");
   

Obtenir une instance TelemetryClient

Obtenir une instance de TelemetryClient:

Note

Si vous utilisez Azure Functions v2+ ou Azure WebJobs v3+, consultez Monitor Azure Functions.

.NET

Note

Pour les applications ASP.NET Core et les applications .NET/.NET Core non HTTP ou Worker, récupérez une instance de TelemetryClient à partir du conteneur d’injection de dépendances comme expliqué dans la documentation correspondante.

private TelemetryClient telemetry = new TelemetryClient();

Si vous voyez un message indiquant que cette méthode est obsolète, consultez microsoft/ApplicationInsights-dotnet#1152 pour plus d’informations.

Les requêtes HTTP entrantes sont automatiquement capturées. Vous pourriez vouloir créer davantage d'instances de TelemetryClient pour d'autres modules de votre application. Par exemple, vous pouvez avoir une TelemetryClient instance dans votre classe middleware pour signaler des événements de logique métier. Vous pouvez définir des propriétés telles que UserId et DeviceId identifier l’ordinateur. Ces informations sont attachées à tous les événements envoyés par l’instance.

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

Node.js

var telemetry = applicationInsights.defaultClient;

Vous pouvez utiliser new applicationInsights.TelemetryClient(instrumentationKey?) pour créer une instance. Nous recommandons cette approche uniquement pour les scénarios nécessitant une configuration isolée de l'instance unique (singleton) defaultClient.

Note

TelemetryClient est thread sécurisé.

TrackEvent

Dans Application Insights, un événement personnalisé est un point de données que vous pouvez afficher dans Metrics Explorer en tant que nombre agrégé et dans La recherche en tant qu’occurrences individuelles. (Il n’est pas lié à MVC ou à d’autres « événements ».

Insérez des TrackEvent appels dans votre code pour compter différents événements. Par exemple, vous souhaiterez peut-être suivre la fréquence à laquelle les utilisateurs choisissent une fonctionnalité particulière. Vous pouvez également savoir à quelle fréquence ils atteignent certains objectifs ou font des types d’erreurs spécifiques.

Par exemple, dans une application de jeu, envoyez un événement chaque fois qu’un utilisateur gagne le jeu :

.NET

telemetry.TrackEvent("WinGame");

Node.js

telemetry.trackEvent({name: "WinGame"});

Événements personnalisés dans Log Analytics

La télémétrie est disponible dans le tableau de l’onglet customEventsJournaux Application Insights ou dans l’expérience d’utilisation. Les événements peuvent provenir de trackEvent(..) ou du plug-in Click Analytics Autocollection.

Si l’échantillonnage est en cours d’opération, la itemCount propriété affiche une valeur supérieure à 1. Par exemple, cela signifie que parmi 10 appels à itemCount==10, le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct d’événements personnalisés, utilisez du code tel que customEvents | summarize sum(itemCount).

Note

itemCount a une valeur minimale d’une ; l’enregistrement lui-même représente une entrée.

GetMetric

Pour savoir comment utiliser efficacement l’appel GetMetric() pour collecter des métriques préagrégées localement pour les applications .NET et .NET Core, consultez Collection de métriques personnalisées dans .NET et .NET Core.

TrackMetric

Note

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric n’est pas la méthode recommandée pour l’envoi de métriques. Les métriques doivent toujours être préagrégées sur une période avant d’être envoyées. Utilisez l’une des surcharges GetMetric(..) pour obtenir un objet métrique permettant d’accéder aux capacités de pré-agrégation du Kit de développement logiciel (SDK).

Si vous implémentez votre propre logique de préaggregation, vous pouvez utiliser la TrackMetric() méthode pour envoyer les agrégats résultants. Si votre application nécessite l’envoi d’un élément de télémétrie distinct à chaque occasion sans agrégation au fil du temps, vous avez probablement un cas d’usage pour la télémétrie des événements. Voir TelemetryClient.TrackEvent(Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Application Insights peut graphiquer des métriques qui ne sont pas attachées à des événements particuliers. Par exemple, vous pouvez surveiller une longueur de file d’attente à intervalles réguliers. Avec les métriques, les mesures individuelles sont moins intéressantes que les variations et les tendances, et les graphiques statistiques sont donc utiles.

Pour envoyer des métriques à Application Insights, vous pouvez utiliser l’API TrackMetric(..) . Il existe deux façons d’envoyer une métrique :

• Valeur unique. Chaque fois que vous effectuez une mesure dans votre application, vous envoyez la valeur correspondante à Application Insights.

  Par exemple, supposons que vous disposez d’une métrique qui décrit le nombre d’éléments d’un conteneur. Pendant une période particulière, vous devez d’abord placer trois éléments dans le conteneur, puis supprimer deux éléments. En conséquence, vous devez appeler TrackMetric deux fois. Tout d’abord, vous devez passer la valeur 3 , puis passer la valeur -2. Application Insights stocke les deux valeurs pour vous.

• Agrégation. Lorsque vous travaillez avec des métriques, chaque mesure unique est rarement intéressante. Au lieu de cela, un résumé de ce qui s’est passé pendant une période particulière est important. Un tel résumé est appelé agrégation.

  Dans l’exemple précédent, la somme de métriques d’agrégation pour cette période est 1 et le nombre de valeurs de métrique est 2. Lorsque vous utilisez l’approche d’agrégation, vous n’appelez TrackMetric qu’une seule fois par période et envoyez les valeurs d’agrégation. Nous vous recommandons cette approche, car elle peut réduire considérablement le coût et la surcharge des performances en envoyant moins de points de données à Application Insights, tout en collectant toutes les informations pertinentes.

Exemples de valeurs uniques

Pour envoyer une valeur de métrique unique :

.NET

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

Node.js

telemetry.trackMetric({name: "queueLength", value: 42.0});

Métriques personnalisées dans Log Analytics

Les données de télémétrie sont disponibles dans la customMetrics table dans Application Insights Analytics. Chaque ligne représente un appel à trackMetric(..) dans votre application.

• valueSum: somme des mesures. Pour obtenir la valeur moyenne, divisez par valueCount.
• valueCount: nombre de mesures qui ont été agrégées dans cet trackMetric(..) appel.

Note

valueCount a une valeur minimale d’une ; l’enregistrement lui-même représente une entrée.

Affichages de page

Dans une application d’appareil ou de page web, les données de télémétrie d’affichage de page sont envoyées par défaut lorsque chaque écran ou page est chargé. Toutefois, vous pouvez modifier la valeur par défaut pour suivre les affichages de page à plusieurs ou différents moments. Par exemple, dans une application qui affiche des onglets ou des volets, vous pouvez suivre une page chaque fois que l’utilisateur ouvre un nouveau volet.

Les données d’utilisateur et de session sont envoyées en tant que propriétés avec les affichages de page, de façon à ce que les graphiques d’utilisateur et de session soient actifs s’il existe une télémétrie de l’affichage de page.

Affichages de pages personnalisés

.NET

telemetry.TrackPageView("GameReviewPage");

Node.js

Non applicable.

Télémétrie de page dans Log Analytics

Dans Log Analytics, deux tables affichent les données des opérations de navigateur :

• pageViews: contient des données sur l’URL et le titre de la page.
• browserTimings: contient des données sur les performances du client, comme le temps nécessaire pour traiter les données entrantes.

Pour savoir combien de temps le navigateur prend pour traiter différentes pages :

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

Pour découvrir la popularité des différents navigateurs :

pageViews
| summarize count() by client_Browser

Pour associer des vues de pages à des appels AJAX, joindre à des dépendances :

pageViews
| join (dependencies) on operation_Id

TrackRequest

Le Kit de développement logiciel (SDK) serveur utilise TrackRequest pour journaliser les requêtes HTTP.

Vous pouvez également l’appeler vous-même si vous souhaitez simuler des requêtes dans un contexte où vous n’avez pas le module de service web en cours d’exécution.

La méthode recommandée pour envoyer des données de télémétrie de requête est l’endroit où la requête agit en tant que contexte d’opération.

Contexte d’opération

Vous pouvez mettre en corrélation des éléments de télémétrie ensemble en les associant au contexte d’opération. Le module de suivi des requêtes standard le fait pour les exceptions et d’autres événements envoyés pendant qu’une requête HTTP est en cours de traitement. Dans La recherche et l’analytique, vous pouvez facilement trouver tous les événements associés à la requête à l’aide de son ID d’opération.

Lorsque vous effectuez le suivi manuel des données de télémétrie, le moyen le plus simple de garantir la corrélation des données de télémétrie consiste à utiliser ce modèle :

.NET

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here uses the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

Pour plus d’informations sur la corrélation, consultez la corrélation de télémétrie dans Application Insights.

Node.js

// Establish an operation context and associated telemetry item:
const operation = appInsights.startOperation(client, { name: "operationName" });

appInsights.wrapWithCorrelationContext(() => {
    // Telemetry sent in here uses the same operation ID.
    ...
    client.trackTrace({ message: "..." }); // or other track* calls
    ...

    // Set properties of containing telemetry item—for example:
    operation.telemetry.responseCode = "200";

    // Optional: explicitly send telemetry item:
    client.stopOperation(operation);

}, operation.context)(); // When callback completes, telemetry item is sent.

En plus de définir un contexte d’opération, StartOperation crée un élément de télémétrie du type que vous spécifiez. Il envoie l’élément de télémétrie lorsque vous supprimez l’opération ou si vous appelez StopOperation explicitement. Si vous utilisez RequestTelemetry comme type de télémétrie, sa durée est définie sur l’intervalle chronométré entre le début et l’arrêt.

Les éléments de télémétrie signalés dans une étendue de l’opération deviennent « enfants » d’une telle opération. Les contextes d’opération peuvent être imbriqués.

Dans La recherche, le contexte d’opération est utilisé pour créer la liste Éléments associés .

Pour plus d’informations sur le suivi des opérations personnalisées, consultez Track custom operations with Application Insights .NET SDK.

Demandes dans Log Analytics

Dans Application Insights Analytics, les requêtes s’affichent dans la requests table.

Si l’échantillonnage est en cours d’opération, la itemCount propriété affiche une valeur supérieure à 1. Par exemple, cela signifie que parmi 10 appels à itemCount==10, le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct de requêtes et la durée moyenne segmentées par noms de requête, utilisez du code tel que :

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

Envoyer des exceptions à Application Insights :

• Pour les compter, comme indication de la fréquence d’un problème.
• Pour examiner les occurrences individuelles.

Les rapports incluent les traces de pile.

.NET

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

Node.js

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

Les kits SDK interceptent automatiquement de nombreuses exceptions. Vous n’avez donc pas toujours besoin d’appeler TrackException explicitement.

Exceptions dans Log Analytics

Dans Application Insights Analytics, les exceptions s’affichent dans la exceptions table.

Si l’échantillonnage est en cours d’opération, la itemCount propriété affiche une valeur supérieure à 1. Par exemple, cela signifie que parmi 10 appels à itemCount==10, le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct d’exceptions segmentées par type d’exception, utilisez du code tel que :

exceptions
| summarize sum(itemCount) by type

La plupart des informations importantes sur la pile sont déjà extraites dans des variables distinctes, mais vous pouvez extraire séparément la structure details pour en savoir plus. Étant donné que cette structure est dynamique, vous devez convertir le résultat en type attendu. Par exemple:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

Pour associer des exceptions à leurs demandes associées, utilisez une jointure :

exceptions
| join (requests) on operation_Id

TrackTrace

Utilisez TrackTrace pour diagnostiquer des problèmes en envoyant une « piste de navigation » à Application Insights. Vous pouvez envoyer des blocs de données de diagnostic et les inspecter dans La recherche.

.NET

Dans .NET, les Adaptateurs de journaux utilisent cette API pour envoyer des journaux tiers au portail.

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

Node.js

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

Journaliser un événement de diagnostic, tel que l’entrée ou la sortie d’une méthode.

Paramètre	Descriptif
message	Données de diagnostic. Peut être beaucoup plus long qu’un nom.
properties	Mappage de chaîne à chaîne. D’autres données sont utilisées pour filtrer les exceptions dans le portail. La valeur par défaut est vide.
severityLevel	Valeurs prises en charge : SeverityLevel.ts.

Vous pouvez rechercher dans le contenu du message, mais contrairement aux valeurs de propriété, vous ne pouvez pas filtrer dessus.

La limite de taille sur message est beaucoup plus élevée que la limite sur les propriétés. Un avantage de TrackTrace est que vous pouvez intégrer des données relativement longues dans le message. Par exemple, vous pouvez encoder les données POST là-bas.

Vous pouvez également ajouter un niveau de gravité à votre message. Et, comme d’autres données de télémétrie, vous pouvez ajouter des valeurs de propriété pour vous aider à filtrer ou à rechercher différents ensembles de traces. Par exemple:

.NET

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

Node.js

Non applicable.

Dans la recherche, vous pouvez ensuite filtrer facilement tous les messages d’un niveau de gravité particulier lié à une base de données particulière.

Traces dans Log Analytics

Dans Application Insights Analytics, les appels vers TrackTrace s’affichent dans la traces table.

Si l’échantillonnage est en cours d’opération, la itemCount propriété affiche une valeur supérieure à 1. Par exemple, cela signifie que parmi 10 appels à itemCount==10, le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct d’appels de trace, utilisez du code tel que traces | summarize sum(itemCount).

TrackDependency

Utilisez l’appel TrackDependency pour suivre les temps de réponse et les taux de réussite des appels à un élément de code externe. Les résultats apparaissent dans les graphiques de dépendances dans le portail. L’extrait de code suivant doit être ajouté partout où un appel de dépendance est effectué.

Note

Pour .NET et .NET Core, vous pouvez également utiliser la méthode TelemetryClient.StartOperation (extension) qui remplit les propriétés DependencyTelemetry nécessaires pour la corrélation et certaines autres propriétés comme l'heure de début et la durée. Vous n'avez donc pas besoin de créer un minuteur personnalisé comme avec les exemples suivants. Pour plus d’informations, reportez-vous à la section sur le suivi des dépendances sortantes dans Track custom operations with Application Insights .NET SDK.

.NET

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

Node.js

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

N’oubliez pas que les kits SDK de serveur incluent un module de dépendance qui découvre et suit automatiquement certains appels de dépendance, par exemple aux bases de données et aux API REST. Vous devez installer un agent sur votre serveur pour que le module fonctionne.

Vous utilisez cet appel si vous souhaitez suivre les appels que le suivi automatisé n’intercepte pas.

Pour désactiver le module de suivi des dépendances standard en C#, modifiez ApplicationInsights.config et supprimez la référence à DependencyCollector.DependencyTrackingTelemetryModule.

Dépendances dans Log Analytics

Dans Application Insights Analytics, trackDependency les appels s’affichent dans la dependencies table.

Si l’échantillonnage est en cours d’opération, la itemCount propriété affiche une valeur supérieure à 1. Par exemple, cela signifie que parmi 10 appels à itemCount==10, le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct de dépendances segmentées par composant cible, utilisez du code tel que :

dependencies
| summarize sum(itemCount) by target

Pour associer des dépendances à leurs demandes associées, utilisez une jointure :

dependencies
| join (requests) on operation_Id

Vidage des données

Normalement, le SDK envoie des données à intervalles fixes, généralement 30 secondes, ou chaque fois que la mémoire tampon est pleine, ce qui représente généralement 500 éléments. Dans certains cas, vous souhaiterez peut-être vider la mémoire tampon. Par exemple, si vous utilisez le Kit de développement logiciel (SDK) dans une application qui s’arrête.

.NET

Lorsque vous utilisez Flush(), nous vous recommandons ce modèle :

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

Lorsque vous utilisez FlushAsync(), nous vous recommandons ce modèle :

await telemetryClient.FlushAsync()
// No need to sleep

Nous vous recommandons de toujours effectuer une vidange lors de l'arrêt de l'application pour garantir que la télémétrie n'est pas perdue.

Note

Review Autoflush configuration : L'activation de l'autoflush dans votre fichier web.config peut entraîner une dégradation des performances dans les applications .NET instrumentées avec Application Insights. Lorsque la configuration autoflush est activée, chaque appel de méthode System.Diagnostics.Trace.Trace* entraîne l’envoi d’éléments de télémétrie individuels sous forme de requêtes web distinctes au service d’ingestion. Cela peut entraîner l’épuisement du réseau et du stockage sur vos serveurs web. Pour améliorer les performances, il est recommandé de désactiver l’autoflush et également, d’utiliser ServerTelemetryChannel, conçu pour une transmission de données de télémétrie plus efficace.

La fonction est asynchrone pour le canal de télémétrie du serveur.

Node.js

telemetry.flush();

Utilisateurs authentifiés

Dans une application web, les utilisateurs sont identifiés par les cookies par défaut. Un utilisateur peut être compté plusieurs fois s’il accède à votre application à partir d’un autre ordinateur ou d’un navigateur, ou s’il supprime des cookies.

Si les utilisateurs se connectent à votre application, vous pouvez obtenir un nombre plus précis en définissant l’ID d’utilisateur authentifié dans le code du navigateur. Il n’est pas nécessaire d’utiliser le nom de connexion réel de l’utilisateur. Il doit uniquement s’agir d’un ID unique à cet utilisateur. Il ne doit pas inclure d’espaces ou d’un des caractères ,;=|.

L’ID utilisateur est également défini dans un cookie de session et envoyé au serveur. Si le Kit de développement logiciel (SDK) du serveur est installé, l’ID d’utilisateur authentifié est envoyé dans le cadre des propriétés de contexte des données de télémétrie client et serveur. Vous pouvez ensuite filtrer et rechercher dessus.

Si votre application regroupe des utilisateurs dans des comptes, vous pouvez également transmettre un identificateur pour le compte. Les mêmes restrictions de caractères s’appliquent.

Dans Metrics Explorer, vous pouvez créer un graphique qui compte utilisateurs, authentifiés et comptes d’utilisateur.

Vous pouvez également rechercher des points de données client avec des noms d’utilisateur et des comptes spécifiques.

Note

La propriété EnableAuthenticationTrackingJavaScript dans la classe ApplicationInsightsServiceOptions dans le Kit de développement logiciel (SDK) .NET Core simplifie la configuration JavaScript nécessaire pour injecter le nom d’utilisateur en tant qu’ID d’authentification pour chaque trace envoyée par le Kit de développement logiciel (SDK) JavaScript Application Insights.

Lorsque cette propriété est définie sur true, le nom d’utilisateur de l’utilisateur dans l’ASP.NET Core est imprimé avec télémétrie côté client. Pour cette raison, l'ajout de appInsights.setAuthenticatedUserContext manuellement n'est plus nécessaire, car il est déjà injecté par le Kit de développement logiciel (SDK) pour ASP.NET Core. L’ID d’authentification est également envoyé au serveur où le Kit de développement logiciel (SDK) de .NET Core l’identifie et l’utilise pour toutes les données de télémétrie côté serveur, comme décrit dans la référence JavaScript API.

Pour les applications JavaScript qui ne fonctionnent pas de la même façon que ASP.NET Core MVC, telles que les applications web SPA, vous devez quand même ajouter appInsights.setAuthenticatedUserContext manuellement.

Filtrer, rechercher et segmenter vos données à l’aide de propriétés

Vous pouvez attacher des propriétés et des mesures à vos événements, métriques, vues de page, exceptions et autres données de télémétrie.

Les propriétés sont des valeurs de chaîne que vous pouvez utiliser pour filtrer vos données de télémétrie dans les rapports d’utilisation. Par exemple, si votre application fournit plusieurs jeux, vous pouvez attacher le nom du jeu à chaque événement afin de voir quels jeux sont plus populaires.

Il existe une limite de 8 192 sur la longueur de chaîne. Si vous souhaitez envoyer des blocs de données volumineux, utilisez le paramètre de message de TrackTrace.

Les métriques sont des valeurs numériques qui peuvent être présentées graphiquement. Par exemple, vous souhaiterez peut-être voir s’il existe une augmentation progressive des scores obtenus par vos joueurs. Les graphiques peuvent être segmentés par les propriétés envoyées avec l’événement afin que vous puissiez obtenir des graphiques distincts ou empilés pour différents jeux.

Les valeurs de métrique doivent être supérieures ou égales à 0 pour s’afficher correctement.

Il existe certaines limites sur le nombre de propriétés, de valeurs de propriété et de métriques que vous pouvez utiliser.

.NET

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

Node.js

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Important

Veillez à ne pas enregistrer les informations d’identification personnelle dans les propriétés.

Alternative pour définir des propriétés et des métriques

S’il est plus pratique, vous pouvez collecter les paramètres d’un événement dans un objet distinct :

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

Avertissement

Ne réutilisez pas la même instance d’élément de télémétrie (event dans cet exemple) pour appeler Track*() plusieurs fois. Cette pratique peut entraîner l’envoi de données de télémétrie avec une configuration incorrecte.

Mesures et propriétés personnalisées dans Log Analytics

Dans Log Analytics, les métriques et propriétés personnalisées s’affichent dans les attributs customMeasurements et customDimensions de chaque enregistrement de télémétrie.

Par exemple, si vous ajoutez une propriété nommée « game » à votre télémétrie de requête, cette requête compte les occurrences de différentes valeurs de « jeu » et affiche la moyenne de la métrique personnalisée « score » :

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

Notez que :

• Lorsque vous extrayez une valeur à partir du JSON via customDimensions ou customMeasurements, elle a un type dynamique, vous devez donc la caster avec tostring ou todouble.
• Pour tenir compte de la possibilité d’échantillonnage, n’utilisez sum(itemCount) pas count().

Événements de chronométrage

Parfois, vous souhaitez graphiquer le temps nécessaire à l’exécution d’une action. Par exemple, vous souhaiterez peut-être savoir combien de temps les utilisateurs prennent pour prendre en compte les choix dans un jeu. Pour obtenir ces informations, utilisez le paramètre de mesure.

.NET

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

Node.js

Propriétés par défaut pour la télémétrie personnalisée

Si vous souhaitez définir des valeurs de propriété par défaut pour certains des événements personnalisés que vous écrivez, définissez-les dans une TelemetryClient instance. Ils sont attachés à chaque élément de télémétrie envoyé par ce client.

.NET

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry is automatically sent with the context property:
gameTelemetry.TrackEvent("WinGame");

Node.js

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

Les appels de télémétrie individuels peuvent remplacer les valeurs par défaut dans leurs dictionnaires de propriétés.

Pour ajouter des propriétés à toutes les données de télémétrie, y compris les données des modules de collecte standard, implémentez ITelemetryInitializer.

Désactiver la télémétrie

Pour arrêter et démarrer dynamiquement la collecte et la transmission des données de télémétrie :

.NET

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Node.js

telemetry.config.disableAppInsights = true;

Pour désactiver les collecteurs standard sélectionnés, comme les compteurs de performances, les requêtes HTTP ou les dépendances, au moment de l’initialisation, enchaînez les méthodes de configuration à votre code d’initialisation du SDK.

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

Pour désactiver ces collecteurs après l’initialisation, utilisez l’objet Configuration : applicationInsights.Configuration.setAutoCollectRequests(false).

Mode développeur

Pendant le débogage, il est utile d'avoir votre télémétrie envoyée par le pipeline afin que vous puissiez voir immédiatement les résultats. Vous obtenez également d’autres messages qui vous aident à suivre les problèmes de télémétrie. Désactivez-le en production, car il peut ralentir votre application.

.NET

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Node.js

Pour Node.js, vous pouvez activer le mode développeur en activant la journalisation interne via setInternalLogging et en définissant maxBatchSize à 0, ce qui permet à vos données de télémétrie d'être envoyées dès qu'elles sont collectées.

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

Définir la clé d’instrumentation pour les données de télémétrie personnalisées sélectionnées

.NET

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

Node.js

Chaîne de connexion dynamique

Pour éviter de mélanger les données de télémétrie des environnements de développement, de test et de production, vous pouvez créer des ressources Application Insights distinctes et modifier leurs clés, en fonction de l’environnement.

Au lieu d’obtenir la clé d’instrumentation à partir du fichier de configuration, vous pouvez la définir dans votre code. Définissez la clé dans une méthode d’initialisation, telle que global.aspx.cs dans un service ASP.NET :

.NET

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

Node.js

Non applicable.

TelemetryContext

TelemetryClient a une propriété Context, qui contient des valeurs qui sont envoyées avec toutes les données de télémétrie. Ils sont normalement définis par les modules de télémétrie standard, mais vous pouvez également les définir vous-même. Par exemple:

telemetry.Context.Operation.Name = "MyOperationName";

Si vous définissez vous-même l’une de ces valeurs, envisagez de supprimer la ligne pertinente de ApplicationInsights.config afin que vos valeurs et les valeurs standard ne soient pas confondues.

• Composant : l’application et sa version.
• Appareil : données sur l’appareil sur lequel l’application est en cours d’exécution. Dans les applications web, il s’agit du serveur ou de l’appareil client à partir duquel les données de télémétrie sont envoyées.
• InstrumentationKey : ressource Application Insights dans Azure où la télémétrie s’affiche. Il est généralement récupéré à partir de ApplicationInsights.config.
• Emplacement : emplacement géographique de l’appareil.
• Opération : dans les applications web, la requête HTTP actuelle. Dans d’autres types d’applications, vous pouvez définir cette valeur pour regrouper les événements.
  • ID : valeur générée qui met en corrélation différents événements de sorte que lorsque vous inspectez un événement dans la Recherche de diagnostic, vous pouvez trouver des éléments connexes.
  • Nom : identificateur, généralement l’URL de la requête HTTP.
  • SyntheticSource : s’il n’est pas null ou vide, chaîne qui indique que la source de la requête a été identifiée comme un robot ou un test web. Par défaut, il est exclu des calculs dans Metrics Explorer.
• Session : session de l’utilisateur. L’ID est défini sur une valeur générée, qui est modifiée lorsque l’utilisateur n’a pas été actif pendant un certain temps.
• Utilisateur : informations utilisateur.

Limites

Il existe certaines limites sur le nombre de métriques et d’événements par application, c’est-à-dire par connection string. Les limites varient selon le plan de tarification que vous choisissez.

Resource	Limite par défaut	Limite maximale	Remarques
Total des données par jour	100 Go	Contactez le support technique.	Vous pouvez définir une limite pour réduire les données. Si vous avez besoin de davantage de données, vous pouvez augmenter la limite dans le portail, jusqu’à 1 000 Go. Pour une capacité supérieure à 1 000 Go, envoyez un e-mail à AIDataCap@microsoft.com.
Throttling	32 000 événements/seconde	Contactez le support technique.	La limite est mesurée par minute.
Journaux de conservation des données	30 à 730 jours	730 jours	Cette ressource est destiné aux journaux.
Métriques de conservation des données	90 jours	90 jours	Cette ressource est destinée à Metrics Explorer.
Conservation des résultats détaillés du test de disponibilité à plusieurs étapes	90 jours	90 jours	Cette ressource fournit des résultats détaillés de chaque étape.
Taille maximale des éléments de télémétrie	64 Ko	64 Ko
Nombre maximal d’éléments de télémétrie par lot	64 000	64 000
Longueur des noms de propriétés et de mesures	150	150	Consultez les schémas par type.
Longueur de chaîne de valeur de propriété	8,192	8,192	Consultez les schémas par type.
Longueur des messages de trace et d’exception	32,768	32,768	Consultez les schémas par type.
Nombre de tests de disponibilité par ressource Application Insights	100	100
Nombre de tests de disponibilité par groupe de ressources	800	800	Consultez Azure Resource Manager
Tests de disponibilité nombre maximal de redirections par test	10	10
Tests de disponibilité fréquence minimale des tests	300 secondes		Les fréquences de test personnalisées ou les fréquences inférieures à 5 minutes nécessitent implémentations personnalisées de TrackAvailability .
.NET Profiler et conservation des données du Snapshot Debugger	Deux semaines	Contactez le support technique. La limite maximale de conservation est de six mois.
.NET Profiler données envoyées par jour	Aucune limite	Aucune limite.
Données du Débogueur de capture instantanée envoyées par jour	30 instantanés par jour par application monitorée	Aucune limite.	Le nombre d’instantanés collectés par application peut être modifié dans la configuration.

Pour plus d’informations sur la tarification et les quotas, consultez Facturation d’Application Insights.

Pour éviter d’atteindre la limite de débit de données, utilisez l’échantillonnage.

Pour déterminer la durée de conservation des données, consultez la conservation et la confidentialité des données.

Exemples d’applications

.NET Application console Core : utilisez cet exemple si vous utilisez une application console écrite dans .NET Core (2.0 ou version ultérieure) ou .NET Framework (4.7.2 ou version ultérieure).

ASP.NET Core tâches en arrière-plan avec HostedServices : utilisez cet exemple si vous êtes dans ASP.NET Core et que vous créez des tâches en arrière-plan conformément aux instructions officiales.

Service Worker .NET Core : Utilisez cet exemple si vous disposez d’une application Service Worker .NET conformément aux instructions officielles.

Résolution des problèmes

Consultez les articles de résolution des problèmes dédiés pour .NET et Node.js.

Tester la connectivité entre votre hôte d’application et le service d’ingestion

Les SDK et les agents d'Application Insights envoient de la télémétrie pour être incorporée sous forme d'appels REST à nos points de terminaison d'ingestion. Vous pouvez tester la connectivité de votre serveur web ou de votre machine hôte d’application vers les points de terminaison de service d’ingestion en utilisant des clients du Representational State Transfer (REST) bruts à partir de commandes PowerShell ou curl. Consultez Comment dépanner la télémétrie d'application absente dans Azure Monitor Application Insights.

Kit de développement logiciel (SDK) open source

Lisez et contribuez au code de .NET et Node.js.

Notes de publication

• Notes de publication d’Application Insights
• Versions du SDK .NET sur GitHub
• Versions du SDK Node.js sur GitHub

Les mises à jour de service résument également les principales améliorations d’Application Insights.

Étapes suivantes

• Vérifiez que vous exécutez une version prise en charge du Kit de développement logiciel (SDK) Application Insights.
• Pour connaître les types et les modèles de données Application Insights, consultez Modèle de données.
• Consultez le Guide de l’utilisateur System.Diagnostics.Activity pour voir comment mettre en corrélation les données de télémétrie.
• Pour consulter les questions fréquentes (FAQ), consultez :
  • FAQ ASP.NET
  • FAQ ASP.NET Core
  • Worker Service FAQ
  • FAQNode.js
  • API pour les événements et les métriques personnalisés FAQ