Application Insights pour applications ASP.NET Core

Cet article décrit comment activer et configurer Application Insights pour une application ASP.NET Core.

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 la section Activer Azure Monitor OpenTelemetry pour les applications .NET, Node.js, Python et Java.

Application Insights peut collecter les données de télémétrie suivantes à partir de votre application ASP.NET Core :

• Demandes
• Les dépendances
• Exceptions
• Compteurs de performance
• Pulsations
• Journaux d’activité

Nous allons utiliser ici un exemple d’application MVC. Si vous utilisez le service Worker, suivez les instructions fournies dans Application Insights pour les applications de service Worker.

Une offre .NET basée sur OpenTelemetry est disponible. Pour plus d’informations, consultez Présentation d’OpenTelemetry.

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.

Notes

Si vous souhaitez utiliser un fournisseur ILogger autonome, utilisez Microsoft.Extensions.Logging.ApplicationInsight.

Scénarios pris en charge

Le SDK Application Insights pour ASP.NET Core peut surveiller vos applications peu importe où et 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. La surveillance d’Application Insights est prise en charge partout où .NET Core est pris en charge et couvre les scénarios suivants :

• Système d’exploitation : Windows, Linux ou Mac
• Méthode d’hébergement : dans le processus ou en dehors du processus
• Méthode de déploiement : dépendante de l’infrastructure ou autonome
• Serveur web : Internet Information Server (IIS) ou Kestrel
• Plateforme d’hébergement : Fonctionnalité Web Apps d’Azure App Service, de Machines virtuelles Azure, de Docker, d’Azure Kubernetes Service (AKS)
• Version .NET : toutes les versions .NET officiellement prises en charge qui ne sont pas en préversion
• IDE : Visual Studio, Visual Studio Code ou ligne de commande

Prérequis

Ce dont vous avez besoin :

• Application ASP.NET Core fonctionnelle. Si vous avez besoin créer une application ASP.NET Core, suivez ce didacticiel ASP.NET Core.
• Référence à une version prise en charge du package NuGet Application Insights.
• Une chaîne de connexion Application Insights valide. Cette chaîne est requise pour envoyer les données de télémétrie à Application Insights. Si vous avez besoin créer une ressource Application Insights pour obtenir une chaîne de connexion, consultez Créer une ressource Application Insights.

Activer les données de télémétrie Application Insights côté serveur (Visual Studio)

Pour Visual Studio pour Mac, utilisez l’aide du manuel. Seule la version Windows de Visual Studio prend en charge cette procédure.

1. Ouvrez votre projet dans Visual Studio.

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

3. Sélectionnez Azure Application Insights>Suivant.

4. Choisissez votre abonnement et votre instance Application Insights. Vous pouvez également créer une instance avec l’option Créer nouveau. Sélectionnez Suivant.

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

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

   

Activer les données de télémétrie Application Insights côté serveur (hors Visual Studio)

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

   Nous vous recommandons de toujours utiliser la dernière version stable. Recherchez les notes de publication complètes pour le SDK sur le référentiel GitHub open source.

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

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

2. Ajoutez AddApplicationInsightsTelemetry() à votre classe startup.cs ou program.cs. Le choix dépend de votre version de .NET Core.

   ASP.NET Core 6 et versions ultérieures

   Ajoutez builder.Services.AddApplicationInsightsTelemetry(); à la méthode WebApplication.CreateBuilder() dans la classe Program, comme dans cet exemple :

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

   ASP.NET Core 5 et versions antérieures

   Ajoutez services.AddApplicationInsightsTelemetry(); à la méthode ConfigureServices() dans la classe Startup, comme dans cet exemple :

   // This method gets called by the runtime. Use this method to add services to the container.
   public void ConfigureServices(IServiceCollection services)
   {
       // The following line enables Application Insights telemetry collection.
       services.AddApplicationInsightsTelemetry();
   
       // This code adds other services for your application.
       services.AddMvc();
   }
   

   Notes

   Cette version .NET n’est plus prise en charge.

