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

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.

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.

Prerequisites

Créer une application web de base

Si vous n’avez pas encore d’application web fonctionnelle, vous pouvez utiliser les instructions suivantes pour en créer une.

ASP.NET

1. Ouvrez Visual Studio.
2. Sélectionnez Créer un projet.
3. Choisissez ASP.NET application web (.NET Framework) avec C# et sélectionnez Suivant.
4. Entrez un nom de projet, puis sélectionnez Créer.
5. Choisissez MVC, puis sélectionnez Créer.

ASP.NET Core

1. Ouvrez Visual Studio.
2. Sélectionnez Créer un projet.
3. Choisissez ASP.NET Core Web App (Pages Razor) avec C# et sélectionnez Suivant.
4. Entrez un nom de projet, puis sélectionnez Créer.
5. Choisissez une infrastructure (LTS ou STS), puis sélectionnez Créer.

Ajouter Application Insights automatiquement (Visual Studio)

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

ASP.NET

À partir de votre projet d’application web ASP.NET dans Visual Studio :

1. Sélectionnez Projet>Ajouter Application Insights Telemetry>SDK Application Insights (local)>Suivant>Terminer>Fermer.

2. Ouvrez le fichier ApplicationInsights.config.

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

   <ConnectionString>Copy connection string from Application Insights Resource Overview</ConnectionString>
   

4. Sélectionnez Projet>Gérer les packages NuGet>Mises à jour. Ensuite, mettez à jour chaque package NuGet Microsoft.ApplicationInsights vers la dernière version stable.

5. Exécutez votre application en sélectionnant IIS Express. Une application ASP.NET basique s’ouvre. Lorsque vous parcourez les pages du site, la télémétrie est envoyée vers Application Insights.

ASP.NET Core

À partir de votre projet d’application web ASP.NET dans Visual Studio :

1. Accédez à Projet>Ajouter Application Insights Telemetry.

2. Sélectionnez Azure Application Insights>Suivant.

3. Choisissez votre abonnement et votre instance Application Insights. Vous pouvez également créer une instance avec l’option Créer nouveau. Cliquez sur Suivant.

4. Ajoutez ou confirmez votre chaîne de connexion Application Insights. Celle-ci doit être préremplie en fonction de votre sélection à l’étape précédente. Sélectionnez Terminer.

5. Après avoir ajouté Application Insights à votre projet, vérifiez que vous utilisez la dernière version stable du SDK. Accédez à Projet>Gérer les packages NuGet>Microsoft.ApplicationInsights.AspNetCore. Au besoin, sélectionnez Mettre à jour.

   

Ajouter Application Insights manuellement (hors Visual Studio)

Cette section vous guide tout au long de l’ajout manuel 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 chaîne de connexion, que vous pouvez effectuer de deux manières :

   • (Recommandé) Définissez la chaîne de connexion dans la configuration.

     Avant la balise </ApplicationInsights> de clôture dans ApplicationInsights.config, ajoutez la chaîne de connexion pour votre ressource Application Insights. Vous pouvez rechercher votre chaîne de connexion dans le volet vue d’ensemble de la ressource d’Application Insights nouvellement créée.

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

   • Définissez la chaîne de connexion dans le code.

     Fournissez une chaîne de connexion 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 pour le SDK sur le référentiel 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 chaîne de connexion, que vous pouvez effectuer de trois manières :

   • (Recommandé) Définissez la chaîne de connexion dans la configuration.

     Définissez la chaîne de connexion dans appsettings.json et veillez à ce que le fichier config soit 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 chaîne de connexion dans la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING ou ApplicationInsights:ConnectionString dans le fichier config 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>
     • En règle générale, vous utilisez APPLICATIONINSIGHTS_CONNECTION_STRING dans Web Apps. Vous pouvez également l’utiliser partout où ce SDK est pris en charge.

     Note

     Une chaîne de connexion spécifiée dans le code prévaut sur la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING, qui prévaut sur les autres options.

   • Définissez la chaîne de connexion dans le code.

     Fournissez une chaîne de connexion dans le cadre de l’argument ApplicationInsightsServiceOptions à 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 d’utilisateur d’ASP.NET Core ou la récupérer auprès d’un autre fournisseur de configuration, vous pouvez utiliser la surcharge 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 ultérieure, l’appel à services.AddApplicationInsightsTelemetry() permet de lire automatiquement la chaîne de connexion à partir de Microsoft.Extensions.Configuration.IConfiguration dans 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 d'arrière-plan .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 la chaîne de connexion 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 de processus de fond .NET Core

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

1. Téléchargez et installez le Kit de développement logiciel (SDK) .NET.

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

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 la chaîne de connexion.

   

   Note

   Nous vous recommandons de spécifier la chaîne de connexion dans la configuration. L’exemple de code suivant montre comment spécifier une chaîne de connexion 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 chaîne de connexion dans la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING .

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

