Partager via

Application Insights pour Java 2.x

  • Article

Attention

Ce document s’applique à Application Insights Java 2.x, qui n’est plus recommandé.

Vous trouverez la documentation de la dernière version dans Application Insights Java 3.x.

Dans cet article, vous allez apprendre à utiliser Application Insights Java 2.x. Cet article vous montre comment :

  • Pour commencer, découvrez comment instrumenter les demandes, effectuer le suivi des dépendances, collecter les compteurs de performances, diagnostiquer les problèmes de performances et les exceptions, et écrire du code pour suivre l’utilisation de votre application par les utilisateurs.
  • Envoyez les journaux de suivi à Application Insights et explorez-les à l’aide du portail Application Insights.
  • Surveillez les dépendances, les exceptions interceptées et les temps d’exécution des méthodes dans les applications web Java.
  • Filtrez les données de télémétrie dans votre application web Java.
  • Explorez les métriques de performance du système Linux dans Application Insights à l’aide de collectd.
  • Mesurez les métriques relatives au code d’application basé sur une machine virtuelle Java (JVM). Exportez les données vers vos systèmes de surveillance favoris à l’aide de la surveillance des applications Micrometer.

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.

Prise en main d'Application Insights dans un projet web Java

Dans cette section, vous allez utiliser le kit de développement logiciel (SDK) Application Insights pour instrumenter les demandes, effectuer le suivi des dépendances, collecter les compteurs de performances, diagnostiquer les problèmes de performances et les exceptions, et écrire du code pour suivre l’utilisation de votre application par les utilisateurs.

Application Insights est un service d’analyse extensible pour développeurs web qui vous permet de comprendre les performances et l’utilisation de votre application en direct. Application Insights prend en charge les applications Java exécutées sur Linux, Unix ou Windows.

Prérequis

Ce dont vous avez besoin :

Obtenir une clé d'instrumentation Application Insights

  1. Connectez-vous au portail Azure.

  2. Dans le Portail Azure, créez une ressource Application Insights. Définissez le type d’application sur Application web Java.

  3. Obtenez la clé d'instrumentation de la nouvelle ressource. Vous devrez la coller rapidement dans le code de votre projet.

    Capture d’écran du volet Vue d’ensemble d’une ressource Application Insights sur le Portail Azure, avec la clé d’instrumentation mise en évidence.

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

Choisissez votre type de projet.

Si votre projet est déjà configuré pour être généré avec Maven, fusionnez le code suivant dans votre fichier pom.xml. Actualisez ensuite les dépendances du projet pour télécharger les fichiers binaires.

    <dependencies>
      <dependency>
        <groupId>com.microsoft.azure</groupId>
        <artifactId>applicationinsights-web-auto</artifactId>
        <!-- or applicationinsights-web for manual web filter registration -->
        <!-- or applicationinsights-core for bare API -->
        <version>2.6.4</version>
      </dependency>
    </dependencies>

Forum aux questions

  • Quelle est la relation entre les composants -web-auto, -web et -core ?

    • applicationinsights-web-auto fournit des métriques qui permettent d’effectuer le suivi du nombre de demandes servlet HTTP et des temps de réponse, en inscrivant automatiquement le filtre servlet Application Insights à l’exécution.
    • applicationinsights-web fournit également des métriques qui permettent d’effectuer le suivi du nombre de requêtes servlet HTTP et des temps de réponse. Toutefois, une inscription manuelle du filtre servlet Application Insights dans votre application est requise.
    • applicationinsights-core fournit l’API seule, par exemple si l’application n’est pas basée sur un servlet.

  • Comment dois-je mettre à jour le Kit de développement logiciel (SDK) vers la dernière version ?

    • Depuis novembre 2020, nous vous recommandons d’utiliser Application Insights Java 3.x pour la surveillance des applications Java. Pour plus d’informations sur la prise en main, consultez Application Insights Java 3.x.

Ajouter un fichier ApplicationInsights.xml

Ajoutez ApplicationInsights.xml dans le dossier de ressources de votre projet ou vérifiez qu’il est ajouté au chemin d’accès de la classe du déploiement de votre projet. Copiez-y le code XML suivant.

Remplacez la clé d’instrumentation par celle que vous avez obtenue sur le Portail Azure.

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings" schemaVersion="2014-05-30">

   <!-- The key from the portal: -->
   <InstrumentationKey>** Your instrumentation key **</InstrumentationKey>

   <!-- HTTP request component (not required for bare API) -->
   <TelemetryModules>
      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebRequestTrackingTelemetryModule"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebSessionTrackingTelemetryModule"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebUserTrackingTelemetryModule"/>
   </TelemetryModules>

   <!-- Events correlation (not required for bare API) -->
   <!-- These initializers add context data to each event -->
   <TelemetryInitializers>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebOperationIdTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebOperationNameTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebSessionTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebUserTelemetryInitializer"/>
      <Add type="com.microsoft.applicationinsights.web.extensibility.initializers.WebUserAgentTelemetryInitializer"/>
   </TelemetryInitializers>

</ApplicationInsights>

Si vous le souhaitez, le fichier config peut être hébergé à tout emplacement accessible par votre application. La propriété système -Dapplicationinsights.configurationDirectory spécifie le répertoire qui contient le fichier ApplicationInsights.xml. Par exemple, un fichier config situé à l’emplacement E:\myconfigs\appinsights\ApplicationInsights.xml doit être configuré avec la propriété -Dapplicationinsights.configurationDirectory="E:\myconfigs\appinsights".

  • La clé d'instrumentation est envoyée avec chaque élément de télémétrie et indique à Application Insights de l'afficher dans votre ressource.
  • Le composant de demande HTTP est facultatif. Il envoie automatiquement la télémétrie concernant les demandes et les temps de réponse au portail.
  • La corrélation des événements est un complément au composant de requête HTTP. Elle assigne un identificateur à chaque requête reçue par le serveur. Cet identificateur est ensuite ajouté comme propriété Operation.Id de chaque élément de télémétrie. Cela vous permet de mettre en corrélation la télémétrie associée à chaque demande en définissant un filtre dans la Recherche de diagnostic.