3. Définissez la chaîne de connexion.

   Bien que vous puissiez fournir une chaîne de connexion dans le cadre de l’argument ApplicationInsightsServiceOptions à AddApplicationInsightsTelemetry, nous vous recommandons de la spécifier dans la configuration. L’exemple de code suivant montre comment spécifier une chaîne de connexion dans appsettings.json. Assurez-vous que appsettings.json est copié dans le dossier racine de l’application lors de la publication.

   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*",
     "ApplicationInsights": {
       "ConnectionString": "Copy connection string from Application Insights Resource Overview"
     }
   }
   

   Vous pouvez aussi spécifier la chaîne de connexion dans la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING ou dans ApplicationInsights:ConnectionString dans le fichier de configuration JSON.

   Par exemple :

   • SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
   • SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
   • En règle générale, vous utilisez APPLICATIONINSIGHTS_CONNECTION_STRING dans Web Apps. Vous pouvez également l’utiliser partout où ce SDK est pris en charge.

   Notes

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

Secrets d’utilisateur et autres fournisseurs de configuration

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

Dans Microsoft.ApplicationInsights.AspNetCore version 2.15.0 et ultérieure, l’appel à services.AddApplicationInsightsTelemetry() permet de lire automatiquement la chaîne de connexion à partir de Microsoft.Extensions.Configuration.IConfiguration dans l’application. Il n’est pas nécessaire de fournir explicitement IConfiguration.

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

Exécuter votre application

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.

Métriques temps réel

Les métriques temps réel peuvent être utilisées pour vérifier rapidement si la supervision Application Insights est correctement configurée. L’affichage et l’analyse des données de télémétrie dans le portail peuvent prendre quelques minutes, mais les métriques en temps réel indiquent l’utilisation du processeur par le processus en temps quasi-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.

Journaux ILogger

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

Les dépendances

La collecte des dépendances est activée par défaut. L’article Suivi des dépendances dans Application Insights explique les dépendances automatiquement collectées et contient également les étapes à effectuer pour un suivi manuel.

Compteurs de performance

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

• La version 2.4.1 et les versions ultérieures du SDK collectent les compteurs de performances si l’application est exécutée dans Web Apps (Windows).
• Les versions 2.7.1 et ultérieures du kit SDK collectent les compteurs de performances si l’application s’exécute dans Windows et cible netstandard2.0 ou version ultérieure.
• Pour les applications ciblant .NET Framework, toutes les versions du SDK prennent en charge les compteurs de performances.
• Les versions 2.8.0 et ultérieures du SDK prennent en charge le compteur processeur/mémoire dans Linux. Aucun autre compteur n’est pris en charge dans Linux. Pour obtenir les compteurs système dans Linux et dans d’autres environnements non-Windows, utilisez EventCounters.

EventCounter

Par défaut, EventCounterCollectionModule est activé. Pour savoir comment configurer la liste des compteurs à collecter, consultez Présentation d’EventCounters.

Enrichir des données via HTTP

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

Activer les données de télémétrie côté client pour les applications web

Les étapes précédentes sont suffisantes pour commencer à collecter des données de télémétrie côté serveur. Si votre application comporte des composants côté client, effectuez les étapes suivantes pour commencer à collecter les données de télémétrie d’utilisation à l’aide dune injection de script de chargement du SDK JavaScript (Web) par configuration.

1. Dans _ViewImports.cshtml, ajoutez l’injection :

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

2. Dans _Layout.cshtml, insérez HtmlHelper à la fin de la section <head>, mais avant tout autre script. Si vous souhaitez signaler les données de télémétrie JavaScript personnalisées à partir de la page, injectez-la par après cet extrait de code :

   @Html.Raw(JavaScriptSnippet.FullScript)
   </head>
   

Alternativement à l’utilisation de FullScript, ScriptBody est disponible à partir du SDK Application Insights pour ASP.NET Core version 2.14. Utilisez ScriptBody si vous devez contrôler la balise <script> pour définir une stratégie de sécurité de contenu :

<script> // apply custom changes to this script tag.
 @Html.Raw(JavaScriptSnippet.ScriptBody)
</script>

Les noms de fichier .cshtml mentionnés précédemment proviennent d’un modèle d’application MVC par défaut. Enfin, si vous souhaitez activer en bonne et due forme le monitoring côté client pour votre application, le Script de chargement du SDK JavaScript (Web) doit figurer dans la section <head> de chaque page de l’application que vous souhaitez surveiller. Ajoutez le Script de chargement du SDK JavaScript (Web) à _Layout.cshtml dans un modèle d’application pour activer le monitoring côté client.

