Activer Application Insights pour les applications ASP.NET Core

Cet article décrit comment activer Application Insights pour une application ASP.NET Core déployée comme Azure Web App. Cette implémentation utilise une approche basée sur un Kit de développement logiciel (SDK). Une approche par instrumentation automatique est également disponible.

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é

En guise d’exemple d’application, nous allons utiliser une application MVC ASP.NET Core ciblant net6.0. Toutefois, vous pouvez appliquer ces instructions à toutes les applications ASP.NET Core. Si vous utilisez le service Worker, suivez les instructions ici.

Notes

Une offre .NET basée sur OpenTelemetry est disponible. Plus d’informations

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.

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 à Azure, Application Insights peut collecter la télémétrie à partir de celui-ci. La surveillance Application Insights est prise en charge partout où .NET Core est pris en charge. Les scénarios suivants sont pris en charge :

• 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, machine virtuelle Azure, Docker, Azure Kubernetes Service (AKS), etc.
• Version de .NET Core : toutes les versions .NET Core officiellement prises en charge qui ne sont pas en préversion
• IDE : Visual Studio, Visual Studio Code ou ligne de commande

Prérequis

Pour suivre ce didacticiel, vous avez besoin des éléments suivants :

• Visual Studio 2022
• Charges de travail Visual Studio suivantes :
  • Développement web et ASP.NET
  • Traitement et stockage de données
  • Développement Azure
• .NET 6.0
• Abonnement et compte d’utilisateur Azure (avec possibilité de créer et de supprimer des ressources)

Déployer des ressources Azure

Suivez les instructions pour déployer l’exemple d’application à partir de son référentiel GitHub.

Pour fournir des noms globalement uniques aux ressources, un suffixe de six caractères est attribué à certaines d’entre elles. Notez ce suffixe pour une utilisation ultérieure dans cet article.

Création d’une ressource Application Insights dans Azure

1. Dans le portail Azure, sélectionnez le groupe de ressources application-insights-azure-cafe.

2. Dans le menu de la barre supérieure, sélectionnez +Créer.

   

3. Dans l’écran Créer une ressource, recherchez et sélectionnez Application Insights dans la zone de texte de recherche de la place de marché.

   

   Capture d’écran Créer une ressource dans le portail Azure. La capture d’écran montre une recherche pour Application Insights mise en évidence et Application Insights s’affichant dans les résultats de la recherche et mis en évidence également.

4. Dans l’écran Vue d’ensemble des ressources Application Insights, sélectionnez Créer.

   

5. Sur l’écran d’Application Insights, sous l’onglet Informations de base, remplissez le formulaire en utilisant le tableau suivant, puis sélectionnez le bouton Vérifier + créer. Les champs non spécifiés dans le tableau ci-dessous peuvent conserver leurs valeurs par défaut.

   Champ	Valeur
   Nom	Entrez azure-cafe-application-insights-{SUFFIX}, en remplaçant {SUFFIXEX} par la valeur du suffixe appropriée enregistrée précédemment.
   Région	Sélectionnez la même région que celle choisie lors du déploiement des ressources de l’article.
   Espace de travail Log Analytics	Sélectionnez azure-cafe-log-analytics-workspace. Vous pouvez également créer un espace de travail Log Analytics.

   

6. Une fois la validation passée, sélectionnez Créer pour déployer la ressource.

   

7. Une fois la ressource déployée, revenez au groupe de ressources application-insights-azure-cafe, puis sélectionnez la ressource Application Insights que vous avez déployée.

   

8. Sur l’écran Vue d’ensemble de la ressource Application Insights, sélectionnez le bouton Copier dans le Presse-papiers pour copier la valeur de la chaîne de connexion. Vous allez utiliser la valeur de la chaîne de connexion dans la section suivante de cet article.

   

   Capture de l’écran Vue d’ensemble d’Application Insights dans le portail Azure. La capture d’écran montre la valeur de chaîne de connexion mise en évidence et le bouton Copier dans le Presse-papiers sélectionné et mis en évidence.