Autres méthodes pour définir la clé d’instrumentation

Le kit de développement logiciel (SDK) d’Application Insights recherche la clé dans cet ordre :

  • Propriété système : -DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikey
  • Variable d’environnement : APPINSIGHTS_INSTRUMENTATIONKEY
  • Fichier de configuration :ApplicationInsights.xml

Vous pouvez également définir la clé dans le code:

    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

Ajouter un agent

Installez l’agent Java pour capturer les appels HTTP sortants, les requêtes JDBC, la journalisation des applications et une meilleure appellation des opérations.

Exécuter votre application

Exécutez-le en mode débogage sur votre ordinateur de développement, ou publiez-le sur votre serveur.

Voir votre télémétrie dans Application Insights

Revenez à votre ressource Application Insights sur le Portail Azure.

Les données des demandes HTTP apparaissent dans le volet Vue d’ensemble. Si elle ne s’y trouve pas, attendez quelques secondes, puis sélectionnez Actualiser.

Capture d’écran montrant la vue d’ensemble des exemples de données.

En savoir plus sur les métriques.

Cliquez sur un des graphiques pour afficher des métriques agrégées plus détaillées.

Capture d’écran montrant le volet Défaillances Application Insights avec des graphes.

Données d’instance

Cliquez sur un type de demande spécifique pour afficher les instances individuelles.

Capture d’écran montrant l’exploration de la visualisation d’un exemple spécifique.

Log Analytics : un puissant langage de requête

En accumulant des données, vous pouvez exécuter des requêtes pour agréger les données et rechercher des instances individuelles. Log Analytics est un outil puissant qui permet de comprendre les performances et l’utilisation, et d’effectuer des diagnostics.

Capture d’écran montrant un exemple Log Analytics sur le Portail Azure.

Installer votre application sur le serveur

Publiez maintenant votre application sur le serveur, laissez le temps aux usagers de l’utiliser, puis observez les données de télémétrie qui s’affichent sur le portail.

  • Assurez-vous que votre pare-feu autorise votre application à envoyer les données de télémétrie vers ces ports :

    • dc.services.VisualStudio.com:443
    • f5.services.visualstudio.com:443

  • Si le trafic sortant doit être acheminé à travers un pare-feu, définissez les propriétés système http.proxyHost et http.proxyPort.

  • Sur les serveurs Windows, installez :

Azure App Service, Azure Kubernetes Service et configuration des machines virtuelles

L’approche la meilleure et la plus simple pour surveiller des applications s’exécutant sur des fournisseurs de ressources Azure consiste à utiliser Application Insights Java 3.x.

Exceptions et échecs de requêtes

Les exceptions non prises en charge et les échecs de demande sont collectés automatiquement par le filtre web Application Insights.

Pour collecter des données sur d’autres exceptions, vous pouvez insérer des appels à trackException() dans votre code.

Surveiller les appels de méthode et les dépendances externes

Installez l’agent Java pour journaliser les méthodes internes spécifiées et les appels effectués par le biais de JDBC, avec des données de minutage, et pour nommer automatiquement les opérations.

Traçage distribué W3C

Le kit de développement logiciel (SDK) Java Application Insights prend désormais en charge le traçage distribué W3C.

La configuration du kit SDK entrant est expliquée plus en détail dans Corrélation des données de télémétrie dans Application Insights.

La configuration sortante du SDK est définie dans le fichier AI-Agent.xml.

Compteurs de performance

Sélectionnez Examiner>Métriques pour voir un ensemble de compteurs de performances.

Capture d’écran du volet Métriques d’une ressource Application Insights sur le Portail Azure, avec les octets privés de processus sélectionnés.

Personnaliser la collecte des compteurs de performances

Pour désactiver la collecte du jeu standard de compteurs de performances, ajoutez le code suivant sous le nœud racine du fichier ApplicationInsights.xml :

    <PerformanceCounters>
       <UseBuiltIn>False</UseBuiltIn>
    </PerformanceCounters>

Collecte d’autres compteurs de performances

Vous pouvez spécifier d’autres compteurs de performances à collecter.

Compteurs JMX (exposés par la machine virtuelle Java)
    <PerformanceCounters>
      <Jmx>
        <Add objectName="java.lang:type=ClassLoading" attribute="TotalLoadedClassCount" displayName="Loaded Class Count"/>
        <Add objectName="java.lang:type=Memory" attribute="HeapMemoryUsage.used" displayName="Heap Memory Usage-used" type="composite"/>
      </Jmx>
    </PerformanceCounters>
  • displayName : nom affiché sur le portail Application Insights.
  • objectName : nom de l’objet JMX.
  • attribute : attribut du nom de l’objet JMX à récupérer.
  • type (facultatif) : type d’attribut de l’objet JMX :
    • Par défaut un type simple, par exemple int ou long.
    • composite : les données du compteur de performances sont au format Attribute.Data.
    • tabular : les données du compteur de performances sont au format ligne de tableau.
Compteurs de performances Windows

