Partager via

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

Note

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

Caution

Nous recommandons la distribution OpenTelemetry Azure Monitor pour les nouvelles applications ou les nouveaux clients afin d’alimenter Azure Monitor Application Insights. La distribution OpenTelemetry Azure Monitor offre une expérience et des fonctionnalités similaires à celles du SDK Application Insights. Il est possible de migrer depuis le Kit de développement logiciel (SDK) Application Insights en utilisant les guides de migration pour .NET, Node.js et Python, mais nous travaillons encore à l’ajout de quelques fonctionnalités supplémentaires pour la compatibilité descendante.

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

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

Scénarios pris en charge

Note

Le Kit de développement logiciel (SDK) Application Insights pour ASP.NET Core et sdk pour Worker Service peut surveiller vos applications où ou comment elles s’exécutent. Si votre application est en cours d’exécution et dispose d’une connectivité réseau vers Azure, les données de télémétrie peuvent être collectées.

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

Note

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

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.

Ajouter Application Insights

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.

  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.

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.

Note

Il existe un problème connu dans Visual Studio 2019 : le stockage de la clé d’instrumentation ou de la chaîne de connexion dans un secret d’utilisateur est interrompu pour les applications basées sur .NET Framework. La clé doit finalement être codée en dur dans le fichier Applicationinsights.config pour contourner ce bogue.

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

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.

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

  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.

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

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.

Configurer la télémétrie

Dans cette section

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.

Note

Les mesures en direct sont activées par défaut lorsque vous les intégrez en suivant les instructions recommandées pour les applications .NET.

Activer les métriques en direct par le biais du code pour n'importe quelle application .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.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";
            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-HERE";
            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();
            }
        }
    }
}

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.

Note

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

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

  • Pour passer en revue les questions fréquemment posées (FAQ), consultez La journalisation avec le FAQ .NET.

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

Installer la journalisation sur votre application

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>

Note

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

Configurer Application Insights pour collecter des journaux de suivi

Option 1 : Ajoutez Application Insights à votre projet si vous ne l’avez pas déjà fait. Lors de l’ajout d’Application Insights dans Visual Studio, 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 .

Note

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

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 :

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

Instructions d’installation :

Note

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


ILogger

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

  2. Ajouter ApplicationInsightsLoggerProvider:

using Microsoft.Extensions.Logging.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

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

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

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

var app = builder.Build();

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

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

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

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

public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

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

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

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

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

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

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

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

Si vous préférez log4net ou NLogutilisez :

    logger.Warn("Slow response - database01");
Utiliser les événements de EventSource

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

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

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

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

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

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

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

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

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

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

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

Utiliser des événements ETW

Vous pouvez configurer les événements de suivi d’événements pour Windows (ETW) à envoyer à Application Insights en tant que traces.

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

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

Note

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

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

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

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

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

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

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

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

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

Vous pouvez désormais facilement filtrer dans la recherche de transactions tous les messages d’un niveau de gravité particulier qui concernent 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 :

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

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

using var channel = new InMemoryChannel();

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

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

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

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

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

Étendues de journalisation

Note

Les instructions suivantes s’appliquent aux scénarios ILogger (ASP.NET Core et console uniquement). Elle ne s’applique pas aux ASP.NET classiques.

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.

Dans le volet vue d’ensemble de votre application dans le portail Application Insights, sélectionnez Recherche de transactions dans laquelle vous pouvez :

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

Note

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

Explorer dans les journaux 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.

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

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

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

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

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

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

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

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

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

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

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

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

Activer la prise en charge du suivi distribué W3C

Le suivi distribué basé sur W3C TraceContext est activé par défaut dans tous les SDK .NET Framework/.NET Core récents, avec une compatibilité rétroactive avec le protocole hérité Request-Id.

Corrélation 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 :

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

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

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

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

Note

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

Suivi manuel des dépendances

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

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

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

Exemple

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

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


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

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

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

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

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

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

Note

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

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.

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

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

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

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.

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

Important

Cette section se concentre sur les applications .NET Framework du point de vue d’un exemple de code. Certaines des méthodes qui fonctionnent pour .NET Framework sont obsolètes dans le kit SDK .NET Core.

Diagnostiquer les défaillances et les exceptions

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.

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.

Capture d’écran montrant l’écran Recherche.

Note

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

Afficher les données POST de requête

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

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.

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

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 rechercher tous les rapports d'exception liés à un jeu particulier. Vous pouvez ajouter autant d’éléments que vous le souhaitez à chaque dictionnaire.

Exceptions du navigateur

La plupart des exceptions de navigateur sont signalées.

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

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

Note

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

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


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

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

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

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

MVC 2

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

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

Exemple

MVC 3

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

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

Exemple

MVC 4, MVC 5

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

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

Exemple

API Web

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

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

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

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

Prise en charge des versions antérieures

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


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

API Web 1.x

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

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

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

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

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

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

Exemple

API Web 2.x

Ajoutez une implémentation de IExceptionLogger :

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

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

Ajoutez cet extrait de code aux services dans WebApiConfig :

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

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

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

Exemple

Alternativement, vous pouvez :

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

WCF

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

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

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

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

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

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

            ai.TrackException(error);
            return false;
        }

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

Ajoutez l'attribut aux implémentations de service :

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

Exemple

Compteurs de performance des exceptions

Si vous avez installé l’agent Azure Monitor Application Insights sur votre serveur, vous pouvez obtenir un graphique du taux d’exceptions mesuré par .NET. Les exceptions .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.


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

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

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

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

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

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

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

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

Bien démarrer avec GetMetric

Pour nos exemples, nous allons utiliser une application de service Worker .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.

Note

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

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

Capture d’écran montrant l’affichage des requêtes Log Analytics.

Note

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

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

Capture d’écran montrant la vue Metrics Explorer.

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

Capture d’écran montrant la vue Log Analytics de la métrique multidimensionnelle.

Dans l'explorateur de métriques :

Capture d’écran montrant les métriques personnalisées.

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.

Capture d’écran montrant la prise en charge du fractionnement.

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

Activer les métriques multidimensionnelles

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

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

Note

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

Capture d’écran montrant l’application du fractionnement.

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

Capture d’écran montrant les facteurs de forme.

Utilisez MetricIdentifier lorsqu'il y a plus de trois dimensions

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

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

Configuration de métrique personnalisée

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

Noms de dimensions spéciales

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

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

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

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

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

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

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

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