Si votre projet ne comporte pas _Layout.cshtml, vous pouvez toujours ajouter le monitoring côté client en intégrant le Script de chargement du SDK JavaScript (Web) à un fichier équivalent qui contrôle la section <head> de toutes les pages de votre application. Vous pouvez également ajouter le Script de chargement du SDK JavaScript (Web) à plusieurs pages, mais nous le déconseillons.

Notes

L’injection JavaScript fournit une expérience de configuration par défaut. Si vous avez besoin d’une configuration qui va au-delà de la définition de la chaîne de connexion, vous devez supprimer l’injection automatique comme indiqué et ajouter manuellement le SDK JavaScript.

Configurer le SDK Application Insights

Vous pouvez personnaliser le SDK Application Insights pour ASP.NET Core afin de modifier la configuration par défaut. Les utilisateurs du SDK Application Insights ASP.NET peuvent maîtriser la modification de configuration à l’aide de ApplicationInsights.config ou en modifiant TelemetryConfiguration.Active. Pour ASP.NET Core, apportez presque toutes les modifications de configuration dans la méthode ConfigureServices() de votre classe Startup.cs, sauf instruction contraire. Pour plus d’informations, consultez les sections suivantes.

Notes

Dans les applications ASP.NET Core, car la modification de la configuration en altérant TelemetryConfiguration.Active n’est pas prise en charge.

Utiliser ApplicationInsightsServiceOptions

Vous pouvez modifier quelques paramètres courants en passant de ApplicationInsightsServiceOptions à AddApplicationInsightsTelemetry, comme dans cet exemple :

ASP.NET Core 6 et versions ultérieures

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables QuickPulse (Live Metrics stream).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

ASP.NET Core 5 et versions antérieures

public void ConfigureServices(IServiceCollection services)
{
    Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions aiOptions
                = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

    // Disables QuickPulse (Live Metrics stream).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetry(aiOptions);
}

Notes

Cette version .NET n’est plus prise en charge.

Cette table comprend la liste complète des paramètres ApplicationInsightsServiceOptions :

Paramètre	Description	Default
EnablePerformanceCounterCollectionModule	Active/désactive PerformanceCounterCollectionModule.	True
EnableRequestTrackingTelemetryModule	Active/désactive RequestTrackingTelemetryModule.	True
EnableEventCounterCollectionModule	Active/désactive EventCounterCollectionModule.	True
EnableDependencyTrackingTelemetryModule	Active/désactive DependencyTrackingTelemetryModule.	True
EnableAppServicesHeartbeatTelemetryModule	Active/désactive AppServicesHeartbeatTelemetryModule.	True
EnableAzureInstanceMetadataTelemetryModule	Active/désactive AzureInstanceMetadataTelemetryModule.	True
EnableQuickPulseMetricStream	Active/désactive la fonctionnalité LiveMetrics.	True
EnableAdaptiveSampling	Active/désactive l’échantillonnage adaptatif.	True
EnableHeartbeat	Active/désactive la fonctionnalité des pulsations. Il envoie régulièrement (toutes les 15 minutes par défaut) une métrique personnalisée nommée HeartbeatState avec des informations sur le runtime comme la version .NET et des détails sur l’environnement Azure, le cas échéant.	True
AddAutoCollectedMetricExtractor	Active/désactive AutoCollectedMetrics extractor. Ce processeur de télémétrie envoie des métriques préagrégées relatives aux requêtes/dépendances avant l’échantillonnage.	True
RequestCollectionOptions.TrackExceptions	Active/désactive la création de rapports de suivi des exceptions non gérées par le module de collecte des requêtes.	False dans netstandard2.0 (car les exceptions sont suivies avec ApplicationInsightsLoggerProvider). True sinon.
EnableDiagnosticsTelemetryModule	Active/désactive DiagnosticsTelemetryModule. Si l’élément est désactivé, les paramètres suivants sont ignorés : EnableHeartbeat, EnableAzureInstanceMetadataTelemetryModule et EnableAppServicesHeartbeatTelemetryModule.	True

Pour obtenir la liste la plus à jour, consultez les paramètres configurables dans ApplicationInsightsServiceOptions.

Recommandation de configuration pour le kit de développement logiciel (SDK) Microsoft.ApplicationInsights.AspNetCore 2.15.0 et versions ultérieures