Chaque compteur de performances Windows est un membre d'une catégorie (de la même façon qu'un champ est un membre d'une classe). Les catégories peuvent être globales ou comporter des instances numérotées ou nommées.

    <PerformanceCounters>
      <Windows>
        <Add displayName="Process User Time" categoryName="Process" counterName="%User Time" instanceName="__SELF__" />
        <Add displayName="Bytes Printed per Second" categoryName="Print Queue" counterName="Bytes Printed/sec" instanceName="Fax" />
      </Windows>
    </PerformanceCounters>
  • displayName : nom affiché sur le portail Application Insights.
  • categoryName : catégorie du compteur de performances (objet de performances) à laquelle ce compteur de performances est associé.
  • counterName : nom du compteur de performances.
  • instanceName : nom de l’instance de la catégorie du compteur de performances, ou chaîne vide ("") si la catégorie contient une seule instance. Si categoryName est Process et que le compteur de performances que vous souhaitez collecter vient du processus en cours de la JVM sur laquelle votre application s’exécute, spécifiez "__SELF__".

Compteurs de performances Unix

Installez collectd avec le plug-in Application Insights pour obtenir une grande variété de données système et réseau.

Obtenir des données utilisateur et de session

Vous envoyez à présent des données de télémétrie depuis votre serveur web. Pour obtenir une vue à 360 degrés de votre application, vous pouvez ajouter plus de surveillance :

Envoyer votre propre télémétrie

Maintenant que vous avez installé le kit SDK, vous pouvez utiliser l’API pour envoyer vos propres données de télémétrie :

Tests web de disponibilité

Application Insights peut tester votre site web à intervalles réguliers pour vérifier qu’il fonctionne et répond correctement.

Découvrez comment configurer des tests de disponibilité web.

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

Exploration du suivi des journaux d’activité Java dans Application Insights

Si vous utilisez Logback ou Log4J (v1.2 ou v2.0) pour le suivi, vous pouvez faire en sorte que vos journaux d’activité de suivi soient envoyés automatiquement à Application Insights, où vous pouvez les explorer et effectuer des recherches.

Conseil

Vous ne devez définir votre clé d’instrumentation Application Insights qu’une seule fois pour votre application. Si vous utilisez une infrastructure comme Java Spring, il se peut que vous ayez déjà inscrit la clé ailleurs dans la configuration de votre application.

Utilisation de l’agent Java Application Insights

Par défaut, l’agent Java Application Insights capture automatiquement la journalisation effectuée au niveau WARN et au-dessus.

Vous pouvez changer le seuil de journalisation capturé à l’aide du fichier AI-Agent.xml :

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsightsAgent>
   <Instrumentation>
      <BuiltIn>
         <Logging threshold="info"/>
      </BuiltIn>
   </Instrumentation>
</ApplicationInsightsAgent>

Vous pouvez désactiver la capture de la journalisation par l’agent Java à l’aide du fichier AI-Agent.xml :

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsightsAgent>
   <Instrumentation>
      <BuiltIn>
         <Logging enabled="false"/>
      </BuiltIn>
   </Instrumentation>
</ApplicationInsightsAgent>

Autres solutions

Au lieu d’utiliser l’agent Java, vous pouvez suivre ces instructions.

Installer le Kit de développement logiciel (SDK) Java

Suivez les instructions pour installer le kit SDK Application Insights pour Java, si ce n’est pas déjà fait.

Ajouter des bibliothèques de journalisation à votre projet

Choisissez la méthode adaptée à votre projet.

Maven

Si votre projet est déjà configuré pour être assemblé avec Maven, fusionnez les extraits de code suivants dans votre fichier pom.xml. Actualisez ensuite les dépendances du projet pour télécharger les fichiers binaires.

Logback


    <dependencies>
       <dependency>
          <groupId>com.microsoft.azure</groupId>
          <artifactId>applicationinsights-logging-logback</artifactId>
          <version>[2.0,)</version>
       </dependency>
    </dependencies>

Log4J v2.0


    <dependencies>
       <dependency>
          <groupId>com.microsoft.azure</groupId>
          <artifactId>applicationinsights-logging-log4j2</artifactId>
          <version>[2.0,)</version>
       </dependency>
    </dependencies>

Log4J v1.2


    <dependencies>
       <dependency>
          <groupId>com.microsoft.azure</groupId>
          <artifactId>applicationinsights-logging-log4j1_2</artifactId>
          <version>[2.0,)</version>
       </dependency>
    </dependencies>
Gradle

Si votre projet est déjà configuré pour utiliser Gradle, ajoutez l’une des lignes suivantes au groupe dependencies dans votre fichier build.gradle. Actualisez ensuite les dépendances du projet pour télécharger les fichiers binaires.

Logback


    compile group: 'com.microsoft.azure', name: 'applicationinsights-logging-logback', version: '2.0.+'

Log4J v2.0

    compile group: 'com.microsoft.azure', name: 'applicationinsights-logging-log4j2', version: '2.0.+'

Log4J v1.2

    compile group: 'com.microsoft.azure', name: 'applicationinsights-logging-log4j1_2', version: '2.0.+'

Suivez les instructions pour installer manuellement le kit SDK Java Application Insights et télécharger le fichier jar. Sur la page Maven Central, sélectionnez le lien jar dans la section de téléchargement de l’appender concerné. Ajoutez le fichier jar d’appender téléchargé au projet.

Enregistreur Téléchargement Bibliothèque
Logback Jar de l’appender Logback applicationinsights-logging-logback
Log4J v2.0 Jar de l’appender Log4J v2 applicationinsights-logging-log4j2
Log4J v1.2 Jar de l’appender Log4J v1.2 applicationinsights-logging-log4j1_2

Ajouter l’appender à votre infrastructure de journalisation

Pour recevoir le suivi, fusionnez l’extrait de code approprié dans le fichier de configuration Logback ou Log4J.