_telemetryClient.GetMetric("Request Size", "Operation Name", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation", "Special Operation");
Limitation des dimensions et des séries chronologiques

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

Important

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

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

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

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

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

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

// The following call gives 3rd unique value for dimension2, which is above the limit of 2.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3");
// The above call does not 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.


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

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

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

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

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

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

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

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

Instrumentation des files d’attente

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

Note

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

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

File d’attente 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.

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

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.

Avertissement

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

Suivi et traitement d’opérations parallèles

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

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

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

await firstTask;

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

await secondTask;

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

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

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

Opérations ApplicationInsights vs System.Diagnostics.Activity

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

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

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

Compteurs dans Application Insights

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.

Aperçu

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

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

Compteurs de performance

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

Conseil / Astuce

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

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.

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

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.

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.

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.

Conseil / Astuce

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

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

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

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

Compteurs par défaut collectés

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

Pour obtenir la liste des compteurs connus publiés par le Runtime .NET, consultez le document 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.

Filtrer et enrichir les données de télémétrie

Dans cette section

Filtrer et prétraiter les données de télémétrie

Vous pouvez écrire du code pour filtrer, modifier ou enrichir vos données de télémétrie avant d’être envoyées à partir du Kit de développement logiciel (SDK). Le traitement inclut les données envoyées à partir des modules de télémétrie standard, tels que la collecte de requêtes HTTP et la collecte de dépendances.

  • Le filtrage peut modifier ou ignorer les données de télémétrie avant qu’elles ne soient envoyées à partir du Kit de développement logiciel (SDK) en implémentant ITelemetryProcessor. Par exemple, vous pouvez réduire le volume de données de télémétrie en excluant les demandes des robots. Contrairement à l’échantillonnage, vous avez un contrôle total sur ce qui est envoyé ou ignoré, mais il affecte toutes les métriques basées sur les journaux agrégés. Selon la façon dont vous supprimez les éléments, vous risquez également de perdre la capacité de naviguer entre les éléments associés.

  • Ajoutez ou modifiez des propriétés à toutes les données de télémétrie envoyées à partir de votre application en implémentant un ITelemetryInitializer. Par exemple, vous pouvez ajouter des valeurs calculées ou des numéros de version pour filtrer les données dans le portail.

  • L’échantillonnage réduit le volume de données de télémétrie sans affecter vos statistiques. Il conserve les points de données associés afin que vous puissiez naviguer entre eux lorsque vous diagnostiquez un problème. Dans le portail, le nombre total est multiplié pour compenser l’échantillonnage.

Note

L’API sdk est utilisée pour envoyer des événements et des métriques personnalisés.

Filtrage

Cette technique vous permet de contrôler directement ce qui est inclus ou exclu du flux de télémétrie. Le filtrage peut être utilisé pour empêcher l'envoi des éléments de télémétrie à Application Insights. Vous pouvez utiliser le filtrage avec l’échantillonnage ou séparément.

Pour filtrer les données de télémétrie, vous écrivez un processeur de télémétrie et l’inscrivez auprès de TelemetryConfiguration. Toutes les données de télémétrie passent par votre processeur. Vous pouvez choisir de le supprimer du flux ou de le donner au processeur suivant dans la chaîne. Les données de télémétrie des modules standard, telles que le collecteur de requêtes HTTP et le collecteur de dépendances, et les données de télémétrie que vous avez suivies vous-même sont incluses. Vous pouvez, par exemple, filtrer la télémétrie concernant les requêtes émanant de robots ou les appels de dépendance réussis.

Avertissement

Le filtrage des données de télémétrie envoyées à partir du Kit de développement logiciel (SDK) à l’aide de processeurs peut fausser les statistiques que vous voyez dans le portail et compliquer le suivi des éléments connexes.

Au lieu de cela, envisagez d’utiliser l’échantillonnage.

ITelemetryProcessor et ITelemetryInitializer

Quelle est la différence entre les processeurs de télémétrie et les initialiseurs de télémétrie ?

  • Il y a des chevauchements dans ce que vous pouvez faire avec eux. Les deux peuvent être utilisés pour ajouter ou modifier des propriétés de télémétrie, bien que nous vous recommandons d’utiliser des initialiseurs à cet effet.
  • Les initialiseurs de télémétrie s’exécutent toujours avant les processeurs de télémétrie.
  • Les initialiseurs de télémétrie peuvent être appelés plusieurs fois. Par convention, ils ne définissent aucune propriété qui a déjà été définie.
  • Les processeurs de télémétrie vous permettent de remplacer ou d’ignorer complètement un élément de télémétrie.
  • Tous les initialiseurs de télémétrie inscrits sont appelés pour chaque élément de télémétrie. Pour les processeurs de télémétrie, le SDK garantit l’appel du premier processeur de télémétrie. Si le reste des processeurs est appelé ou non est décidé par les processeurs de télémétrie précédents.
  • Utilisez des initialiseurs de télémétrie pour enrichir les données de télémétrie avec davantage de propriétés ou remplacer un initialiseur existant. Utilisez un processeur de télémétrie pour filtrer les données de télémétrie.

Ajouter/modifier des propriétés

Utilisez des initialiseurs de télémétrie pour enrichir les données de télémétrie avec des informations supplémentaires ou pour remplacer les propriétés de télémétrie définies par les modules de télémétrie standard.

Par exemple, Application Insights pour un package web collecte des données de télémétrie sur les requêtes HTTP. Par défaut, il signale toute requête avec un code >de réponse =400 comme ayant échoué. Si vous souhaitez plutôt traiter 400 comme un succès, vous pouvez fournir un initialiseur de télémétrie qui configure la propriété de succès.

Si vous fournissez un initialiseur de télémétrie, il est appelé chaque fois que l’une des méthodes Track*() est appelée. Cet initialiseur inclut des Track() méthodes appelées par les modules de télémétrie standard. Par convention, ces modules ne définissent aucune propriété qui a déjà été définie par un initialiseur. Les initialiseurs de télémétrie sont appelés avant d’appeler des processeurs de télémétrie. Les enrichissements effectués par les initialiseurs sont donc visibles par les processeurs.

Initialiseurs de télémétrie

Pour enrichir les données de télémétrie avec des informations supplémentaires ou remplacer les propriétés de télémétrie définies par les modules de télémétrie standard, utilisez des initialiseurs de télémétrie.

Les initialiseurs de télémétrie définissent les propriétés de contexte envoyées avec chaque élément de télémétrie. Vous pouvez écrire vos propres initialiseurs pour définir des propriétés de contexte.

Les initialiseurs standard sont tous définis par les packages NuGet web ou WindowsServer :

Initialiseur Descriptif
AccountIdTelemetryInitializer Définit la propriété AccountId.
AuthenticatedUserIdTelemetryInitializer Définit la propriété AuthenticatedUserId déterminée par le kit de développement logiciel (SDK) JavaScript.
AzureRoleEnvironmentTelemetryInitializer Met à jour les propriétés RoleName et RoleInstance du contexte Device pour tous les éléments de télémétrie avec des informations extraites de l'environnement du runtime Azure.
BuildInfoConfigComponentVersionTelemetryInitializer Met à jour la propriété Version du contexte Component pour tous les éléments de télémétrie avec la valeur extraite du fichier BuildInfo.config produit par MS Build.
ClientIpHeaderTelemetryInitializer Met à jour la propriété Ip du contexte Location de tous les éléments de télémétrie en fonction de l’en-tête HTTP X-Forwarded-For de la requête.
DeviceTelemetryInitializer Met à jour les propriétés suivantes du contexte Device pour tous les éléments de télémétrie :

• Type est défini sur PC.
• Id est défini sur le nom de domaine de l'ordinateur sur lequel l'application web s’exécute.
• OemName est défini sur la valeur extraite du champ Win32_ComputerSystem.Manufacturer en utilisant WMI.
• Model est défini sur la valeur extraite du champ Win32_ComputerSystem.Model en utilisant WMI.
• NetworkType est défini sur la valeur extraite de la propriété NetworkInterface.
• Language est défini sur le nom de la propriété CurrentCulture.
DomainNameRoleInstanceTelemetryInitializer Met à jour la propriété RoleInstance du contexte Device pour tous les éléments de télémétrie avec le nom de domaine de l'ordinateur sur lequel l'application web s’exécute.
OperationNameTelemetryInitializer Met à jour la propriété Name de RequestTelemetry et la propriété Name du contexte Operation de tous les éléments de télémétrie en fonction de la méthode HTTP, ainsi que les noms du contrôleur ASP.NET MVC et de l’action appelée pour traiter la requête.
OperationIdTelemetryInitializer ou OperationCorrelationTelemetryInitializer Met à jour la propriété du contexte Operation.Id de tous les éléments de télémétrie suivis lors de la gestion d’une requête avec la RequestTelemetry.Id générée automatiquement.
SessionTelemetryInitializer Met à jour la propriété Id du contexte Session pour tous les éléments de télémétrie avec la valeur extraite du cookie ai_session généré par le code d’instrumentation JavaScript ApplicationInsights en cours d'exécution dans le navigateur de l'utilisateur.
SyntheticTelemetryInitializer ou SyntheticUserAgentTelemetryInitializer Met à jour les propriétés de contexte User, Session et Operation de tous les éléments de télémétrie suivis lors du traitement d'une requête émanant d'une source synthétique, comme un test de disponibilité ou un robot de moteur de recherche. Par défaut, Metrics Explorer n'affiche pas la télémétrie synthétique.

Ensemble de <Filters> qui identifie les propriétés des requêtes.
UserTelemetryInitializer Met à jour les propriétés Id et AcquisitionDate du contexte User pour tous les éléments de télémétrie avec les valeurs extraites du cookie ai_user généré par le code d’instrumentation JavaScript Application  Insights en cours d'exécution dans le navigateur de l'utilisateur.
WebTestTelemetryInitializer Définit l’ID utilisateur, l’ID de session et les propriétés de source synthétiques pour les requêtes HTTP provenant des tests de disponibilité.

Ensemble de <Filters> qui identifie les propriétés des requêtes.

Note

Pour les applications .NET en cours d’exécution dans Azure Service Fabric, vous pouvez inclure le package NuGet Microsoft.ApplicationInsights.ServiceFabric. Ce package comprend une propriété FabricTelemetryInitializer, qui ajoute des propriétés Service Fabric pour les éléments de télémétrie. Pour plus d’informations, consultez la page GitHub sur les propriétés ajoutées par ce package NuGet.

Ajouter ITelemetryInitializer

Ce blog décrit un projet pour diagnostiquer les problèmes de dépendance en envoyant automatiquement des pings réguliers aux dépendances.

  1. Définir votre initialiseur

    using System;
using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.DataContracts;
using Microsoft.ApplicationInsights.Extensibility;

namespace MvcWebRole.Telemetry
{
  /*
   * Custom TelemetryInitializer that overrides the default SDK
   * behavior of treating response codes >= 400 as failed requests
   *
   */
    public class MyTelemetryInitializer : ITelemetryInitializer
    {
        public void Initialize(ITelemetry telemetry)
        {
            var requestTelemetry = telemetry as RequestTelemetry;
            // Is this a TrackRequest() ?
            if (requestTelemetry == null) return;
            int code;
            bool parsed = Int32.TryParse(requestTelemetry.ResponseCode, out code);
            if (!parsed) return;
            if (code >= 400 && code < 500)
            {
                // If we set the Success property, the SDK won't change it:
                requestTelemetry.Success = true;

                // Allow us to filter these requests in the portal:
                requestTelemetry.Properties["Overridden400s"] = "true";
            }
            // else leave the SDK to set the Success property
        }
    }
}

  2. Charger votre initialiseur

Option 1 : configuration dans le code

protected void Application_Start()
{
    // ...
    TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
}

Option 2 : configuration dans ApplicationInsights.config

<ApplicationInsights>
    <TelemetryInitializers>
    <!-- Fully qualified type name, assembly name: -->
    <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/>
    ...
    </TelemetryInitializers>
</ApplicationInsights>

Pour en savoir plus, consultez cet exemple.

Note

Vérifiez que le fichier applicationinsights.config se trouve dans votre répertoire de sortie et contient les modifications récentes.

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 le nom du rôle cloud et l’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

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

  1. 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 recevez 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;
    }
}

  2. Ajoutez votre processeur.

    Insérez cet extrait de code dans ApplicationInsights.config:

    <TelemetryProcessors>
  <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9">
    <!-- Set public property -->
    <MyParamFromConfigFile>2-beta</MyParamFromConfigFile>
  </Add>