Dans le SDK Microsoft.ApplicationInsights.AspNetCore 2.15.0 et versions ultérieures, configurez tous les paramètres disponibles dans ApplicationInsightsServiceOptions, y compris ConnectionString. Utilisez l’instance IConfiguration de l’application. Les paramètres doivent se trouver sous la section ApplicationInsights, comme indiqué dans l’exemple suivant. La section suivante extraite du fichier appsettings.json configure la chaîne de connexion et désactive l’échantillonnage adaptatif et la collecte des compteurs de performances.

{
    "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

Si vous utilisez builder.Services.AddApplicationInsightsTelemetry(aiOptions), pour ASP.NET Core 6.0 ou services.AddApplicationInsightsTelemetry(aiOptions) pour ASP.NET Core 3.1 et versions antérieures, il remplace les paramètres de Microsoft.Extensions.Configuration.IConfiguration.

échantillonnage

Le SDK Application Insights pour ASP.NET Core prend en charge l’échantillonnage à taux fixe et adaptatif. Par défaut, l’échantillonnage adaptatif est activé.

Pour plus d'informations, voir la configuration de l’échantillonnage adaptatif pour les applications ASP.NET Core.

Ajouter des TelemetryInitializers

Quand vous voulez enrichir les données de télémétrie avec d’autres informations, utilisez des initialiseurs de télémétrie.

Ajoutez un nouvel élément TelemetryInitializer au conteneur DependencyInjection, comme indiqué dans le code suivant. Le SDK ne repère automatiquement tous les éléments TelemetryInitializer qui sont ajoutés au conteneur DependencyInjection.

ASP.NET Core 6 et versions ultérieures

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

Notes

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); fonctionne pour les initialiseurs simples. Pour les autres, builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); est nécessaire.

ASP.NET Core 5 et versions antérieures

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
}

Notes

services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); fonctionne pour les initialiseurs simples. Pour les autres, services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); est nécessaire. Cette version .NET n’est plus prise en charge.

Supprimer des TelemetryInitializers

Par défaut, les initialiseurs de télémétrie sont présents. Pour supprimer tout ou partie des initialiseurs de télémétrie, utilisez l’exemple de code suivant après avoir appelé AddApplicationInsightsTelemetry().

ASP.NET Core 6 et versions ultérieures

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

// Remove all initializers
// This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.RemoveAll(typeof(ITelemetryInitializer));

var app = builder.Build();

ASP.NET Core 5 et versions antérieures

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();

    // Remove a specific built-in telemetry initializer
    var tiToRemove = services.FirstOrDefault<ServiceDescriptor>
                        (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
    if (tiToRemove != null)
    {
        services.Remove(tiToRemove);
    }

    // Remove all initializers
    // This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
    services.RemoveAll(typeof(ITelemetryInitializer));
}

Notes

Cette version .NET n’est plus prise en charge.

Ajouter processeurs de télémétrie

Vous pouvez ajouter des processeurs de télémétrie personnalisés à TelemetryConfiguration à l’aide de la méthode d’extension AddApplicationInsightsTelemetryProcessor sur IServiceCollection. Des processeurs de télémétrie sont utilisés dans les scénarios de filtrage avancés. Consultez l’exemple qui suit :

ASP.NET Core 6 et versions ultérieures

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

ASP.NET Core 5 et versions antérieures

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddApplicationInsightsTelemetry();
    services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

    // If you have more processors:
    services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();
}

Notes

Cette version .NET n’est plus prise en charge.

Configurer ou supprimer des TelemetryModules par défaut

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. Ces modules sont chargés de collecter automatiquement les données de télémétrie. Vous pouvez les désactiver ou les configurer pour modifier leur comportement par défaut.

• RequestTrackingTelemetryModule : Collecte RequestTelemetry à partir des requêtes web entrantes.
• DependencyTrackingTelemetryModule : Collecte DependencyTelemetry à partir des appels SQL et des appels HTTP sortants.
• PerformanceCollectorModule : Collecte les PerformanceCounters Windows.
• QuickPulseTelemetryModule : Collecte les données de télémétrie à afficher dans le portail Métriques en temps réel.
• AppServicesHeartbeatTelemetryModule : Collecte les pulsations (envoyées en tant que métriques personnalisées) relatives à l’environnement App Service où l’application est hébergée.
• AzureInstanceMetadataTelemetryModule : Collecte les pulsations (envoyées en tant que métriques personnalisées) relatives à l’environnement Azure VM où l’application est hébergée.
• EventCounterCollectionModule : Collecte les EventCounters. Ce module est une nouvelle fonctionnalité disponible dans le SDK 2.8.0 et ses versions ultérieures.