ASP.NET Core tâches d'arrière-plan 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 la chaîne de connexion. Utilisez le même appsettings.json de l’exemple précédant Worker Service .NET.

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, afin qu’il puisse être utilisé pour les applications console dans .NET Core ou version ultérieure, et .NET Framework ou version ultérieure.

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.

Prerequisites

Configurer la bibliothèque de client Node.js

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

1. Copiez la chaîne de connexion de votre ressource à partir de votre nouvelle ressource. Application Insights utilise la chaîne de connexion pour mapper des données à votre ressource Azure. Pour que le kit de développement logiciel (SDK) puisse utiliser votre chaîne de connexion, vous devez la spécifier 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 une chaîne de connexion via la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING au lieu de la passer 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();.

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();

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.

ASP.NET et 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.

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, sur le Portail Azure, accédez à la ressource Application Insights que vous avez créée. 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.

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

Indicateurs en 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 s’afficher dans le Portail Azure, mais le volet des métriques en direct affiche l’utilisation du processeur pour les 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 en direct par le biais 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 s’utilise pour les applications console, mais le même code peut être utilisé dans toute application .NET.

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"
    }
  }
}

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 ASP.NET applications principales à 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.

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 les traces System.Diagnostics, configurez un TraceListener Application Insights dans la configuration de l'application.

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>

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, il existe une option permettant d’inclure le collecteur de journaux.

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

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 l’Explorateur de solutions, cliquez avec le bouton droit sur votre projet, puis sélectionnez Gérer les 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 :

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();

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" };
    }
}

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

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

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

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

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.

Explorer dans les journaux de logs Azure Monitor

Les journaux ILogger apparaissent sous forme de télémétrie de 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 : la vue diagnostics des transactions pour une transaction/requête unique et la vue carte d’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 SDK Application Insights pour .NET, .NET Core, Java, Node.js et JavaScript prennent tous en charge le suivi distribué nativement.

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 chaîne de connexion 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 Interroger des données sur des espaces de travail, des applications et des ressources Log Analytics dans Azure Monitor.

Example

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.

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 :

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 SDK .NET Framework/.NET Core récents, avec une compatibilité rétroactive avec le protocole hérité Request-Id.

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.

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

Le Kit de développement logiciel (SDK) .NET Application Insights utilise DiagnosticSource et Activity collecte et met en corrélation les données de télémétrie.

Dépendances

Dépendances suivies automatiquement

Les kits de développement logiciel (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 :

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.

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

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

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

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.

ASP.NET

Pour les applications ASP.NET, la requête SQL complète est collectée à l’aide de l’instrumentation de code byte, qui requiert le moteur d’instrumentation, ou à l’aide du package NuGet Microsoft.Data.SqlClient 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.

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 maintenant nécessaire d’accepter la collecte de texte SQL 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 application web Azure.
• Ajoutez l'extension de surveillance des applications pour les machines virtuelles Azure et les ensembles de machines virtuelles Azure hébergées par IIS.
• Ajoutez le kit de développement logiciel (SDK) Application Insights à votre code d’application, exécutez Application Insights Agent 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

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 de recherche 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.

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.
• Capturer automatiquement des exceptions en configurant votre infrastructure 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

Avec l'injection de dépendances (DI) dans .NET, le kit de développement logiciel (SDK) .NET approprié et la configuration correcte d’Application Insights pour l’injection de dépendance, vous pouvez exiger le TelemetryClient comme 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.

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);
        }
    }
}

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

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

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

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.

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);
    }
    }
}

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());
        }
    }
}

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);
        }
    }
}

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());
        }
    }
}

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 .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.

Le .NET Framework calcule le taux en comptant le nombre d’exceptions sur un intervalle et en divisant ce nombre par 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 SDK .NET et .NET Core Application Insights Azure Monitor ont deux méthodes différentes de collecte de métriques personnalisée :

• 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.

Bien démarrer avec GetMetric

Pour nos exemples, nous allons utiliser une application de service Worker .NET Core 3.1 de base. Si vous souhaitez répliquer l’environnement de test utilisé avec ces exemples, suivez les étapes 1 à 6 sous l’application du service Worker .NET Core. 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);
            }
        }
    }
}

Lors de l’exécution de l’exemple de code, vous voyez la boucle while s'exécuter de manière répétée sans qu'aucune télémétrie ne soit 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.

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.

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 télémétriques 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.

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.

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 SDK .NET d’Application Insights, l’opération est décrite par la classe abstraite OperationTelemetry et par ses descendants RequestTelemetry et DependencyTelemetry.

Suivi des opérations entrantes