Configurer le paramètre d’application de la chaîne de connexion Application Insights dans Web App Service

1. Revenez au groupe de ressources application-insights-azure-cafe et ouvrez la ressource App Service azure-cafe-web-{SUFFIXE}.

   

2. Dans le menu de gauche, sous la section Paramètres, sélectionnez Configuration. Ensuite, dans l’onglet Paramètres de l’application, sélectionnez +Nouveau paramètre d’application sous l’en-tête Paramètres de l’application.

   

   Capture de l’écran de ressource App Service dans le portail Azure. La capture d’écran montre l’option sélectionnée et mise en évidence Configuration dans le menu de gauche sous la section Paramètres, l’onglet Paramètres de l’application sélectionné et mis en évidence, et le bouton de barre d’outils + Nouveau paramètre d’application mis en évidence.

3. Dans le panneau Ajouter/Modifier le paramètre d’application, complétez le formulaire comme suit et sélectionnez OK.

   Champ	Valeur
   Nom	APPLICATIONINSIGHTS_CONNECTION_STRING
   Valeur	Collez la valeur de la chaîne de connexion Application Insights que vous avez copiée dans la section précédente.

   

4. Dans l’écran configuration App Service, sélectionnez le bouton Enregistrer dans le menu de la barre d’outils. Lorsque vous êtes invité à enregistrer les modifications, sélectionnez Continuer.

   

Installer le package NuGet Application Insights

Nous devons configurer l’application web MVC ASP.NET Core pour envoyer les données de télémétrie. Cela s’effectue à l’aide du package NuGet des applications web Application Insights pour ASP.NET Core.

1. Dans Visual Studio, ouvrez 1 - Starter Application\src\AzureCafe.sln.

2. Dans le volet de l’Explorateur de solutions de Visual Studio, cliquez avec le bouton droit sur le projet AzureCafe, puis sélectionnez Gérer les packages NuGet.

   

3. Sélectionnez l’onglet Parcourir, puis recherchez et choisissez Microsoft.ApplicationInsights.AspNetCore. Sélectionnez Installer et acceptez les conditions de la licence. Il est recommandé d’utiliser la dernière version stable. Pour les notes de publication complètes du Kit de développement logiciel (SDK), consultez le dépôt GitHub open-source.

   

   Capture d’écran montrant l’interface utilisateur du Gestionnaire de package NuGet dans Visual Studio avec l’onglet Parcourir sélectionné. Microsoft.ApplicationInsights.AspNetCore est entré dans la zone de recherche et le package Microsoft.ApplicationInsights.AspNetCore est sélectionné dans une liste de résultats. Dans le volet droit, la dernière version stable du package Microsoft.ApplicationInsights.AspNetCore est sélectionnée dans une liste déroulante et le bouton Installer est mis en évidence.

   Laissez Visual Studio ouvert pour la section suivante de l’article.

Activer les données de télémétrie Application Insights côté serveur

Le package NuGet d’applications web Application Insights pour ASP.NET Core encapsule certaines fonctionnalités permettant d’envoyer des données de télémétrie côté serveur à la ressource Application Insights dans Azure.

1. Dans l’Explorateur de solutions de Visual Studio, ouvrez le fichier Program.cs.

   

2. Insérez le code suivant avant l’instruction builder.Services.AddControllersWithViews(). Ce code lit automatiquement la valeur de la chaîne de connexion Application Insights à partir de la configuration. La méthode AddApplicationInsightsTelemetry inscrit le ApplicationInsightsLoggerProvider auprès du conteneur d’injection de dépendances intégré qui sera ensuite utilisé pour répondre aux demandes d’implémentation ILogger et ILogger<TCategoryName>.

   builder.Services.AddApplicationInsightsTelemetry();
   

   

   Conseil

   Apprenez-en davantage sur les options de configuration dans ASP.NET Core.

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. L’exemple d’application a des composants côté client. Pour commencer à collecter la télémétrie de l’utilisation, procédez comme suit.

1. Dans l’Explorateur de solutions de Visual Studio, ouvrez \Views\_ViewImports.cshtml.