</TelemetryProcessors>

    Vous pouvez transmettre des valeurs de chaîne à partir du fichier .config en fournissant des propriétés nommées publiques dans votre classe.

    Avertissement

    Veillez à faire correspondre le nom de type et tous les noms de propriétés du fichier .config aux noms de classe et de propriété dans le code. Si le fichier .config fait référence à un type ou à une propriété inexistants, le Kit de développement logiciel (SDK) peut échouer en mode silencieux pour envoyer des données de télémétrie.

    Vous pouvez également initialiser le filtre dans le code. Dans une classe d’initialisation appropriée, par exemple, AppStart in Global.asax.cs, insérez votre processeur dans la chaîne :

    Note

    L’exemple de code suivant est obsolète, mais est mis à disposition ici pour la postérité. Envisagez de bien démarrer avec OpenTelemetry ou de migrer vers OpenTelemetry.

    var builder = TelemetryConfiguration.Active.DefaultTelemetrySink.TelemetryProcessorChainBuilder;
builder.Use((next) => new SuccessfulDependencyFilter(next));

// If you have more processors:
builder.Use((next) => new AnotherProcessor(next));

builder.Build();

    Les clients de télémétrie créés après ce point utilisent vos processeurs.

    Processeur de télémétrie d'échantillonnage adaptatif (à partir de 2.0.0-beta3)

    Cette fonctionnalité est activée par défaut. Si votre application envoie beaucoup de télémétrie, ce processeur en supprime une partie.

    
    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

    Le paramètre fournit la cible que l'algorithme essaie d'atteindre. Chaque instance du Kit de développement logiciel (SDK) fonctionne de manière indépendante. Ainsi, si votre serveur est un cluster de plusieurs ordinateurs, le volume réel des données de télémétrie est multiplié en conséquence.

    En savoir plus sur l’échantillonnage.

    Processeur de télémétrie d'échantillonnage à taux fixe (à partir de 2.0.0-beta1)

    Il existe également un processeur de télémétrie d’échantillonnage standard (à partir de la version 2.0.1) :

        <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

Exemples de filtres

Demandes synthétiques

Filtrez les bots et les tests web. Bien que Metrics Explorer vous donne la possibilité de filtrer les sources synthétiques, cette option réduit la taille du trafic et de l’ingestion en les filtrant au niveau du SDK lui-même.

public void Process(ITelemetry item)
{
    if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
    
    // Send everything else:
    this.Next.Process(item);
}
Échec de l’authentification

Filtrez les requêtes avec une réponse « 401 ».

public void Process(ITelemetry item)
{
    var request = item as RequestTelemetry;

    if (request != null &&
    request.ResponseCode.Equals("401", StringComparison.OrdinalIgnoreCase))
    {
        // To filter out an item, return without calling the next processor.
        return;
    }

    // Send everything else
    this.Next.Process(item);
}
Excluez les appels de dépendance à distance rapides.

Si vous souhaitez diagnostiquer uniquement les appels lents, filtrez les appels rapides.

Note

Ce filtrage fausse les statistiques que vous voyez sur le portail.

public void Process(ITelemetry item)
{
    var request = item as DependencyTelemetry;

    if (request != null && request.Duration.TotalMilliseconds < 100)
    {
        return;
    }
    this.Next.Process(item);
}

Échantillonnage

Pour savoir comment configurer l’échantillonnage pour ASP.NET applications, consultez Échantillonnage dans Application Insights.

Enrichir des données via HTTP

var requestTelemetry = HttpContext.Current?.Items["Microsoft.ApplicationInsights.RequestTelemetry"] as RequestTelemetry;

if (requestTelemetry != null)
{
    requestTelemetry.Properties["myProp"] = "someData";
}

Gérer les composants du Kit de développement logiciel (SDK)

Dans cette section

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.

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.

Important

Le fichier de configuration est ignoré si l’extension pour les sites web Azure ou l’extension pour les machines virtuelles Azure et les ensembles de machines virtuelles Azure est utilisée.