Pour configurer tout TelemetryModule par défaut, utilisez la méthode d’extension ConfigureTelemetryModule<T> sur IServiceCollection, comme illustré dans l’exemple suivant :

ASP.NET Core 6 et versions ultérieures

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

// The following removes PerformanceCollectorModule to disable perf-counter collection.
// Similarly, any other default modules can be removed.
var performanceCounterService = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

ASP.NET Core 5 et versions antérieures

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();

    // The following configures DependencyTrackingTelemetryModule.
    // Similarly, any other default modules can be configured.
    services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
            {
                module.EnableW3CHeadersInjection = true;
            });

    // The following removes all default counters from EventCounterCollectionModule, and adds a single one.
    services.ConfigureTelemetryModule<EventCounterCollectionModule>(
            (module, o) =>
            {
                module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
            }
        );

    // The following removes PerformanceCollectorModule to disable perf-counter collection.
    // Similarly, any other default modules can be removed.
    var performanceCounterService = services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
    if (performanceCounterService != null)
    {
        services.Remove(performanceCounterService);
    }
}

Notes

Cette version .NET n’est plus prise en charge.

Dans les versions 2.12.2 et ultérieures, ApplicationInsightsServiceOptions offre une option simple pour désactiver les modules par défaut.

Configurer un canal de télémétrie

Le canal de télémétrie par défaut est ServerTelemetryChannel. L'exemple suivant montre comment le substituer.

ASP.NET Core 6 et versions ultérieures

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

// Use the following to replace the default channel with InMemoryChannel.
// This can also be applied to ServerTelemetryChannel.
builder.Services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

ASP.NET Core 5 et versions antérieures

using Microsoft.ApplicationInsights.Channel;

public void ConfigureServices(IServiceCollection services)
{
    // Use the following to replace the default channel with InMemoryChannel.
    // This can also be applied to ServerTelemetryChannel.
    services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

    services.AddApplicationInsightsTelemetry();
}

Notes

Cette version .NET n’est plus prise en charge.

Notes

Si vous voulez vider la mémoire tampon, consultez Vidage des données. Par exemple, vous pouvez avoir besoin de vider la mémoire tampon si vous utilisez le SDK dans une application qui s’arrête.

Désactiver la télémétrie dynamiquement

Si vous souhaitez désactiver la télémétrie de manière conditionnelle et dynamique, vous pouvez résoudre l’instance TelemetryConfiguration avec un conteneur d’injection de dépendance ASP.NET n’importe où dans votre code et définir l’indicateur DisableTelemetry sur celle-ci.

ASP.NET Core 6 et versions ultérieures

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

ASP.NET Core 5 et versions antérieures

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
{
    configuration.DisableTelemetry = true;
    ...
}

Notes

Cette version .NET n’est plus prise en charge.

L’exemple de code précédent empêche l’envoi de données de télémétrie à Application Insights. Il n'empêche pas les modules de collecte automatique de collecter des données de télémétrie. Si vous voulez supprimer un module de collecte automatique particulier, consultez Supprimer le module de télémétrie.

Forum aux questions

Cette section fournit des réponses aux questions fréquentes.

Le service Application Insights prend-il en charge ASP.NET Core 3.1 ?

ASP.NET Core 3.1 n’est plus pris en charge par Microsoft.

Le Kit de développement logiciel (SDK) Application Insights pour ASP.NET Core version 2.8.0 et Visual Studio 2019 ou ultérieure peut être utilisé avec des applications ASP.NET Core 3.1.

Comment puis-je suivre les données de télémétrie qui ne sont pas automatiquement collectées ?

Obtenez une instance de TelemetryClient à l’aide de l’injection de constructeur et appelez la méthode TrackXXX() requise dessus. Nous ne recommandons pas de créer d’autres instances TelemetryClient ou TelemetryConfiguration dans une application ASP.NET Core. Une instance singleton de TelemetryClient est déjà inscrite dans le conteneur DependencyInjection, qui partage TelemetryConfiguration avec le reste de la télémétrie. Créez une instance TelemetryClient uniquement si celle-ci a besoin d’une configuration distincte du reste de la télémétrie.