2. À la fin du fichier existant, ajoutez le code suivant.

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

   

3. Pour activer correctement la surveillance de votre application côté client, dans l’Explorateur de solutions de Visual Studio, ouvrez \Views\Shared\_Layout.cshtml et insérez le code suivant juste devant la balise <\head> fermante. Cet extrait de JavaScript doit être inséré dans la section <head> de chaque page de votre application que vous souhaitez surveiller.

   @Html.Raw(JavaScriptSnippet.FullScript)
   

   

   Conseil

   Une alternative à l’utilisation de FullScript est ScriptBody. 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>
   

Notes

L’injection JavaScript fournit une expérience de configuration par défaut. Si vous avez besoin d’une configuration en plus de la chaîne de connexion, vous devez supprimer l’injection automatique comme décrit ci-dessus et ajouter manuellement le kit de développement logiciel (SDK) JavaScript.

Activer la surveillance des requêtes de base de données

Lors de l’examen des causes de la dégradation des performances, il est important d’inclure des insights sur les appels de base de données. Vous activez la surveillance en configurant le module de dépendance. La surveillance de la dépendance, y compris SQL, est activée par défaut.

Pour capturer le texte complet de la requête SQL, procédez comme suit.

Notes

Le texte SQL peut contenir des données sensibles telles que des mots de passe et des informations d’identification personnelle. Soyez prudent lors de l’activation de cette fonctionnalité.

1. Dans l’Explorateur de solutions de Visual Studio, ouvrez le fichier Program.cs.

2. Au début du fichier, ajoutez l’instruction using suivante.

   using Microsoft.ApplicationInsights.DependencyCollector;
   

3. Pour activer l’instrumentation de texte de commande SQL, insérez le code suivant juste après le code builder.Services.AddApplicationInsightsTelemetry().

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

   

Exécuter l’application web Azure Cafe

Une fois le code de l’application web déployé, la télémétrie est transmise à Application Insights. Le kit de développement logiciel (SDK) Application Insights collecte automatiquement les requêtes web adressées à votre application.

1. Dans l’Explorateur de solutions de Visual Studio, cliquez avec le bouton droit sur le projet AzureCafe, puis, dans le menu contextuel, sélectionnez Publier.

   

2. Sélectionnez Publier pour promouvoir le nouveau code dans Azure App Service.

   

   Lorsque l’application web Azure Cafe est publiée avec succès, une nouvelle fenêtre de navigateur s’ouvre sur l’application web Azure Cafe.

   

3. Pour générer certaines données de télémétrie, suivez ces étapes dans l’application web pour ajouter une révision.

   1. Sélectionnez Détails en regard d’un café pour voir son menu et ses évaluations.

      

   2. Pour afficher et ajouter des révisions, dans l’écran Café, sélectionnez l’onglet Révisions. Sélectionnez le bouton Ajouter une révision pour ajouter une révision.

      

   3. Dans la boîte de dialogue Create a review, entrez un nom, une note et des commentaires et chargez une photo pour l’évaluation. Lorsque vous avez terminé, sélectionnez Ajouter une évaluation.

      

   4. Si vous devez générer des données de télémétrie supplémentaires, ajoutez des révisions supplémentaires.

Mesures actives

Vous pouvez utiliser des Métriques en direct pour vérifier rapidement si la surveillance d’Application Insights est correctement configurée. Les Métriques en direct montrent l’utilisation du processeur par le processus en cours d’exécution en quasi-temps réel. Elles peuvent également d’autres télémétries comme les requêtes, les dépendances et les traces. Notez quelques minutes peuvent s’écouler avant que les données de télémétrie s’affichent dans le portail et l’analyse.

Affichage de la cartographie de l’application

L’exemple d’application effectue des appels à plusieurs ressources Azure, notamment Azure SQL, Stockage Blob Azure et Azure Language Service (pour l’analyse des sentiments).

Application Insights analyse les données de télémétrie entrantes et peut générer une carte visuelle des intégrations système détectées.

1. Connectez-vous au portail Azure.