Il n’existe aucun fichier équivalent permettant de contrôler le kit de développement logiciel (SDK) dans une page web.

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.

Note

Pour examiner les questions fréquentes (FAQ), consultez les FAQ sur les canaux de télémétrie

Que sont les canaux de télémétrie ?

Les canaux de télémétrie gèrent la mise en mémoire tampon des éléments de télémétrie et la transmission de ces éléments au service Application Insights, où ils sont stockés pour être interrogés et analysés. Un canal de télémétrie est une classe qui implémente l’interface Microsoft.ApplicationInsights.ITelemetryChannel.

La méthode Send(ITelemetry item) d’un canal de télémétrie est appelée une fois que tous les initialiseurs et processeurs de télémétrie ont été appelés. Par conséquent, tous les éléments supprimés par un processeur de télémétrie n’atteignent pas le canal. La méthode Send() n’envoie généralement pas instantanément les éléments au back-end. Il les place généralement en mémoire tampon et les envoie par lots pour optimiser leur transmission.

Évitez d’appeler Flush(), sauf s’il est essentiel d’envoyer immédiatement des données de télémétrie mises en mémoire tampon. Utilisez-le uniquement dans des scénarios tels que l’arrêt de l’application, la gestion des exceptions ou lors de l’utilisation de processus de courte durée, tels que des travaux en arrière-plan ou des outils en ligne de commande. Dans les applications web ou les services de longue durée, le kit de développement logiciel (SDK) gère automatiquement l’envoi de données de télémétrie. Appeler Flush() inutilement peut entraîner des problèmes de niveau de performance.

Le flux de métriques temps réel a également un canal personnalisé pour le streaming en direct des données de télémétrie. Le présent document ne s’applique pas à ce canal, qui est indépendant du canal de télémétrie standard.

Canaux de télémétrie intégrés

Les kits SDK .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.

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>

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 :

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.

Chaque module de télémétrie collecte un type de données précis et utilise l'API de base pour envoyer les données. Les modules sont installés par différents packages NuGet, qui ajoutent également les lignes requises dans le fichier .config.

Area Descriptif
Suivi des requêtes Collecte les données de télémétrie des requêtes (temps de réponse, code de résultat) pour les requêtes web entrantes.

Module:Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
NuGet :Microsoft.ApplicationInsights.Web
Suivi des dépendances Collecte les données de télémétrie sur les dépendances sortantes (appels HTTP, appels SQL). Pour travailler dans IIS, installez l’agent Application Insights. Vous pouvez également écrire un suivi des dépendances personnalisé en utilisant l’API TrackDependency. Prend en charge l’autoinstrumentation avec App Service et machines virtuelles et la surveillance des groupes de machines virtuelles identiques.

Module:Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
NuGet :Microsoft.ApplicationInsights.DependencyCollector
Compteurs de performances Collecte les compteurs de performance Windows (processeur, mémoire, charge réseau à partir des installations IIS). Spécifiez les compteurs (y compris les compteurs personnalisés). Pour plus d’informations, consultez Collecte les compteurs de performance système.

Module:Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
NuGet :Microsoft.ApplicationInsights.PerfCounterCollector
Compteurs d’événements Collecte .NET EventCounters. Recommandé pour ASP.NET Core et multiplateforme à la place des compteurs de performance Windows.

Module:EventCounterCollectionModule (SDK ≥ 2.8.0)
Métriques en direct (QuickPulse) Collecte les données de télémétrie pour le volet Métriques en direct.

Module:QuickPulseTelemetryModule
Pulsations (App Service) Envoie des pulsations et des métriques personnalisées pour l’environnement App Service.

Module:AppServicesHeartbeatTelemetryModule
Pulsations (machines virtuelles et de groupes de machines virtuelles identiques) Envoie des pulsations et des métriques personnalisées pour l’environnement de machine virtuelle Azure.

Module:AzureInstanceMetadataTelemetryModule
Télémétrie des diagnostics Signale des erreurs dans le code d’instrumentation Application Insights (par exemple, compteurs manquants, exceptions ITelemetryInitializer). La télémétrie de trace s’affiche dans Recherche de diagnostic.

Module:Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
NuGet :Microsoft.ApplicationInsights

Remarque : si vous installez simplement ce package, le fichier ApplicationInsights.config n’est pas automatiquement créé.
Mode développeur (débogueur attaché) Force TelemetryChannel à envoyer des éléments immédiatement lorsque le débogueur est attaché. Réduit la latence, mais augmente la surcharge processeur/réseau.

Module:Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
NuGet :Application Insights Windows Server
Suivi des exceptions (web) Suit le nombre d’exceptions non traitées dans les applications web. Consultez Échecs et exceptions.

Module:Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule
NuGet :Microsoft.ApplicationInsights.Web
Suivi des exceptions (non observé/non géré) Suit les exceptions de tâche non observées et les exceptions non gérées pour les rôles worker, les services Windows et les applications console.

Modules :
 • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule
 • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule
NuGet :Microsoft.ApplicationInsights.WindowsServer
Suivi EventSource Envoie les événements EventSource configurés à Application Insights en tant que traces.

Module:Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
NuGet :Microsoft.ApplicationInsights.EventSourceListener
Collecteur ETW Envoie des événements du fournisseur ETW configurés à Application Insights en tant que traces.

Module:Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
NuGet :Microsoft.ApplicationInsights.EtwCollector
API principale (pas un module) API principale utilisée par d’autres composants de télémétrie et pour la télémétrie personnalisée.

Module:Microsoft.ApplicationInsights package
NuGet :Microsoft.ApplicationInsights
Remarque : si vous installez simplement ce package, le fichier ApplicationInsights.config n’est pas automatiquement créé.

Configurer des modules de télémétrie

Utilisez la section TelemetryModules dans ApplicationInsights.config pour configurer, ajouter ou supprimer des modules. Les exemples suivants :

  • Configurer DependencyTrackingTelemetryModule (activer l’injection d’en-tête W3C).
  • Configurer EventCounterCollectionModule (effacer les valeurs par défaut et ajouter un compteur unique).
  • Désactiver la collecte des compteurs de performance en supprimant PerformanceCollectorModule.
<ApplicationInsights>
  <TelemetryModules>

    <!-- Dependency tracking -->
    <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
      <!-- Match Core example: enable W3C header injection -->
      <EnableW3CHeadersInjection>true</EnableW3CHeadersInjection>
    </Add>

    <!-- EventCounterCollectionModule: add a single counter (if you use event counters) -->
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.EventCounterCollectionModule, Microsoft.AI.PerfCounterCollector">
      <Counters>
        <!-- Mirrors Core example: only collect 'gen-0-size' from System.Runtime -->
        <Add ProviderName="System.Runtime" CounterName="gen-0-size" />
      </Counters>
    </Add>

    <!-- PerformanceCollectorModule (classic Windows performance counters).
         To DISABLE perf-counter collection, do NOT include this module.
         If it already exists in your file, remove or comment it out.
         Example of the line you would remove:
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector" />
    -->

  </TelemetryModules>
</ApplicationInsights>

Note

L’ensemble exact de modules présents dans votre ApplicationInsights.config dépend des packages SDK que vous avez installés.

Désactiver la télémétrie

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.

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.

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 = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
        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 = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
    tc.TrackEvent("myEvent");
    // ...

Pour obtenir une nouvelle chaîne de connexion, créez une ressource dans le portail Application Insights.

Fournisseur ApplicationId

Note

Pour ASP.NET, ce fournisseur est disponible à partir du kit de développement logiciel (SDK) v2.6.0*.

L’objectif de ce fournisseur est de rechercher un ID d’application à 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 instrumentationKey, 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 du runtime, {0} est remplacé par la clé d’instrumentation pour chaque requête.

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

