Configurer le kit de développement logiciel (SDK) Application Insights à l’aide du fichier ApplicationInsights.config ou .xml

  • Article

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.

Remarque

La documentation suivante s’appuie sur l’API classique d’Application Insights. Le plan à long terme pour Application Insights est de collecter des données en utilisant OpenTelemetry. Pour plus d’informations, consultez Activer Azure Monitor OpenTelemetry pour les applications .NET, Node.js, Python et Java.

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. Une fois compilé, il est copié dans le dossier Bin. Il est également ajouté à une application web par l’agent Application Insights sur un serveur IIS. Le fichier config est ignoré si l'extension pour les sites web Azure ou l'extension pour les machines virtuelles Azure et les groupes de machines virtuelles identiques est utilisée.

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

Cet article décrit les sections du fichier de configuration, la façon dont ils contrôlent les composants du Kit de développement logiciel (SDK) et les packages NuGet qui chargent ces composants.

Notes

Les instructions ApplicationInsights.config et .xml ne s’appliquent pas au Kit de développement logiciel (SDK) .NET Core. Pour configurer les applications ASP.NET Core, suivez les instructions de la section Application Insights pour applications ASP.NET Core.

Modules de télémétrie (ASP.NET)

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

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.

Suivi des dépendances

Dependency tracking collecte la télémétrie des appels de votre application aux bases de données et aux services et bases de données externes. Pour permettre à ce module de fonctionner dans un serveur IIS, vous devez installer l’agent Application Insights.

Vous pouvez également écrire votre propre code de suivi des dépendances à l'aide de l’API TrackDependency.

Les dépendances peuvent être collectées automatiquement, sans modification de votre code, à l’aide de la jonction (sans code) basée sur l'agent. Pour l’utiliser dans des applications web Azure, activez l’extension Application Insights. Pour l’utiliser dans une machine virtuelle Azure ou un groupe de machines virtuelles identiques Azure, activez l’extension Surveillance des applications pour machines virtuelles et groupes de machines virtuelles identiques.

Collecteur de performances

Le collecteur de performances collecte les compteurs de performances système, notamment l’UC, la mémoire et la charge réseau, à partir des installations IIS. Vous pouvez spécifier les compteurs à collecter, y compris les compteurs de performances que vous avez configurés vous-même.

Télémétrie des diagnostics Application Insights

La classe DiagnosticsTelemetryModule signale les erreurs dans le code d'instrumentation Application Insights lui-même. Par exemple, si le code ne peut pas accéder aux compteurs de performances ou si un ITelemetryInitializer renvoie une exception. La télémétrie de trace suivie par ce module s’affiche dans Recherche de diagnostic.

  • Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
  • Microsoft.ApplicationInsights . Si vous installez simplement ce package, le fichier ApplicationInsights.config n'est pas créé automatiquement.

Mode Développeur :

La classe DeveloperModeWithDebuggerAttachedTelemetryModule force Application Insights TelemetryChannel à envoyer des données immédiatement, un élément de télémétrie à la fois, lorsqu’un débogueur est associé au processus d'application. Ce design réduit le délai entre le moment où votre application effectue le suivi de télémétrie et celui où les données apparaissent sur le portail Application Insights. Cela cause une surcharge importante au niveau de l'UC et de la bande passante réseau.

Suivi des requêtes web

Le suivi des requêtes web indique le temps de réponse et le code résultant des requêtes HTTP.

Suivi des exceptions

La classe ExceptionTrackingTelemetryModule comptabilise le nombre d’exceptions non gérées dans votre application web. Pour plus d’informations, consultez Échecs et exceptions.

  • Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
  • Package NuGet Microsoft.ApplicationInsights.Web.
  • Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule : Effectue le suivi d’une tâche non traitée. Exceptions.
  • Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule : Effectue le suivi des exceptions non gérées pour les rôles de travail, les services Windows et les applications de console.
  • Application Insights Windows Server .

Suivi EventSource

La classe EventSourceTelemetryModule vous permet de configurer les événements EventSource à envoyer à Application Insights en tant que traces. Pour plus d’informations sur le suivi des événements EventSource, consultez Utilisation d’événements EventSource.

Suivi des événements ETW

La classe EtwCollectorTelemetryModule vous permet de configurer les événements provenant des fournisseurs ETW à envoyer à Application Insights en tant que traces. Pour plus d’informations sur le suivi des événements ETW, consultez Utilisation d’événements ETW.

Microsoft.ApplicationInsights