Logback


    <appender name="aiAppender" 
      class="com.microsoft.applicationinsights.logback.ApplicationInsightsAppender">
        <instrumentationKey>[APPLICATION_INSIGHTS_KEY]</instrumentationKey>
    </appender>
    <root level="trace">
      <appender-ref ref="aiAppender" />
    </root>

Log4J v2.0


    <Configuration packages="com.microsoft.applicationinsights.log4j.v2">
      <Appenders>
        <ApplicationInsightsAppender name="aiAppender" instrumentationKey="[APPLICATION_INSIGHTS_KEY]" />
      </Appenders>
      <Loggers>
        <Root level="trace">
          <AppenderRef ref="aiAppender"/>
        </Root>
      </Loggers>
    </Configuration>

Log4J v1.2


    <appender name="aiAppender" 
         class="com.microsoft.applicationinsights.log4j.v1_2.ApplicationInsightsAppender">
        <param name="instrumentationKey" value="[APPLICATION_INSIGHTS_KEY]" />
    </appender>
    <root>
      <priority value ="trace" />
      <appender-ref ref="aiAppender" />
    </root>

Les appenders Application Insights peuvent être appelés par n’importe quel enregistreur configuré, et pas nécessairement par l’enregistreur racine (cf. exemples de code précédents).

Explorer le suivi dans le portail Application Insights

Maintenant que vous avez configuré votre projet pour qu’il envoie le suivi à Application Insights, vous pouvez rechercher et consulter ce suivi sur le portail Application Insights, dans le volet Recherche.

Les exceptions envoyées par les enregistreurs d’événements s’affichent sur le portail sous forme de données de télémétrie de type Exception.

Capture d’écran du volet Recherche d’une ressource Application Insights sur le Portail Azure.

Surveiller les dépendances, les exceptions interceptées et les temps d’exécution des méthodes dans les applications web Java

Si vous avez instrumenté votre application web Java avec le kit SDK Application Insights, vous pouvez utiliser l’agent Java pour obtenir des informations plus détaillées, sans pour autant modifier le code :

  • Dépendances : données sur les appels passés par l’application à d’autres composants :

    • Appels HTTP sortants : les appels effectués par le biais de Apache HttpClient, de OkHttp et de java.net.HttpURLConnection sont capturés.
    • Appels Redis : les appels effectués par le biais du client Jedis sont capturés.
    • Requêtes JDBC : pour MySQL et PostgreSQL, l’agent signale le plan de requête si l’appel prend plus de 10 secondes.

  • Journalisation des applications : capturez et mettez en corrélation les journaux de vos applications avec des requêtes HTTP et d’autres données de télémétrie :

    • Log4j 1.2
    • Log4j2
    • Logback

  • Meilleure appellation des opérations : utilisée pour l’agrégation des demandes sur le portail.

    • Spring : basé sur @RequestMapping.
    • JAX-RS : basé sur @Path.

Pour utiliser l’agent Java, installez-le sur votre serveur. Vos applications web doivent être instrumentées à l’aide du Kit de développement logiciel (SDK) Java Application Insights.

Installer l’agent Application Insights pour Java

  1. Téléchargez l'agent 2.x sur la machine exécutant votre serveur Java. Vérifiez que la version de l’agent Java 2.x que vous utilisez correspond à la version de votre kit SDK Java Application Insights 2.x.

  2. Modifiez le script de démarrage du serveur d’applications, puis ajoutez l’argument JVM suivant :

    -javaagent:<full path to the agent JAR file>

    Par exemple, dans Tomcat sur une machine Linux :

    export JAVA_OPTS="$JAVA_OPTS -javaagent:<full path to agent JAR file>"

  3. Redémarrez votre serveur d’applications.

Configurer l’agent

Créez un fichier nommé AI-Agent.xml et placez-le dans le même dossier que le fichier jar de l’agent.

Définissez le contenu du fichier XML. Modifiez l’exemple suivant pour inclure ou omettre les fonctionnalités souhaitées.

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsightsAgent>
   <Instrumentation>
      <BuiltIn enabled="true">

         <!-- capture logging via Log4j 1.2, Log4j2, and Logback, default is true -->
         <Logging enabled="true" />

         <!-- capture outgoing HTTP calls performed through Apache HttpClient, OkHttp,
              and java.net.HttpURLConnection, default is true -->
         <HTTP enabled="true" />

         <!-- capture JDBC queries, default is true -->
         <JDBC enabled="true" />

         <!-- capture Redis calls, default is true -->
         <Jedis enabled="true" />

         <!-- capture query plans for JDBC queries that exceed this value (MySQL, PostgreSQL),
              default is 10000 milliseconds -->
         <MaxStatementQueryLimitInMS>1000</MaxStatementQueryLimitInMS>

      </BuiltIn>
   </Instrumentation>
</ApplicationInsightsAgent>

Configuration supplémentaire (Spring Boot)

java -javaagent:/path/to/agent.jar -jar path/to/TestApp.jar

Pour Azure App Service, procédez comme suit :

  1. Sélectionnez Paramètres>Paramètres de l’application.

  2. Sous Paramètres de l’application, ajoutez une nouvelle paire clé/valeur :

    • Clé : JAVA_OPTS
    • Valeur : -javaagent:D:/home/site/wwwroot/applicationinsights-agent-2.6.4.jar

    L’agent doit être empaqueté sous forme de ressource dans votre projet de sorte qu’il se retrouve dans le répertoire D:/home/site/wwwroot/. Pour vérifier que votre agent se situe dans le bon répertoire App Service, accédez à Outils de développement>Outils avancés>Console de débogage, puis examinez le contenu du répertoire du site.

  3. Enregistrez les paramètres, puis redémarrez votre application. Cette procédure s’applique uniquement aux services d’application s’exécutant sur Windows.