Le kit SDK web d’Application Insights collecte automatiquement des 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.

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 la file d’attente de stockage Azure, nécessitent que le contexte soit encodé dans la charge utile du message.

File d’attente Service Bus

Pour les informations de suivi, reportez-vous à Suivi distribué et corrélation via la messagerie Service Bus.

File d’attente de stockage Azure

L’exemple suivant montre comment effectuer le suivi des opérations de file d’attente de stockage Azure et mettre en corrélation la télémétrie entre le producteur, le consommateur et le stockage Azure.

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 obtention d’un client de demande de stockage et un ID de demande de serveur, consultez Surveiller, diagnostiquer et dépanner Stockage Azure.

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 Stockage Azure
• Azure Event Hubs pour les concentrateurs d’événements Azure
• 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 type de 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.

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é.

Counters

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 les applications .NET.

Compteurs de performance

Windows offre divers compteurs de performances, tels que ceux utilisés pour rassembler les statistiques d’utilisation du processeur, de la mémoire et du disque. 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 qu’Azure Web Apps ne peuvent pas accéder directement aux compteurs de performances, mais Application Insights collecte un sous-ensemble de compteurs disponibles.

Prerequisites

Accordez l’autorisation du compte de service du pool d’applications pour analyser les compteurs de performances en l’ajoutant au groupe Utilisateurs analyseur de performances.

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

Les compteurs par défaut pour les applications web ASP.NET sont les suivants :

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

ASP.NET Core

Les compteurs par défaut pour les applications web ASP.NET Core sont les suivants :

• % 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

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();

Collecte des compteurs de performance en code pour les applications web ASP.NET ou les applications de 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 qui s’exécutent dans les conteneurs Azure Web Apps et Windows sur Azure App Service

Les applications ASP.NET et ASP.NET Core déployées sur les applications web d’Azure 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 de 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. Pour obtenir la liste complète, consultez Compteurs de performances exposés en tant que variables d’environnement.

Le kit de développement logiciel (SDK) Application Insights pour ASP.NET et ASP.NET Core détecte si le code est déployé sur une application web et un conteneur non-Windows. La détection détermine si les compteurs de performances sont collectés dans un environnement de bac à sable ou si vous utilisez le mécanisme de collecte standard lorsqu’ils sont hébergés sur un conteneur Windows ou une machine virtuelle.

Requêtes Log Analytics pour les compteurs de performance

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 le mécanisme .NET/.NET Core permettant de publier et consommer des compteurs ou des statistiques. Les compteurs d’événements sont pris en charge sur 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.

Alors que les utilisateurs peuvent publier n’importe quel compteur d’événements personnalisé pour répondre à leurs besoins, .NET publie un ensemble de ces compteurs par défaut. Ce document décrit les étapes nécessaires à la collecte et à l’affichage des compteurs d’événements (définis par le système ou par l’utilisateur) dans Azure Application Insights.

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 Compteurs disponibles.

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énement

Vous pouvez rechercher et afficher des rapports de compteurs 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.

Collection d’instantanés

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

Dans cette section

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

Indicateurs en temps réel

Pour activer l’envoi de métriques en temps réel de votre application vers Azure, utilisez setSendLiveMetrics(true). Le filtrage des métriques en temps réel dans le portail n’est actuellement pas pris en charge.

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 : la vue diagnostics des transactions pour une transaction/requête unique et la vue carte d’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 SDK Application Insights pour .NET, .NET Core, Java, Node.js et JavaScript prennent tous en charge le suivi distribué nativement.

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 chaîne de connexion 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 Interroger des données sur des espaces de travail, des applications et des ressources Log Analytics dans Azure Monitor.

Example

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.

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 :

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()

Métriques étendues

Pour activer l’envoi de métriques natives étendues de votre application vers 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.

API TelemetryClient

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 :

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.

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.

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.

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 :

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.

ASP.NET Core

L’ajout d’un initialiseur à l’aide 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 DependencyInjection conteneur, 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();

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.

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 :

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

Pour ASP.NET Core, 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.

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

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.

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 Échantillonnage 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

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.

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.

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 à composants multiples

Dans certains scénarios, votre application peut consister en plusieurs composants que vous voulez instrumenter avec la même chaîne de connexion. 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();

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 de développement logiciel (SDK) .NET Application Insights se compose d’un certain nombre de 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, quand vous utilisez l’expérience automatisée des projets de modèle Visual Studio qui prennent en charge Ajouter>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.

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 applications Core, toutes les modifications de configuration sont apportées dans la ConfigureServices() méthode de votre classe Startup.cs , sauf indication contraire.

Service Worker