Le package Microsoft.ApplicationInsights fournit l’API principale du Kit de développement logiciel (SDK). Les autres modules de télémétrie utilisent cette API. Vous pouvez également l’utiliser pour définir votre propre télémétrie.

  • Aucune entrée dans ApplicationInsights.config.
  • Microsoft.ApplicationInsights . Si vous installez simplement ce package NuGet, aucun fichier .config n'est créé.

Canal de télémétrie

Le canal de télémétrie gère la mise en mémoire tampon et la transmission de la télémétrie au service Application Insights.

  • Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel est le canal par défaut des applications web. Il met les données en mémoire tampon, et emploie des mécanismes de nouvelle tentative et de stockage de disque local pour fournir des données de télémétrie plus fiables.
  • Microsoft.ApplicationInsights.InMemoryChannel est un canal de télémétrie léger. Il est utilisé si aucun autre canal n’est configuré.

Initialiseurs de télémétrie (ASP.NET)

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 les propriétés de contexte.

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

  • AccountIdTelemetryInitializer définit la propriété AccountId.

  • AuthenticatedUserIdTelemetryInitializer définit la propriété AuthenticatedUserId déterminée par le Kit de développement logiciel (SDK) JavaScript.

  • AzureRoleEnvironmentTelemetryInitializer met à jour les propriétés RoleName et RoleInstance du contexte Device pour tous les éléments de télémétrie avec des informations extraites de l'environnement d’exécution Azure.

  • BuildInfoConfigComponentVersionTelemetryInitializer met à jour la propriété Version du contexte Component pour tous les éléments de télémétrie avec la valeur extraite du fichier BuildInfo.config produit par MSBuild.

  • ClientIpHeaderTelemetryInitializer met à jour la propriété Ip du contexte Location de tous les éléments de télémétrie à partir de l’en-tête HTTP X-Forwarded-For de la demande.

  • 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 est exécutée.
    • OemName est défini sur la valeur extraite du champ Win32_ComputerSystem.Manufacturer à l'aide de WMI.
    • Model est défini sur la valeur extraite du champ Win32_ComputerSystem.Model à l'aide de 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 est exécutée.

  • 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 à partir de la méthode HTTP, ainsi que les noms du contrôleur ASP.NET MVC et de l’action appelée pour traiter la demande.

  • OperationIdTelemetryInitializer ou OperationCorrelationTelemetryInitializer met à jour la propriété de contexte Operation.Id de tous les éléments de télémétrie suivis lors du traitement d'une demande avec le RequestTelemetry.Id généré 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 la source de synthèse pour des requêtes HTTP provenant des tests de disponibilité. Ensemble de <Filters> qui identifie les propriétés des requêtes.

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.

Processeurs de télémétrie (ASP.NET)

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

Vous pouvez écrire vos propres processeurs de télémétrie.

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

ConnectionString

Consultez Exemples de code de chaîne de connexion.

InstrumentationKey

Notes

Le support de l’ingestion de clé d’instrumentation prendra fin le 31 mars 2025. L’ingestion de clé d’instrumentation continuera de fonctionner, mais nous ne fournirons plus de mises à jour ni de support pour la fonctionnalité. Passez aux chaînes de connexion pour tirer parti des nouvelles fonctionnalités.

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 clé distincte, pour chacune de vos applications.

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

Pour définir la clé 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.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        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.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

Pour obtenir une nouvelle clé, créez une ressource dans le portail Application Insights.

Fournisseur ApplicationId

Le fournisseur est disponible à partir de la version 2.6.0.

L’objectif de ce fournisseur est de rechercher un ID d’application à partir d’une clé d’instrumentation. 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 dans le code ou dans le fichier config.

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 limitera les requêtes et les résultats du cache.

Ce fournisseur est ajouté à votre fichier config lorsque vous installez Microsoft.ApplicationInsights.DependencyCollector ou Microsoft.ApplicationInsights.Web.

Cette classe possède une propriété facultative ProfileQueryEndpoint. https://dc.services.visualstudio.com/api/profiles/{0}/appId est sélectionné par défaut. Si vous avez besoin de configurer un proxy pour cette configuration, nous vous recommandons d’utiliser le proxy sur l’adresse de base et d’inclure "/api/profiles/{0}/appId". « {0} » est remplacé, lors de l’exécution par requête, par la clé d’instrumentation.

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 à l’aide 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 clé d’instrumentation 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 à l’aide du code

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

Configurer la collecte de captures instantanées pour les applications ASP.NET

Configurez une collecte de captures instantanées pour les applications ASP.NET.

Étapes suivantes

En savoir plus sur l’API