Notes

Le fichier AI-Agent.xml et le fichier jar de l’agent doivent se trouver dans le même dossier. Ils sont souvent placés ensemble dans le dossier /resources du projet.

Activer le traçage distribué W3C

Ajoutez l’extrait de code suivant à AI-Agent.xml :

<Instrumentation>
   <BuiltIn enabled="true">
      <HTTP enabled="true" W3C="true" enableW3CBackCompat="true"/>
   </BuiltIn>
</Instrumentation>

Notes

Le mode de compatibilité descendante est activé par défaut. Le paramètre enableW3CBackCompat, facultatif, ne doit être utilisé que lorsque vous souhaitez le désactiver.

Idéalement, ce doit être le cas si tous les services ont été mis à jour vers une version plus récente des kits SDK prenant en charge le protocole W3C. Nous vous recommandons de passer dès que possible à des versions ultérieures des kits SDK avec prise en charge W3C.

Assurez-vous que les configurations entrante et sortante (agent) sont totalement identiques.

Visualiser les données

Dans la ressource Application Insights, les temps d’exécution cumulés de la méthode et de la dépendance distante apparaissent dans la vignette Performances.

Pour rechercher des instances de dépendance et d’exception ainsi que des rapports de méthode, ouvrez Rechercher.

Découvrez comment diagnostiquer les problèmes de dépendance.

Des questions ou des problèmes ?

Utilisez les ressources suivantes :

Filtrer la télémétrie dans votre application web Java

Les filtres offrent un moyen de sélectionner les données de télémétrie que votre application web Java envoie à Application Insights. Il existe des filtres prêts à l’emploi que vous pouvez utiliser. Vous avez également la possibilité d’écrire vos propres filtres personnalisés.

Les filtres prêts à l’emploi incluent :

  • Niveau de gravité de trace.
  • URL, mots clés et codes de réponse spécifiques.
  • Réponses rapides. En d’autres termes, les demandes auxquelles votre application a répondu rapidement.
  • Noms des événements spécifiques.

Notes

Les filtres faussent les mesures de votre application. Par exemple, vous pouvez décider que, pour diagnostiquer les réponses lentes, vous allez définir un filtre permettant d’ignorer les temps de réponse rapides. Sachez toutefois que les temps de réponse moyens signalés par Application Insights seront alors plus lents que la vitesse réelle. En outre, le nombre de demandes sera inférieur au nombre réel.

Si cela pose problème, utilisez plutôt l’échantillonnage.

Définir les filtres

Dans ApplicationInsights.xml, ajoutez une section TelemetryProcessors comme dans l’exemple suivant :


    <ApplicationInsights>
      <TelemetryProcessors>

        <BuiltInProcessors>
           <Processor type="TraceTelemetryFilter">
                  <Add name="FromSeverityLevel" value="ERROR"/>
           </Processor>

           <Processor type="RequestTelemetryFilter">
                  <Add name="MinimumDurationInMS" value="100"/>
                  <Add name="NotNeededResponseCodes" value="200-400"/>
           </Processor>

           <Processor type="PageViewTelemetryFilter">
                  <Add name="DurationThresholdInMS" value="100"/>
                  <Add name="NotNeededNames" value="home,index"/>
                  <Add name="NotNeededUrls" value=".jpg,.css"/>
           </Processor>

           <Processor type="TelemetryEventFilter">
                  <!-- Names of events we don't want to see -->
                  <Add name="NotNeededNames" value="Start,Stop,Pause"/>
           </Processor>

           <!-- Exclude telemetry from availability tests and bots -->
           <Processor type="SyntheticSourceFilter">
                <!-- Optional: specify which synthetic sources,
                     comma-separated
                     - default is all synthetics -->
                <Add name="NotNeededSources" value="Application Insights Availability Monitoring,BingPreview"
           </Processor>

        </BuiltInProcessors>

        <CustomProcessors>
          <Processor type="com.fabrikam.MyFilter">
            <Add name="Successful" value="false"/>
          </Processor>
        </CustomProcessors>

      </TelemetryProcessors>
    </ApplicationInsights>

Inspectez l’ensemble complet des processeurs intégrés.

Filtres intégrés

Cette section décrit les filtres intégrés disponibles.

Filtre Télémétrie des mesures


           <Processor type="MetricTelemetryFilter">
                  <Add name="NotNeeded" value="metric1,metric2"/>
           </Processor>
  • NotNeeded : liste séparée par des virgules des noms de métriques personnalisées.

Filtre Télémétrie d’affichage de page


           <Processor type="PageViewTelemetryFilter">
                  <Add name="DurationThresholdInMS" value="500"/>
                  <Add name="NotNeededNames" value="page1,page2"/>
                  <Add name="NotNeededUrls" value="url1,url2"/>
           </Processor>
  • DurationThresholdInMS : la durée correspond au temps nécessaire pour charger la page. Si ce paramètre est défini, les pages qui se sont chargées plus rapidement que cette durée ne sont pas signalées.
  • NotNeededNames : liste séparée par des virgules de noms de pages.
  • NotNeededUrls : liste séparée par des virgules de fragments d’URL. Par exemple, "home" exclut toutes les pages contenant « home » dans l’URL.

Filtre Télémétrie des demandes


           <Processor type="RequestTelemetryFilter">
                  <Add name="MinimumDurationInMS" value="500"/>
                  <Add name="NotNeededResponseCodes" value="page1,page2"/>
                  <Add name="NotNeededUrls" value="url1,url2"/>
           </Processor>

Filtre Sources synthétiques

Exclut toutes les données de télémétrie présentant des valeurs dans la propriété SyntheticSource. Sont incluses les demandes des robots, des robots d’indexation et des tests de disponibilité.