L’exemple suivant montre comment suivre des données de télémétrie supplémentaires à partir d’un contrôleur.

using Microsoft.ApplicationInsights;

public class HomeController : Controller
{
    private TelemetryClient telemetry;

    // Use constructor injection to get a TelemetryClient instance.
    public HomeController(TelemetryClient telemetry)
    {
        this.telemetry = telemetry;
    }

    public IActionResult Index()
    {
        // Call the required TrackXXX method.
        this.telemetry.TrackEvent("HomePageRequested");
        return View();
    }

Pour plus d’informations sur la création de rapports personnalisés pour les données dans Application Insights, consultez la documentation de référence sur l’API des métriques personnalisées Application Insights. Une approche similaire peut être utilisée pour envoyer des mesures personnalisées à Application Insights à l’aide de l’API GetMetric.

Comment capturer le corps de la requête et de la réponse dans mes données de télémétrie ?

ASP.NET Core prend en charge la journalisation des informations de requête/réponse HTTP (y compris le corps) à l’aide de ILogger. Il est recommandé de tirer parti de cela. Cela peut potentiellement exposer des informations d’identification personnelle (PII) dans les données de télémétrie et entraîner une hausse significative des coûts (coûts de performances et facturation Application Insights), alors évaluez soigneusement les risques avant d’utiliser cela.

Comment personnaliser la collection de journaux ILogger ?

Le paramètre par défaut pour Application Insights consiste à capturer uniquement les journaux des avertissements et les journaux de gravité supérieure.

Capturez les journaux d’informations et les journaux dont le niveau de gravité est moins important en changeant la configuration de la journalisation pour le fournisseur Application Insights comme suit.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
  }
}

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

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

Pour plus d’informations, consultez Configuration d’ILogger.

Certains modèles Visual Studio utilisaient la méthode d’extension UseApplicationInsights() sur IWebHostBuilder pour activer Application Insights. Cette syntaxe est-elle toujours valide ?

La méthode d'extension UseApplicationInsights() est toujours prise en charge, mais elle est considérée comme obsolète dans la version 2.8.0 du kit de développement logiciel (SDK) Application Insights et versions ultérieures. Elle est supprimée dans la prochaine version principale du SDK. Pour activer les données de télémétrie Application Insights, utilisez AddApplicationInsightsTelemetry() car cette méthode fournit des surcharges permettant de contrôler certaines configurations. En outre, dans les applications ASP.NET Core 3.X, services.AddApplicationInsightsTelemetry() est le seul moyen d'activer Application Insights.

Je déploie mon application ASP.NET Core dans Web Apps. Dois-je toujours activer l’extension Application Insights à partir de Web Apps ?

Si le SDK est installé au moment de la génération, comme indiqué dans cet article, vous n’avez pas besoin activer l’extension Application Insights à partir du portail App Service. Si l’extension est installée, elle s’interrompt quand elle détecte que le SDK est déjà ajouté. Si vous activez Application Insights à partir de l’extension, il est inutile d’installer et de mettre à jour le SDK. Mais si vous activez Application Insights en suivant les instructions de cet article, vous bénéficiez de davantage de flexibilité pour plusieurs raisons :

• La télémétrie Application Insights continue à fonctionner dans :
  • sur tous les systèmes d’exploitation, notamment Windows, Linux et Mac ;
  • dans tous les modes de publication, notamment le mode autonome ou le mode dépendant de l’infrastructure ;
  • dans toutes les versions cibles de .Net Framework, y compris le .NET Framework complet ;
  • Toutes les options d’hébergement, notamment Web Apps, machines virtuelles, Linux, conteneurs, AKS et hébergement hors Azure.
  • Toutes les versions de .NET Core, y compris les préversions.
• Vous pouvez voir les données de télémétrie localement lorsque vous déboguez à partir de Visual Studio.
• Vous pouvez suivre des données de télémétrie personnalisées supplémentaires à l’aide de l’API TrackXXX().
• Vous avez le contrôle total de la configuration.

Puis-je activer la supervision d’Application Insights à l’aide d’outils tels qu’Azure Monitor Agent Application Insights (anciennement Status Monitor v2) ?