2. Ouvrez le groupe de ressources pour l’exemple d’application, à savoir application-insights-azure-cafe.

3. Dans la liste des ressources, sélectionnez la ressource Application Insights azure-cafe-insights-{SUFFIX}.

4. Dans le menu de gauche, sous le titre Examiner, sélectionnez Cartographie d’application. Observez la cartographie d’application générée.

   

Affichage des appels HTTP et du texte de commande SQL de base de données

1. Ouvrez votre ressource Application Insights dans le portail Azure.

2. Dans le menu de gauche, sous l’en-tête Examiner , sélectionnez Niveau de performance.

3. L’onglet Opérations contient les détails des appels HTTP reçus par l’application. Pour basculer entre les vues serveur et navigateur (côté client) des données, utilisez le bouton bascule Serveur/Navigateur.

   

   Capture de l’écran Performances d’Application Insights dans le portail Azure. La capture d’écran montre le bouton bascule Serveur/navigateur et les appels HTTP reçus par l’application mis en évidence.

4. Sélectionnez une opération dans la table, puis choisissez d’explorer un exemple de la requête.

   

   Capture de l’écran Performances d’Application Insights dans le portail Azure. La capture d’écran montre une opération POST et un exemple d’opération dans la liste suggérée sélectionnée et mise en évidence. Le bouton Explorer les exemples est mis en évidence.

   La transaction de bout en bout s’affiche pour la demande sélectionnée. Dans ce cas, une révision ayant été créée avec une image, elle inclut des appels au service Stockage Azure et au service de langage (pour l’analyse des sentiments). Elle inclut également des appels de base de données dans SQL Azure pour conserver la révision. Dans cet exemple, le premier événement sélectionné affiche des informations relatives à l’appel HTTP POST.

   

5. Sélectionnez un élément SQL pour passer en revue le texte de commande SQL émise dans la base de données.

   

6. Si vous le souhaitez, sélectionnez les demandes de dépendance (sortantes) adressées au service Stockage Azure ou au service de langage.

7. Revenez à l’écran Niveau de performance, puis sélectionnez l’onglet Dépendances pour examiner les appels dans les ressources externes. Notez que la table Opérations inclut des appels dans l’analyse des sentiments, le stockage Blob et Azure SQL.

   

Journalisation des applications avec Application Insights

Vue d’ensemble de la journalisation

Application Insights est un type de fournisseur de journalisation disponible pour les applications ASP.NET Core qui deviennent disponibles pour les applications lorsque le package NuGet Application Insights pour ASP.NET Core est installé et que la collecte de télémétrie côté serveur est activée.

En guise de rappel, le code suivant dans Program.cs inscrit le ApplicationInsightsLoggerProvider conteneur intégré d’injection de dépendances.

builder.Services.AddApplicationInsightsTelemetry();

Avec l’inscription de ApplicationInsightsLoggerProvider en tant que fournisseur de journalisation, l’application est prête à se connecter à Application Insights en utilisant une injection de constructeur avec ILogger ou l’alternative de type générique ILogger<TCategoryName>.

Notes

Par défaut, le fournisseur de journalisation est configuré pour capturer automatiquement les événements de journal dont le niveau de gravité est supérieur ou égal à LogLevel.Warning.

Considérez l’exemple de contrôleur suivant. Il illustre l’injection d’ILogger qui est résolue avec le ApplicationInsightsLoggerProvider enregistré avec le conteneur d’injection de dépendance. Observez dans la méthode Get qu’un message d’information, d’avertissement et d’erreur est enregistré.

Notes

Par défaut, la trace au niveau de l’information n’est pas enregistrée. Seuls les niveaux Avertissement et plus sont enregistrés.

using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

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

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        //Info level traces are not captured by default
        _logger.LogInformation("An example of an Info trace..");
        _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 l’article Logging in ASP.NET Core (Journalisation dans ASP.NET Core).

Afficher les journaux d’activité dans Application Insights

Le ValuesController ci-dessus est déployé avec l’exemple d’application et se trouve dans le dossier Controllers du projet.