Exclut les données de télémétrie de toutes les demandes synthétiques :


           <Processor type="SyntheticSourceFilter" />

Exclut les données de télémétrie de sources synthétiques spécifiques :


           <Processor type="SyntheticSourceFilter" >
                  <Add name="NotNeeded" value="source1,source2"/>
           </Processor>
  • NotNeeded : liste séparée par des virgules de noms de sources synthétiques.

Filtre Événements de télémétrie

Filtre les événements personnalisés enregistrés à l’aide de TrackEvent() :


           <Processor type="TelemetryEventFilter" >
                  <Add name="NotNeededNames" value="event1, event2"/>
           </Processor>
  • NotNeededNames : liste séparée par des virgules des noms d’événements.

Filtre Télémétrie des traces

Filtre les traces de journaux consignés à l’aide de TrackTrace() ou d’un collecteur de framework de journalisation.


           <Processor type="TraceTelemetryFilter">
                  <Add name="FromSeverityLevel" value="ERROR"/>
           </Processor>

  • Les valeurs valides FromSeverityLevel sont les suivantes :

    • OFF : exclut toutes les traces.
    • TRACE : aucun filtrage. Équivaut au niveau TRACE.
    • INFO : exclut le niveau TRACE.
    • WARN : exclut les niveaux TRACE et INFO.
    • ERREUR : exclut les niveaux WARN, INFO et TRACE.
    • CRITICAL : exclut tous les niveaux autres que CRITICAL.

Filtres personnalisés

Les sections suivantes vous montrent la procédure à suivre pour créer vos propres filtres personnalisés.

Codez votre filtre

Dans votre code, créez une classe qui implémente TelemetryProcessor:


    package com.fabrikam.MyFilter;
    import com.microsoft.applicationinsights.extensibility.TelemetryProcessor;
    import com.microsoft.applicationinsights.telemetry.Telemetry;

    public class SuccessFilter implements TelemetryProcessor {

        /* Any parameters that are required to support the filter.*/
        private final String successful;

        /* Initializers for the parameters, named "setParameterName" */
        public void setNotNeeded(String successful)
        {
            this.successful = successful;
        }

        /* This method is called for each item of telemetry to be sent.
           Return false to discard it.
           Return true to allow other processors to inspect it. */
        @Override
        public boolean process(Telemetry telemetry) {
            if (telemetry == null) { return true; }
            if (telemetry instanceof RequestTelemetry)
            {
                RequestTelemetry requestTelemetry = (RequestTelemetry)    telemetry;
                return request.getSuccess() == successful;
            }
            return true;
        }
    }

Appeler votre filtre dans le fichier de configuration

Dans ApplicationInsights.xml :



    <ApplicationInsights>
      <TelemetryProcessors>
        <CustomProcessors>
          <Processor type="com.fabrikam.SuccessFilter">
            <Add name="Successful" value="false"/>
          </Processor>
        </CustomProcessors>
      </TelemetryProcessors>
    </ApplicationInsights>

Appeler votre filtre (Java Spring)

Pour les applications basées sur l’infrastructure Spring, les processeurs de télémétrie personnalisée doivent être inscrits dans votre classe d’application principale, en tant que composant bean. Ils sont ensuite connectés automatiquement au démarrage de l’application.

@Bean
public TelemetryProcessor successFilter() {
      return new SuccessFilter();
}

Vous créez vos propres paramètres de filtre dans application.properties. Ensuite, vous utilisez l’infrastructure de configuration externalisée de Spring Boot pour passer ces paramètres dans votre filtre personnalisé.

Résolution des problèmes

Dans cette section figure un conseil de résolution des problèmes.

Mon filtre ne fonctionne pas

Vérifiez que vous avez fourni des valeurs de paramètres valides. Par exemple, les durées doivent être des entiers. En cas de valeurs non valides, le filtre est ignoré. Si votre filtre personnalisé lève une exception à partir d’un constructeur ou d’une méthode définie, il sera ignoré.

collectd : métriques de performances Linux dans Application Insights (déconseillées)

Pour explorer les métriques de performances d’un système Linux dans Application Insights, installez collectd ainsi que son plug-in Application Insights. Cette solution open source rassemble diverses statistiques concernant le système et le réseau.

De manière générale, on utilise collectd après avoir instrumenté le service web Java avec Application Insights. Il vous donne davantage de données pour vous aider à améliorer les performances de votre application ou à diagnostiquer les problèmes.

Récupérer votre clé d’instrumentation

Sur le Portail Azure, ouvrez la ressource Application Insights dans laquelle vous souhaitez afficher les données. Vous pouvez également créer une ressource.

Effectuez une copie de la clé d’instrumentation, qui identifie la ressource.

Capture d’écran du volet Vue d’ensemble d’une ressource Application Insights sur le Portail Azure, avec la clé d’instrumentation mise en évidence.

Installer le plug-in et collectd