DictionaryApplicationIdProvider

Il s’agit d’un fournisseur statique qui s’appuie sur vos paires configurées de clés d’instrumentation/ID d’application.

Cette classe a la propriété Defined, qui est une Dictionary<string,string> des paires de clés d’instrumentation/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.

Exemple de configuration via ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_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>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

Configurer la collecte de capture instantanée

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.

Ajout d’une surveillance côté client

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.

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.

API principale pour les événements et métriques personnalisés

Insérez quelques lignes de code dans votre application pour savoir ce que les utilisateurs font avec lui ou pour aider à diagnostiquer les problèmes. Vous pouvez envoyer des données de télémétrie à partir d’applications d’appareil et de bureau, de clients web et de serveurs web. Utilisez l’API de télémétrie principale Application Insights pour envoyer des événements et des métriques personnalisés et vos propres versions de données de télémétrie standard. Cette API est la même API que celle utilisée par les collecteurs de données Application Insights standard.

Résumé de l’API

L’API principale est uniforme sur toutes les plateformes, à l’exception de quelques variantes telles que GetMetric (.NET uniquement).

Méthode Utilisé pour
TrackPageView Pages, écrans, volets ou formulaires.
TrackEvent Actions utilisateur et autres événements. Permet de suivre le comportement de l’utilisateur ou d’analyser les performances.
GetMetric Métriques zéro et multidimensionnelle, agrégation configurée de manière centralisée, C# uniquement.
TrackMetric Mesures de performances telles que les longueurs de file d’attente non liées à des événements spécifiques.
TrackException Journalisation des exceptions pour le diagnostic. Effectuez un suivi lorsqu’ils se produisent par rapport à d’autres événements et examinez les arborescences des appels de procédure.
TrackRequest Journalisation de la fréquence et de la durée des demandes de serveur pour l’analyse des performances.
TrackTrace Messages du journal de diagnostic des ressources. Vous pouvez également capturer des journaux tiers.
TrackDependency Journalisation de la durée et de la fréquence des appels à des composants externes dont dépend votre application.

Vous pouvez attacher des propriétés et des métriques à la plupart de ces appels de télémétrie.

Prerequisites

Si vous n’avez pas encore de référence sur le Kit de développement logiciel (SDK) Application Insights :

  1. Ajoutez le Kit de développement logiciel (SDK) Application Insights à votre projet.

  2. Dans le code de votre appareil ou serveur web, incluez :

    using Microsoft.ApplicationInsights;

Obtenir une instance TelemetryClient

Obtenir une instance de TelemetryClient:

Note

Si vous utilisez Azure Functions v2+ ou Azure WebJobs v3+, consultez Monitor Azure Functions.

Note

Pour les applications ASP.NET Core et non HTTP/Worker pour .NET/.NET Core, obtenez une instance de TelemetryClient à partir du conteneur d’injection de dépendances comme expliqué dans la documentation correspondante.

private TelemetryClient telemetry = new TelemetryClient();

Si vous voyez un message indiquant que cette méthode est obsolète, consultez microsoft/ApplicationInsights-dotnet#1152 pour plus d’informations.

Les requêtes HTTP entrantes sont automatiquement capturées. Vous pourriez vouloir créer davantage d'instances de TelemetryClient pour d'autres modules de votre application. Par exemple, vous pouvez avoir une TelemetryClient instance dans votre classe middleware pour signaler des événements de logique métier. Vous pouvez définir des propriétés telles que UserId et DeviceId identifier l’ordinateur. Ces informations sont attachées à tous les événements envoyés par l’instance.

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

Note

TelemetryClient est thread sécurisé.

TrackEvent