La valeur par défaut TelemetryConfiguration utilisée par le Kit de développement logiciel (SDK) du service Worker 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 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.

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 SDK intègrent deux canaux de télémétrie : InMemoryChannel et ServerTelemetryChannel. Cette section décrit chaque canal et montre comment personnaliser le comportement du canal.

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 .NET et .NET Core d’Application Insights intègrent deux canaux :

• 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 utilisé par défaut pour les applications ASP.NET et ASP.NET Core qui sont 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 du canal de télémétrie sur TelemetryConfiguration.Active, ou de modifier ApplicationInsights.config. Pour les applications ASP.NET Core, la configuration implique d’ajouter le canal au conteneur d’injection de dépendance.

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();
}

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();

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, le dossier %LOCALAPPDATA% ou %TEMP% est utilisé si aucun autre chemin n’a été 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.

ASP.NET Core

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>

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 :

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 extraite du fichier appsettings.json configure la chaîne de connexion et désactive l’échantillonnage adaptatif et la collecte des compteurs de performances.

{
    "ApplicationInsights": {
    "ConnectionString": "<YOUR-CONNECTION-STRING>",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

Si vous utilisez builder.Services.AddApplicationInsightsTelemetry(aiOptions), pour ASP.NET Core 6.0 ou services.AddApplicationInsightsTelemetry(aiOptions) pour ASP.NET Core 3.1 et versions antérieures, 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 Le problème GitHub 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 dans ce SDK se trouve dans l'espace de noms Microsoft.ApplicationInsights.WorkerService, contrairement au Microsoft.ApplicationInsights.AspNetCore.Extensions dans le SDK ASP.NET Core.

Le tableau suivant répertorie les paramètres couramment utilisés dans ApplicationInsightsServiceOptions.

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épendance ASP.NET n’importe où dans votre code et définir l’indicateur DisableTelemetry sur celle-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épendance ASP.NET n’importe où dans votre code et définir l’indicateur DisableTelemetry sur celle-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 général, vous créez une ressource séparée, avec une chaîne de connexion distincte, pour chacune de vos applications.

Consultez Chaînes de connexion dans Application Insights pour obtenir des exemples de code.

Si vous souhaitez définir la chaîne de connexion de manière dynamique, par exemple pour transmettre des résultats de votre application vers différentes ressources, vous pouvez omettre la chaîne de connexion du fichier de configuration, et la définir plutôt dans le code.

ASP.NET

Pour définir la chaîne de connexion 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 chaîne de connexion, créez une ressource dans le portail Application Insights.

ASP.NET Core

Dans ASP.NET Core, configurez la chaîne de connexion dans Program.cs pendant le démarrage de l’application en utilisant la TelemetryConfiguration du conteneur d’injection de dépendances (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 explicitement sa chaîne de connexion :

using Microsoft.ApplicationInsights;

var tc = new TelemetryClient();
tc.Context.ConnectionString = "<YOUR-CONNECTION-STRING>";
tc.TrackEvent("myEvent");
// ...

Fournisseur ApplicationId

L’objectif de ce fournisseur est de rechercher un ID d’application à partir d’une chaîne de connexion. 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 chaîne de connexion 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

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 chaîne de connexion/ID d'application configurées.

Cette classe a la Defined propriété, qui est une Dictionary<string,string> paire de chaînes de connexion/ID d’application.

Cette classe possède la propriété facultative Next qui peut servir à configurer un autre fournisseur à utiliser lorsqu’une chaîne de connexion demandée 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();

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.

Chaîne de connexion

Ce paramètre détermine la ressource Application Insights dans laquelle vos données s’affichent. En général, vous créez une ressource séparée, avec une chaîne de connexion distincte, pour chacune de vos applications.

Consultez Chaînes de connexion dans Application Insights pour obtenir des exemples de code.

Si vous souhaitez définir la chaîne de connexion de manière dynamique, par exemple pour transmettre des résultats de votre application vers différentes ressources, vous pouvez omettre la chaîne de connexion du fichier de configuration, et la définir plutôt dans le code.

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().

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.

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.

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 MVC ASP.NET basée sur un modèle 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>
   

Alternativement à l’utilisation de FullScript, ScriptBody est disponible à partir du 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.

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 Web Instrumentation peut être modifiée en définissant la variable d’environnement APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

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 = "...";

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.

telemetry.TrackEvent("WinGame");

telemetry.trackEvent({name: "WinGame"});

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

telemetry.trackMetric({name: "queueLength", value: 42.0});

telemetry.TrackPageView("GameReviewPage");

Non applicable.

// 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.

// 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.

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

Dans .NET, les Adaptateurs de journaux utilisent cette API pour envoyer des journaux tiers au portail.

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

Non applicable.

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);
}

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
    });
}

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.

La fonction est asynchrone pour le canal de télémétrie du serveur.

telemetry.flush();

// 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);

// 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});

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);

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");

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

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).

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

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;

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

Non applicable.