Sur vos ordinateurs serveurs Linux :

  1. Installez collectd version 5.4.0 ou ultérieure.
  2. Téléchargez le plug-in d’écriture collectd Application Insights. Notez le numéro de version.
  3. Copiez le fichier jar du plug-in dans /usr/share/collectd/java.
  4. Modifiez /etc/collectd/collectd.conf:

    • Vérifiez que le plug-in Java est activé.

    • Mettez à jour l’élément JVMArg de java.class.path de façon à inclure le fichier jar suivant. Mettez à jour le numéro de version afin qu’il corresponde à celui que vous avez téléchargé :

      • /usr/share/collectd/java/applicationinsights-collectd-1.0.5.jar

    • Ajoutez cet extrait de code à l’aide de la clé d’instrumentation provenant de votre ressource :

      
     LoadPlugin "com.microsoft.applicationinsights.collectd.ApplicationInsightsWriter"
     <Plugin ApplicationInsightsWriter>
        InstrumentationKey "Your key"
     </Plugin>

      Voici une partie d’un exemple de fichier de configuration :

      
    ...
    # collectd plugins
    LoadPlugin cpu
    LoadPlugin disk
    LoadPlugin load
    ...

    # Enable Java Plugin
    LoadPlugin "java"

    # Configure Java Plugin
    <Plugin "java">
      JVMArg "-verbose:jni"
      JVMArg "-Djava.class.path=/usr/share/collectd/java/applicationinsights-collectd-1.0.5.jar:/usr/share/collectd/java/collectd-api.jar"

      # Enabling Application Insights plugin
      LoadPlugin "com.microsoft.applicationinsights.collectd.ApplicationInsightsWriter"

      # Configuring Application Insights plugin
      <Plugin ApplicationInsightsWriter>
        InstrumentationKey "12345678-1234-1234-1234-123456781234"
      </Plugin>

      # Other plugin configurations ...
      ...
    </Plugin>
    ...

Configurez d’autres plug-ins collectd permettant de collecter diverses données de différentes sources.

Redémarrez collectd en suivant son manuel.

Visualiser les données dans Application Insights

Dans votre ressource Application Insights, ouvrez Métriques et ajout de graphes. Sélectionnez les métriques que vous voulez voir dans la catégorie Personnalisé.

Par défaut, les métriques sont agrégés sur toutes les machines hôtes à partir desquelles ils ont été collectés. Pour visualiser les métriques hôte par hôte, activez Regroupement dans le volet Détail du graphe, puis choisissez de les regrouper par CollectD-Host.

Exclusion du chargement de statistiques spécifiques

Par défaut, le plug-in Application Insights envoie toutes les données collectées par tous les plug-ins collectd read activés.

Pour exclure des données provenant de plug-ins ou de sources de données spécifiques, procédez comme suit :

  • Modifiez le fichier de configuration.

  • Dans <Plugin ApplicationInsightsWriter>, ajoutez des lignes de directive comme celles du tableau suivant :

    Directive Résultat
    Exclude disk Excluez toutes les données collectées par le plug-in disk.
    Exclude disk:read,write Excluez les sources nommées read et write du plug-in disk.

Séparez les directives par un saut de ligne.

Des problèmes ?

Dans cette section figurent des conseils de résolution des problèmes.

Je ne vois pas les données dans le portail

Essayez ces options :

  • Ouvrez Rechercher pour voir si les événements bruts sont arrivés. Ils mettent parfois du temps à apparaître dans Metrics Explorer.
  • Vous devrez peut-être définir des exceptions de pare-feu pour les données sortantes.
  • Activez le suivi dans le plug-in Application Insights. Ajoutez la ligne ci-après dans <Plugin ApplicationInsightsWriter>:
    • SDKLogger true
  • Ouvrez un terminal et démarrez collectd en mode détaillé pour voir si des problèmes ont été signalés :
    • sudo collectd -f

Problème connu

Le plug-in d’écriture Application Insights n’est pas compatible avec certains plug-ins de lecture. Tandis que certains plug-ins envoient parfois NaN, le plug-in Application Insights attend un nombre à virgule flottante.

  • Symptôme : le journal collectd affiche des erreurs indiquant « AI: … SyntaxError: Jeton N inattendu ».
  • Solution de contournement : excluez les données collectées par les plug-ins d’écriture à l’origine du problème.

La supervision d’application Micrometer mesure les métriques pour le code d’application basé sur la JVM et vous permet d’exporter les données vers vos systèmes de supervision préférés. Cette section vous montre comment utiliser Micrometer avec Application Insights pour les applications Spring Boot et les autres.

Utilisation de Spring Boot 1.5x

Ajoutez les dépendances suivantes à votre fichier pom.xml ou build.gradle :

  • Application Insights spring-boot-starter 2.5.0 (ou version ultérieure).
  • Micrometer Azure Registry 1.1.0 (ou version ultérieure).
  • Micrometer Spring Legacy 1.1.0 (ou version ultérieure). Il rétroporte le code de configuration automatique dans l’infrastructure Spring.
  • Ressource ApplicationInsights.

Procédez comme suit :

  1. Mettez à jour le fichier pom.xml de votre application Spring Boot et ajoutez-y les dépendances suivantes :

    <dependency>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>applicationinsights-spring-boot-starter</artifactId>
    <version>2.5.0</version>
</dependency>

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-spring-legacy</artifactId>
    <version>1.1.0</version>
</dependency>

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-azure-monitor</artifactId>
    <version>1.1.0</version>
</dependency>

  2. Mettez à jour le fichier application.properties ou YML avec la clé d’instrumentation Application Insights à l’aide de la propriété suivante :

    azure.application-insights.instrumentation-key=<your-instrumentation-key-here>

  3. Créez votre application et exécutez-la.

La procédure précédente devrait vous permettre d’utiliser des métriques préagrégées collectées automatiquement pour Azure Monitor.

Utilisation de Spring 2.x

Ajoutez les dépendances suivantes à votre fichier pom.xml ou build.gradle :

  • Application Insights Spring-boot-starter version 2.1.2 ou ultérieure
  • Azure-spring-boot-metrics-starters version 2.0.7 ou ultérieure
  • Ressource Application Insights

Procédez comme suit :

  1. Mettez à jour le fichier pom.xml de votre application Spring Boot et ajoutez-y la dépendance suivante :

    <dependency> 
      <groupId>com.microsoft.azure</groupId>
      <artifactId>azure-spring-boot-metrics-starter</artifactId>
      <version>2.0.7</version>