Oui. Dans l’agent Application Insights 2.0.0-beta1 et ultérieures, les applications ASP.NET Core hébergées dans IIS sont prises en charge.

Si j’exécute mon application sous Linux, toutes les fonctionnalités sont-elles prises en charge ?

Oui. La prise en charge de fonctionnalités pour le SDK est la même sur toutes les plateformes, avec les exceptions suivantes :

• Le kit SDK collecte les compteurs d’événements sur Linux, car les compteurs de performances ne sont pris en charge que dans Windows. La plupart des métriques sont identiques.

Ce kit de développement logiciel (SDK) est-il pris en charge pour les services Worker ?

Non. Utilisez Application Insights pour les applications de service Worker (applications non HTTP) pour les services Worker.

Comment puis-je désinstaller le Kit de développement logiciel (SDK) ?

Pour supprimer Application Insights, vous devez supprimer les packages NuGet et les références depuis l’API dans votre application. Vous pouvez désinstaller les packages NuGet à l’aide du gestionnaire de package NuGet dans Visual Studio.

Remarque

Ces instructions concernent la désinstallation du Kit de développement logiciel (SDK) ASP.NET Core. Si vous avez besoin de désinstaller le SDK ASP.NET, consultez Comment puis-je désinstaller le Kit de développement logiciel (SDK) ASP.NET ?.

1. Désinstallez le package Microsoft.ApplicationInsights.AspNetCore en utilisant le gestionnaire de package NuGet.
2. Pour supprimer complètement Application Insights, vérifiez et supprimez manuellement le code ou les fichiers ajoutés ainsi que tous les appels d’API que vous avez ajoutés dans votre projet. Pour plus d’informations, consultez Qu’est-ce qui est créé lorsque vous ajoutez le Kit de développement logiciel (SDK) Application Insights ?.

Qu’est-ce qui est créé lorsque vous ajoutez le Kit de développement logiciel (SDK) Application Insights ?

Lorsque vous ajoutez Application Insights à votre projet, il crée des fichiers et ajoute du code à certains de vos fichiers. La seule désinstallation des packages NuGet n’entraîne pas toujours l’abandon des fichiers et du code. Pour supprimer complètement Application Insights, vous devez vérifier et supprimer manuellement le code ou les fichiers ajoutés ainsi que tous les appels d’API que vous avez ajoutés dans votre projet.

Lorsque vous ajoutez Application Insights Telemetry à un projet de modèle Visual Studio ASP.NET Core, le code suivant est ajouté :

• [Nom de votre projet].csproj

    <PropertyGroup>
      <TargetFramework>netcoreapp3.1</TargetFramework>
      <ApplicationInsightsResourceId>/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/Default-ApplicationInsights-EastUS/providers/microsoft.insights/components/WebApplication4core</ApplicationInsightsResourceId>
    </PropertyGroup>
  
    <ItemGroup>
      <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.12.0" />
    </ItemGroup>
  
    <ItemGroup>
      <WCFMetadata Include="Connected Services" />
    </ItemGroup>
  

• Appsettings.json

  "ApplicationInsights": {
      "InstrumentationKey": "00000000-0000-0000-0000-000000000000"
  

• ConnectedService.json

  {
    "ProviderId": "Microsoft.ApplicationInsights.ConnectedService.ConnectedServiceProvider",
    "Version": "16.0.0.0",
    "GettingStartedDocument": {
      "Uri": "https://go.microsoft.com/fwlink/?LinkID=798432"
    }
  }
  

• Startup.cs

     public void ConfigureServices(IServiceCollection services)
          {
              services.AddRazorPages();
              services.AddApplicationInsightsTelemetry(); // This is added
          }
  

Résolution des problèmes

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

Les SDK et les agents Application Insights envoient de la télémétrie à ingérer en tant qu’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) .NET [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

• Explorez les flux d’utilisateurs pour comprendre comment les utilisateurs parcourent votre application.
• Configurez la collecte de captures instantanées pour voir l’état du code source et des variables au moment où une exception est levée.
• Utilisez l’API pour envoyer vos propres événements et mesures pour obtenir une vue détaillée des performances et de l’utilisation de votre application.
• Utilisez des tests de disponibilité pour vérifier votre application en permanence dans le monde entier.
• Découvrez-en plus sur l’injection de dépendances dans ASP.NET Core.