1. À l’aide d’un navigateur Internet, ouvrez l’exemple d’application. Dans la barre d’adresse, ajoutez /api/Values et appuyez sur Entrée.

   

2. Dans le portail Azure, patientez quelques instants, puis sélectionnez la ressource Application Insights azure-cafe-insights-{SUFFIXE}.

   

3. Dans le menu de gauche de la ressource Application Insights, sélectionnez Journaux sous la section Surveillance.

4. Dans le volet Tables, sous l’arborescence Application Insights, double-cliquez sur la table traces.

5. Modifiez la requête pour récupérer les traces du contrôleur Valeurs comme suit, puis sélectionnez Exécuter pour filtrer les résultats.

   traces 
   | where operation_Name == "GET Values/Get"
   

   Les résultats affichent les messages de journalisation présents dans le contrôleur. Une sévérité de 2 indique un avertissement et une gravité de 3 indique une erreur.

6. Vous pouvez également écrire la requête pour récupérer les résultats en fonction de la catégorie du journal. Par défaut, la catégorie est le nom complet de la classe dans laquelle ILogger est injecté. Dans ce cas, le nom de la catégorie est ValuesController (si un espace de noms est associé à la classe, le nom inclut l’espace de nom en préfixe). Réécrivez et exécutez la requête suivante pour récupérer les résultats en fonction de la catégorie.

   traces 
   | where customDimensions.CategoryName == "ValuesController"
   

Contrôler le niveau des journaux envoyés à Application Insights

Les implémentations ILogger disposent d’un mécanisme intégré pour appliquer le filtrage des journaux. Ce filtrage vous permet de contrôler les journaux qui sont envoyés à chaque fournisseur inscrit, y compris au fournisseur Application Insights. Vous pouvez utiliser le filtrage dans la configuration (avec un fichier appsettings.json) ou dans le code. Pour plus d’informations sur les niveaux de journal et des conseils sur leur utilisation, consultez la documentation Niveau du journal.

Les exemples suivants montrent comment appliquer des règles de filtrage à ApplicationInsightsLoggerProvider pour contrôler le niveau des journaux envoyés à Application Insights.

Créer des règles de filtre dans la configuration

L’alias ApplicationInsightsLoggerProvider est créé en tant qu’alias ApplicationInsights dans la configuration. La section suivante du fichier appsettings.json définit le niveau de journal par défaut pour tous les fournisseurs sur LogLevel.Warning. La configuration du fournisseur ApplicationInsights spécifiquement pour les catégories qui commencent par « ValuesController » remplace cette valeur par défaut par un niveau LogLevel.Error ou supérieur.

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Warning"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "Error" //Log Level for the "ValuesController" category
      }
    }
  }
}

Le déploiement de l’exemple d’application avec le code précédent dans appsettings.json génère uniquement la trace d’erreur envoyée à Application Insights lors de l’interaction avec ValuesController. Cela est dû au fait que logLevel pour la catégorie ValuesController est défini sur Error. Par conséquent, la trace Avertissement est supprimée.

Désactiver la journalisation dans Application Insights

Pour désactiver la journalisation à l’aide de la configuration, définissez toutes les valeurs LogLevel sur « None ».

{
  //... additional code removed for brevity
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "None"
    },
    "ApplicationInsights": { // Specific to the provider, LogLevel applies to the Application Insights provider.
      "LogLevel": {
        "ValuesController": "None" //Log Level for the "ValuesController" category
      }
    }
  }
}

De même, dans le code, définissez le niveau par défaut pour ApplicationInsightsLoggerProvider et tous les niveaux de journal suivants sur None.

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("", LogLevel.None);
builder.Logging.AddFilter<Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider>("ValuesController", LogLevel.None);

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.

Étapes suivantes

• Explorez les flux d’utilisateurs pour comprendre comment les utilisateurs naviguent dans 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.
• Vue d’ensemble de la disponibilité
• Injection de dépendances dans ASP.NET Core
• Journalisation dans ASP.NET Core
• Journaux d’activité .NET dans Application Insights
• Instrumentation automatique pour Application Insights