</dependency>

  2. Mettez à jour le fichier application.properties ou YML avec la clé d’instrumentation Application Insights à l’aide de la propriété suivante :

    azure.application-insights.instrumentation-key=<your-instrumentation-key-here>

  3. Créez votre application et exécutez-la.

La procédure précédente devrait vous permettre d’utiliser des métriques préagrégées collectées automatiquement pour Azure Monitor. Pour savoir comment ajuster Application Insights Spring Boot Starter, consultez le fichier Lisez-moi sur GitHub.

Métriques par défaut :

  • Métriques configurées automatiquement pour Tomcat, JVM, métriques Logback, métriques Log4J, métriques de disponibilité, métriques de processeur et FileDescriptorMetrics.
  • Par exemple, si Netflix Hystrix est présent dans le chemin des classes, nous récupérons également ces métriques.
  • Vous pouvez obtenir les métriques suivantes en ajoutant les beans associés :
    • CacheMetrics (CaffeineCache, EhCache2, GuavaCache, HazelcastCache et JCache)
    • DataBaseTableMetrics
    • HibernateMetrics
    • JettyMetrics
    • Métriques OkHttp3
    • Métriques Kafka

Désactivation de la collecte automatique de métriques :

  • Métriques de JVM :
    • management.metrics.binders.jvm.enabled=false
  • Mesures Logback :
    • management.metrics.binders.logback.enabled=false
  • Mesures sur le fonctionnement :
    • management.metrics.binders.uptime.enabled=false
  • Mesures sur le processeur :
    • management.metrics.binders.processor.enabled=false
  • FileDescriptorMetrics :
    • management.metrics.binders.files.enabled=false
  • Métriques Hystrix si la bibliothèque se trouve dans classpath :
    • management.metrics.binders.hystrix.enabled=false
  • Métriques AspectJ si la bibliothèque se trouve dans classpath :
    • spring.aop.enabled=false

Notes

Spécifiez les propriétés précédentes dans le fichier application.properties ou application.yml de votre application Spring Boot.

Utilisez Micrometer avec les applications web non Spring Boot

Ajoutez les dépendances suivantes à votre fichier pom.xml ou build.gradle :

Procédez comme suit :

  1. Ajoutez les dépendances suivantes à votre fichier pom.xml ou build.gradle :

        <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-azure-monitor</artifactId>
        <version>1.1.0</version>
    </dependency>

    <dependency>
        <groupId>com.microsoft.azure</groupId>
        <artifactId>applicationinsights-web-auto</artifactId>
        <version>2.5.0</version>
    </dependency>

  2. Si ce n’est déjà fait, ajoutez le fichier ApplicationInsights.xml dans le dossier resources. Pour plus d’informations, consultez Ajouter un fichier ApplicationInsights.xml.

  3. Exemple de classe de servlet (émet une métrique de minuteur) :

        @WebServlet("/hello")
    public class TimedDemo extends HttpServlet {

      private static final long serialVersionUID = -4751096228274971485L;

      @Override
      @Timed(value = "hello.world")
      protected void doGet(HttpServletRequest request, HttpServletResponse response)
          throws ServletException, IOException {

        response.getWriter().println("Hello World!");
        MeterRegistry registry = (MeterRegistry) getServletContext().getAttribute("AzureMonitorMeterRegistry");

    //create new Timer metric
        Timer sampleTimer = registry.timer("timer");
        Stream<Integer> infiniteStream = Stream.iterate(0, i -> i+1);
        infiniteStream.limit(10).forEach(integer -> {
          try {
            Thread.sleep(1000);
            sampleTimer.record(integer, TimeUnit.MILLISECONDS);
          } catch (Exception e) {}
           });
      }
      @Override
      public void init() throws ServletException {
        System.out.println("Servlet " + this.getServletName() + " has started");
      }
      @Override
      public void destroy() {
        System.out.println("Servlet " + this.getServletName() + " has stopped");
      }

    }

  4. Exemple de classe de configuration :

         @WebListener
     public class MeterRegistryConfiguration implements ServletContextListener {

       @Override
       public void contextInitialized(ServletContextEvent servletContextEvent) {

     // Create AzureMonitorMeterRegistry
       private final AzureMonitorConfig config = new AzureMonitorConfig() {
         @Override
         public String get(String key) {
             return null;
         }
        @Override
           public Duration step() {
             return Duration.ofSeconds(60);}

         @Override
         public boolean enabled() {
             return false;
         }
     };

  MeterRegistry azureMeterRegistry = AzureMonitorMeterRegistry.builder(config);

         //set the config to be used elsewhere
         servletContextEvent.getServletContext().setAttribute("AzureMonitorMeterRegistry", azureMeterRegistry);

       }

       @Override
       public void contextDestroyed(ServletContextEvent servletContextEvent) {

       }
     }

Pour plus d’informations sur les métriques, consultez la documentation de Micrometer.

D’autres exemples de code sur la création de différents types de métriques sont disponibles dans le référentiel GitHub officiel de Micrometer.

Liaison de collecte de métriques supplémentaire

Les sections suivantes montrent comment collecter d’autres métriques.

SpringBoot/Spring

Créez un bean de la catégorie de métrique appropriée. Supposons par exemple que vous ayez besoin de métriques du cache Guava :

    @Bean
    GuavaCacheMetrics guavaCacheMetrics() {
        Return new GuavaCacheMetrics();
    }

Plusieurs métriques ne sont pas activées par défaut, mais peuvent être liées de la manière précédente. Pour obtenir la liste complète, consultez le référentiel GitHub de Micrometer.

Applications non Spring

Ajoutez le code de liaison suivant au fichier de configuration :

    New GuavaCacheMetrics().bind(registry);

Étapes suivantes