Dans Application Insights, un événement personnalisé est un point de données que vous pouvez afficher dans Metrics Explorer sous la forme d’un nombre agrégé et dans la recherche de diagnostics en tant qu’occurrences individuelles. (Il n’est pas lié à MVC ou à d’autres « événements ».

Insérez des TrackEvent appels dans votre code pour compter différents événements. Par exemple, vous souhaiterez peut-être suivre la fréquence à laquelle les utilisateurs choisissent une fonctionnalité particulière. Vous pouvez également savoir à quelle fréquence ils atteignent certains objectifs ou font des types d’erreurs spécifiques.

Par exemple, dans une application de jeu, envoyez un événement chaque fois qu’un utilisateur gagne le jeu :

telemetry.TrackEvent("WinGame");

Événements personnalisés dans Log Analytics

La télémétrie est disponible dans le tableau de l’onglet customEventsJournaux Application Insights ou dans l’expérience d’utilisation. Les événements peuvent provenir de trackEvent(..) ou du plug-in Click Analytics Autocollection.

Si l’échantillonnage est en cours d’opération, la itemCount propriété affiche une valeur supérieure à 1. Par exemple, cela signifie que parmi 10 appels à itemCount==10, le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct d’événements personnalisés, utilisez du code tel que customEvents | summarize sum(itemCount).

Note

itemCount a une valeur minimale d’une ; l’enregistrement lui-même représente une entrée.

GetMetric

Pour savoir comment utiliser efficacement l’appel GetMetric() pour capturer des métriques préggrégées localement pour les applications .NET et .NET Core, consultez la collection de métriques personnalisées dans .NET et .NET Core.

TrackMetric

Note

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric n’est pas la méthode recommandée pour l’envoi de métriques. Les métriques doivent toujours être préagrégées sur une période avant d’être envoyées. Utilisez l’une des surcharges GetMetric(..) pour obtenir un objet métrique permettant d’accéder aux capacités de pré-agrégation du Kit de développement logiciel (SDK).

Si vous implémentez votre propre logique de préaggregation, vous pouvez utiliser la TrackMetric() méthode pour envoyer les agrégats résultants. Si votre application nécessite l’envoi d’un élément de télémétrie distinct à chaque occasion sans agrégation au fil du temps, vous avez probablement un cas d’usage pour la télémétrie des événements. Voir TelemetryClient.TrackEvent(Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Application Insights peut graphiquer des métriques qui ne sont pas attachées à des événements particuliers. Par exemple, vous pouvez surveiller une longueur de file d’attente à intervalles réguliers. Avec les métriques, les mesures individuelles sont moins intéressantes que les variations et les tendances, et les graphiques statistiques sont donc utiles.

Pour envoyer des métriques à Application Insights, vous pouvez utiliser l’API TrackMetric(..) . Il existe deux façons d’envoyer une métrique :

  • Valeur unique. Chaque fois que vous effectuez une mesure dans votre application, vous envoyez la valeur correspondante à Application Insights.

    Par exemple, supposons que vous disposez d’une métrique qui décrit le nombre d’éléments d’un conteneur. Pendant une période particulière, vous devez d’abord placer trois éléments dans le conteneur, puis supprimer deux éléments. En conséquence, vous devez appeler TrackMetric deux fois. Tout d’abord, vous devez passer la valeur 3 , puis passer la valeur -2. Application Insights stocke les deux valeurs pour vous.

  • Agrégation. Lorsque vous travaillez avec des métriques, chaque mesure unique est rarement intéressante. Au lieu de cela, un résumé de ce qui s’est passé pendant une période particulière est important. Un tel résumé est appelé agrégation.

    Dans l’exemple précédent, la somme de métriques d’agrégation pour cette période est 1 et le nombre de valeurs de métrique est 2. Lorsque vous utilisez l’approche d’agrégation, vous n’appelez TrackMetric qu’une seule fois par période et envoyez les valeurs d’agrégation. Nous vous recommandons cette approche, car elle peut réduire considérablement le coût et la surcharge des performances en envoyant moins de points de données à Application Insights, tout en collectant toutes les informations pertinentes.

Exemples de valeurs uniques

Pour envoyer une valeur de métrique unique :

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

Métriques personnalisées dans Log Analytics

Les données de télémétrie sont disponibles dans la customMetrics table dans Application Insights Analytics. Chaque ligne représente un appel à trackMetric(..) dans votre application.

  • valueSum: somme des mesures. Pour obtenir la valeur moyenne, divisez par valueCount.
  • valueCount: nombre de mesures qui ont été agrégées dans cet trackMetric(..) appel.

Note

valueCount a une valeur minimale d’une ; l’enregistrement lui-même représente une entrée.

Affichages de page

Dans une application d’appareil ou de page web, les données de télémétrie d’affichage de page sont envoyées par défaut lorsque chaque écran ou page est chargé. Toutefois, vous pouvez modifier la valeur par défaut pour suivre les affichages de page à plusieurs ou différents moments. Par exemple, dans une application qui affiche des onglets ou des volets, vous pouvez suivre une page chaque fois que l’utilisateur ouvre un nouveau volet.

Les données d’utilisateur et de session sont envoyées en tant que propriétés avec les affichages de page, de façon à ce que les graphiques d’utilisateur et de session soient actifs s’il existe une télémétrie de l’affichage de page.

Affichages de pages personnalisés

telemetry.TrackPageView("GameReviewPage");

Télémétrie de page dans Log Analytics

Dans Log Analytics, deux tables affichent les données des opérations de navigateur :

  • pageViews: contient des données sur l’URL et le titre de la page.
  • browserTimings: contient des données sur les performances du client, comme le temps nécessaire pour traiter les données entrantes.

Pour savoir combien de temps le navigateur prend pour traiter différentes pages :

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

Pour découvrir la popularité des différents navigateurs :

pageViews
| summarize count() by client_Browser

Pour associer des vues de pages à des appels AJAX, joindre à des dépendances :

pageViews
| join (dependencies) on operation_Id

TrackRequest

Le Kit de développement logiciel (SDK) serveur utilise TrackRequest pour journaliser les requêtes HTTP.

Vous pouvez également l’appeler vous-même si vous souhaitez simuler des requêtes dans un contexte où vous n’avez pas le module de service web en cours d’exécution.

La méthode recommandée pour envoyer des données de télémétrie de requête est l’endroit où la requête agit en tant que contexte d’opération.

Contexte d’opération

Vous pouvez mettre en corrélation des éléments de télémétrie ensemble en les associant au contexte d’opération. Le module de suivi des requêtes standard le fait pour les exceptions et d’autres événements envoyés pendant qu’une requête HTTP est en cours de traitement. Dans La recherche et l’analytique, vous pouvez facilement trouver tous les événements associés à la requête à l’aide de son ID d’opération.

Lorsque vous effectuez le suivi manuel des données de télémétrie, le moyen le plus simple de garantir la corrélation des données de télémétrie consiste à utiliser ce modèle :

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

En plus de définir un contexte d’opération, StartOperation crée un élément de télémétrie du type que vous spécifiez. Il envoie l’élément de télémétrie lorsque vous supprimez l’opération ou si vous appelez StopOperation explicitement. Si vous utilisez RequestTelemetry comme type de télémétrie, sa durée est définie sur l’intervalle chronométré entre le début et l’arrêt.

Les éléments de télémétrie signalés dans une étendue de l’opération deviennent « enfants » d’une telle opération. Les contextes d’opération peuvent être imbriqués.

Dans La recherche, le contexte d’opération est utilisé pour créer la liste Éléments associés .

Capture d’écran montrant la liste Éléments associés.

Pour plus d’informations sur le suivi des opérations personnalisées, consultez Suivi des opérations personnalisées avec le Kit de développement logiciel (SDK) .NET Application Insights.

Demandes dans Log Analytics

Dans Application Insights Analytics, les requêtes s’affichent dans la requests table.

Si l’échantillonnage est en cours d’opération, la itemCount propriété affiche une valeur supérieure à 1. Par exemple, cela signifie que parmi 10 appels à itemCount==10, le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct de requêtes et la durée moyenne segmentées par noms de requête, utilisez du code tel que :

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

Envoyer des exceptions à Application Insights :

Les rapports incluent les traces de pile.

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

Les kits SDK interceptent automatiquement de nombreuses exceptions. Vous n’avez donc pas toujours besoin d’appeler TrackException explicitement.

Exceptions dans Log Analytics

Dans Application Insights Analytics, les exceptions s’affichent dans la exceptions table.

Si l’échantillonnage est en cours d’opération, la itemCount propriété affiche une valeur supérieure à 1. Par exemple, cela signifie que parmi 10 appels à itemCount==10, le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct d’exceptions segmentées par type d’exception, utilisez du code tel que :

exceptions
| summarize sum(itemCount) by type

La plupart des informations importantes sur la pile sont déjà extraites dans des variables distinctes, mais vous pouvez extraire séparément la structure details pour en savoir plus. Étant donné que cette structure est dynamique, vous devez convertir le résultat en type attendu. Par exemple:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

Pour associer des exceptions à leurs demandes associées, utilisez une jointure :

exceptions
| join (requests) on operation_Id

TrackTrace

Utilisez TrackTrace pour diagnostiquer des problèmes en envoyant une « piste de navigation » à Application Insights. Vous pouvez envoyer des blocs de données de diagnostic et les inspecter dans La recherche de diagnostic.

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

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

Journaliser un événement de diagnostic, tel que l’entrée ou la sortie d’une méthode.

Paramètre Descriptif
message Données de diagnostic. Peut être beaucoup plus long qu’un nom.
properties Mappage de chaîne à chaîne. D’autres données sont utilisées pour filtrer les exceptions dans le portail. La valeur par défaut est vide.
severityLevel Valeurs prises en charge : SeverityLevel.ts.

Vous pouvez rechercher dans le contenu du message, mais contrairement aux valeurs de propriété, vous ne pouvez pas filtrer dessus.

La limite de taille sur message est beaucoup plus élevée que la limite sur les propriétés. Un avantage de TrackTrace est que vous pouvez intégrer des données relativement longues dans le message. Par exemple, vous pouvez encoder les données POST là-bas.

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

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

Dans la recherche, vous pouvez ensuite filtrer facilement tous les messages d’un niveau de gravité particulier lié à une base de données particulière.

Traces dans Log Analytics

Dans Application Insights Analytics, les appels vers TrackTrace s’affichent dans la traces table.

Si l’échantillonnage est en cours d’opération, la itemCount propriété affiche une valeur supérieure à 1. Par exemple, cela signifie que parmi 10 appels à itemCount==10, le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct d’appels de trace, utilisez du code tel que traces | summarize sum(itemCount).

TrackDependency

Utilisez l’appel TrackDependency pour suivre les temps de réponse et les taux de réussite des appels à un élément de code externe. Les résultats apparaissent dans les graphiques de dépendances dans le portail. L’extrait de code suivant doit être ajouté partout où un appel de dépendance est effectué.

Note

Pour .NET et .NET Core, vous pouvez également utiliser la TelemetryClient.StartOperation méthode (extension) qui remplit les DependencyTelemetry propriétés nécessaires pour la corrélation et d’autres propriétés comme l’heure de début et la durée. Vous n’avez donc pas besoin de créer un minuteur personnalisé comme avec les exemples suivants. Pour plus d’informations, consultez la section sur le suivi des dépendances sortantes dans Suivi des opérations personnalisées avec le Kit de développement logiciel (SDK) .NET Application Insights.

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

N’oubliez pas que les kits SDK de serveur incluent un module de dépendance qui découvre et suit automatiquement certains appels de dépendance, par exemple aux bases de données et aux API REST. Vous devez installer un agent sur votre serveur pour que le module fonctionne.

Vous utilisez cet appel si vous souhaitez suivre les appels que le suivi automatisé n’intercepte pas.

Pour désactiver le module de suivi des dépendances standard en C#, modifiez ApplicationInsights.config et supprimez la référence à DependencyCollector.DependencyTrackingTelemetryModule.

Dépendances dans Log Analytics

Dans Application Insights Analytics, trackDependency les appels s’affichent dans la dependencies table.

Si l’échantillonnage est en cours d’opération, la itemCount propriété affiche une valeur supérieure à 1. Par exemple, cela signifie que parmi 10 appels à itemCount==10, le processus d’échantillonnage n’en a transmis qu’un seul. Pour obtenir un nombre correct de dépendances segmentées par composant cible, utilisez du code tel que :

dependencies
| summarize sum(itemCount) by target

Pour associer des dépendances à leurs demandes associées, utilisez une jointure :

dependencies
| join (requests) on operation_Id

Vidage des données

Normalement, le SDK envoie des données à intervalles fixes, généralement 30 secondes, ou chaque fois que la mémoire tampon est pleine, ce qui représente généralement 500 éléments. Dans certains cas, vous souhaiterez peut-être vider la mémoire tampon. Par exemple, si vous utilisez le Kit de développement logiciel (SDK) dans une application qui s’arrête.

Lorsque vous utilisez Flush(), nous vous recommandons ce modèle :

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

Lorsque vous utilisez FlushAsync(), nous vous recommandons ce modèle :

await telemetryClient.FlushAsync()
// No need to sleep

Nous vous recommandons de toujours effectuer une vidange lors de l'arrêt de l'application pour garantir que la télémétrie n'est pas perdue.

Note

Passez en revue la configuration de l’autoflush : l’activation de l’autoflush dans votre web.config fichier peut entraîner une dégradation des performances dans les applications .NET instrumentées avec Application Insights. Lorsque la configuration autoflush est activée, chaque appel de méthode System.Diagnostics.Trace.Trace* entraîne l’envoi d’éléments de télémétrie individuels sous forme de requêtes web distinctes au service d’ingestion. Cela peut entraîner l’épuisement du réseau et du stockage sur vos serveurs web. Pour améliorer les performances, il est recommandé de désactiver l’autoflush et également, d’utiliser ServerTelemetryChannel, conçu pour une transmission de données de télémétrie plus efficace.

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

Utilisateurs authentifiés

Dans une application web, les utilisateurs sont identifiés par les cookies par défaut. Un utilisateur peut être compté plusieurs fois s’il accède à votre application à partir d’un autre ordinateur ou d’un navigateur, ou s’il supprime des cookies.

Si les utilisateurs se connectent à votre application, vous pouvez obtenir un nombre plus précis en définissant l’ID d’utilisateur authentifié dans le code du navigateur. Il n’est pas nécessaire d’utiliser le nom de connexion réel de l’utilisateur. Il doit uniquement s’agir d’un ID unique à cet utilisateur. Il ne doit pas inclure d’espaces ou d’un des caractères ,;=|.

L’ID utilisateur est également défini dans un cookie de session et envoyé au serveur. Si le Kit de développement logiciel (SDK) du serveur est installé, l’ID d’utilisateur authentifié est envoyé dans le cadre des propriétés de contexte des données de télémétrie client et serveur. Vous pouvez ensuite filtrer et rechercher dessus.

Si votre application regroupe des utilisateurs dans des comptes, vous pouvez également transmettre un identificateur pour le compte. Les mêmes restrictions de caractères s’appliquent.

Dans Metrics Explorer, vous pouvez créer un graphique qui compte utilisateurs, authentifiés et comptes d’utilisateur.

Vous pouvez également rechercher des points de données client avec des noms d’utilisateur et des comptes spécifiques.

Note

La propriété EnableAuthenticationTrackingJavaScript dans la classe ApplicationInsightsServiceOptions dans le Kit de développement logiciel (SDK) .NET Core simplifie la configuration JavaScript nécessaire pour injecter le nom d’utilisateur comme ID d’authentification pour chaque trace envoyée par le Kit de développement logiciel (SDK) JavaScript Application Insights.

Lorsque cette propriété est définie sur true, le nom d'utilisateur de l'utilisateur dans ASP.NET Core est imprimé avec les données de télémétrie côté client. Pour cette raison, l’ajout appInsights.setAuthenticatedUserContext manuel n’est plus nécessaire, car il est déjà injecté par le Kit de développement logiciel (SDK) pour ASP.NET Core. L’ID d’authentification est également envoyé au serveur où le Kit de développement logiciel (SDK) dans .NET Core identifie et l’utilise pour toutes les données de télémétrie côté serveur, comme décrit dans la référence de l’API JavaScript.

Pour les applications JavaScript qui ne fonctionnent pas de la même façon que ASP.NET Core MVC, comme les applications web SPA, vous devez toujours ajouter appInsights.setAuthenticatedUserContext manuellement.

Filtrer, rechercher et segmenter vos données à l’aide de propriétés

Vous pouvez attacher des propriétés et des mesures à vos événements, métriques, vues de page, exceptions et autres données de télémétrie.

Les propriétés sont des valeurs de chaîne que vous pouvez utiliser pour filtrer vos données de télémétrie dans les rapports d’utilisation. Par exemple, si votre application fournit plusieurs jeux, vous pouvez attacher le nom du jeu à chaque événement afin de voir quels jeux sont plus populaires.

Il existe une limite de 8 192 sur la longueur de chaîne. Si vous souhaitez envoyer des blocs de données volumineux, utilisez le paramètre de message de TrackTrace.

Les métriques sont des valeurs numériques qui peuvent être présentées graphiquement. Par exemple, vous souhaiterez peut-être voir s’il existe une augmentation progressive des scores obtenus par vos joueurs. Les graphiques peuvent être segmentés par les propriétés envoyées avec l’événement afin que vous puissiez obtenir des graphiques distincts ou empilés pour différents jeux.

Les valeurs de métrique doivent être supérieures ou égales à 0 pour s’afficher correctement.

Il existe certaines limites sur le nombre de propriétés, de valeurs de propriété et de métriques que vous pouvez utiliser.

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

Important

Veillez à ne pas enregistrer les informations d’identification personnelle dans les propriétés.

Alternative pour définir des propriétés et des métriques

S’il est plus pratique, vous pouvez collecter les paramètres d’un événement dans un objet distinct :

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

Avertissement

Ne réutilisez pas la même instance d’élément de télémétrie (event dans cet exemple) pour appeler Track*() plusieurs fois. Cette pratique peut entraîner l’envoi de données de télémétrie avec une configuration incorrecte.

Mesures et propriétés personnalisées dans Log Analytics

Dans Log Analytics, les métriques et propriétés personnalisées s’affichent dans les attributs customMeasurements et customDimensions de chaque enregistrement de télémétrie.

Par exemple, si vous ajoutez une propriété nommée « game » à votre télémétrie de requête, cette requête compte les occurrences de différentes valeurs de « jeu » et affiche la moyenne de la métrique personnalisée « score » :

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

Notez que :

  • Lorsque vous extrayez une valeur à partir du JSON via customDimensions ou customMeasurements, elle a un type dynamique, vous devez donc la caster avec tostring ou todouble.
  • Pour tenir compte de la possibilité d’échantillonnage, n’utilisez sum(itemCount) pas count().

Événements de chronométrage

Parfois, vous souhaitez graphiquer le temps nécessaire à l’exécution d’une action. Par exemple, vous souhaiterez peut-être savoir combien de temps les utilisateurs prennent pour prendre en compte les choix dans un jeu. Pour obtenir ces informations, utilisez le paramètre de mesure.

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

Propriétés par défaut pour la télémétrie personnalisée

Si vous souhaitez définir des valeurs de propriété par défaut pour certains des événements personnalisés que vous écrivez, définissez-les dans une TelemetryClient instance. Ils sont attachés à chaque élément de télémétrie envoyé par ce client.

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

Les appels de télémétrie individuels peuvent remplacer les valeurs par défaut dans leurs dictionnaires de propriétés.

Pour ajouter des propriétés à toutes les données de télémétrie, y compris les données des modules de collecte standard, implémentez ITelemetryInitializer.

Désactiver la télémétrie

Pour arrêter et démarrer dynamiquement la collecte et la transmission des données de télémétrie :

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Mode développeur

Pendant le débogage, il est utile d'avoir votre télémétrie envoyée par le pipeline afin que vous puissiez voir immédiatement les résultats. Vous obtenez également d’autres messages qui vous aident à suivre les problèmes de télémétrie. Désactivez-le en production, car il peut ralentir votre application.

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Définir la clé d’instrumentation pour les données de télémétrie personnalisées sélectionnées

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

Chaîne de connexion dynamique

Pour éviter de mélanger les données de télémétrie des environnements de développement, de test et de production, vous pouvez créer des ressources Application Insights distinctes et modifier leurs clés, en fonction de l’environnement.

Au lieu d’obtenir la clé d’instrumentation à partir du fichier de configuration, vous pouvez la définir dans votre code. Définissez la clé dans une méthode d’initialisation, par global.aspx.cs exemple dans un service ASP.NET :

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

TelemetryContext

TelemetryClient a une propriété Context, qui contient des valeurs qui sont envoyées avec toutes les données de télémétrie. Ils sont normalement définis par les modules de télémétrie standard, mais vous pouvez également les définir vous-même. Par exemple:

telemetry.Context.Operation.Name = "MyOperationName";

Si vous définissez vous-même l’une de ces valeurs, envisagez de supprimer la ligne pertinente de ApplicationInsights.config afin que vos valeurs et les valeurs standard ne soient pas confondues.

  • Composant : l’application et sa version.
  • Appareil : données sur l’appareil sur lequel l’application est en cours d’exécution. Dans les applications web, il s’agit du serveur ou de l’appareil client à partir duquel les données de télémétrie sont envoyées.
  • InstrumentationKey : ressource Application Insights dans Azure où les données de télémétrie s’affichent. Il est généralement récupéré à partir de ApplicationInsights.config.
  • Emplacement : emplacement géographique de l’appareil.
  • Opération : dans les applications web, la requête HTTP actuelle. Dans d’autres types d’applications, vous pouvez définir cette valeur pour regrouper les événements.
    • ID : valeur générée qui met en corrélation différents événements de sorte que lorsque vous inspectez un événement dans la Recherche de diagnostic, vous pouvez trouver des éléments connexes.
    • Nom : identificateur, généralement l’URL de la requête HTTP.
    • SyntheticSource : s’il n’est pas null ou vide, chaîne qui indique que la source de la requête a été identifiée comme un robot ou un test web. Par défaut, il est exclu des calculs dans Metrics Explorer.
  • Session : session de l’utilisateur. L’ID est défini sur une valeur générée, qui est modifiée lorsque l’utilisateur n’a pas été actif pendant un certain temps.
  • Utilisateur : informations utilisateur.

Limites

Il existe certaines limites au nombre de métriques et d’événements par application, c’est-à-dire, par clé d’instrumentation. Les limites varient selon le plan de tarification que vous choisissez.

Resource Limite par défaut Limite maximale Remarques
Total des données par jour 100 Go Contactez le support technique. Vous pouvez définir une limite pour réduire les données. Si vous avez besoin de davantage de données, vous pouvez augmenter la limite dans le portail, jusqu’à 1 000 Go. Pour une capacité supérieure à 1 000 Go, envoyez un e-mail à AIDataCap@microsoft.com.
Throttling 32 000 événements/seconde Contactez le support technique. La limite est mesurée par minute.
Journaux de conservation des données 30 à 730 jours 730 jours Cette ressource est destiné aux journaux.
Métriques de conservation des données 90 jours 90 jours Cette ressource est destinée à Metrics Explorer.
Conservation des résultats détaillés du test de disponibilité à plusieurs étapes 90 jours 90 jours Cette ressource fournit des résultats détaillés de chaque étape.
Taille maximale des éléments de télémétrie 64 Ko 64 Ko
Nombre maximal d’éléments de télémétrie par lot 64 000 64 000
Longueur des noms de propriétés et de mesures 150 150 Consultez les schémas par type.
Longueur de chaîne de valeur de propriété 8,192 8,192 Consultez les schémas par type.
Longueur des messages de trace et d’exception 32,768 32,768 Consultez les schémas par type.
Nombre de tests de disponibilité par ressource Application Insights 100 100
Nombre de tests de disponibilité par groupe de ressources 800 800 Consultez Azure Resource Manager
Tests de disponibilité nombre maximal de redirections par test 10 10
Tests de disponibilité fréquence minimale des tests 300 secondes Les fréquences de test personnalisées ou les fréquences inférieures à 5 minutes nécessitent implémentations personnalisées de TrackAvailability .
Conservation des données du Profileur .NET et du Débogueur de capture instantanée Deux semaines Contactez le support technique. La limite maximale de conservation est de six mois.
Données du Profileur .NET envoyées par jour Aucune limite Aucune limite.
Données du Débogueur de capture instantanée envoyées par jour 30 instantanés par jour par application monitorée Aucune limite. Le nombre d’instantanés collectés par application peut être modifié dans la configuration.

Pour plus d’informations sur la tarification et les quotas, consultez Facturation d’Application Insights.

Pour éviter d’atteindre la limite de débit de données, utilisez l’échantillonnage.

Pour déterminer la durée de conservation des données, consultez la conservation et la confidentialité des données.

Exemples d’applications

Application console .NET Core : utilisez cet exemple si vous utilisez une application console écrite dans .NET Core (2.0 ou version ultérieure) ou .NET Framework (4.7.2 ou version ultérieure).

ASP.NET Core tâches d'arrière-plan avec HostedServices : Utilisez cet exemple si vous êtes dans ASP.NET Core et que vous créez des tâches d'arrière-plan conformément aux conseils officiels.

Service Worker .NET Core : Utilisez cet exemple si vous disposez d’une application Service Worker .NET conformément aux instructions officielles.

Résolution des problèmes

Consultez l’article sur la résolution des problèmes dédié.

Tester la connectivité entre votre hôte d’application et le service d’ingestion

Les SDK et les agents d'Application Insights envoient de la télémétrie pour être incorporée sous forme d'appels REST à nos points de terminaison d'ingestion. Vous pouvez tester la connectivité de votre serveur web ou de votre machine hôte d’application vers les points de terminaison de service d’ingestion en utilisant des clients du Representational State Transfer (REST) bruts à partir de commandes PowerShell ou curl. Consultez Résoudre les problèmes de télémétrie d’application manquante dans Azure Monitor Application Insights.

Kit de développement logiciel (SDK) open source

Lisez et contribuez au code.

Pour obtenir les mises à jour et correctifs de bogues les plus récents, consultez les notes de publication.

Notes de publication

Pour les versions 2.12 et ultérieures : Kits de développement logiciel (SDK), y compris ASP.NET, ASP.NET Core et adaptateurs de journalisation

Nos Mises à jour de service résument également les principales améliorations apportées à Application Insights.

Étapes suivantes

Documents de référence

  • Last updated on