Application Insights pour Java 2.x

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

• Commencez et découvrez comment instrumenter les requêtes, suivre les dépendances, collecter des compteurs de performances, diagnostiquer les problèmes de performances et les exceptions, et écrire du code pour suivre ce que font les utilisateurs avec votre application.
• Envoyez des 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 de méthode dans les applications web Java.
• Filtrez les données de télémétrie dans votre application web Java.
• Explorez les métriques de performances du système Linux dans Application Insights à l’aide de collectd.
• Mesurez les métriques pour le code d’application JVM (Java Virtual Machine). Exportez les données vers vos systèmes de surveillance favoris à l’aide de la surveillance des applications Micrometer.

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

Dans cette section, vous utilisez le Kit de développement logiciel (SDK) Application Insights pour instrumenter les requêtes, suivre les dépendances, collecter des compteurs de performances, diagnostiquer les problèmes de performances et les exceptions, et écrire du code pour suivre ce que font les utilisateurs avec votre application.

Application Insights est un service d’analytique extensible pour les développeurs web qui vous aide à comprendre les performances et l’utilisation de votre application dynamique. Application Insights prend en charge les applications Java s’exécutant sur Linux, Unix ou Windows.

Prerequisites

Ce dont vous avez besoin :

• Un compte Azure avec un abonnement actif. Vous pouvez créer un compte gratuitement.
• Application Java fonctionnelle.

Obtenez une clé d'instrumentation pour 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 l’application web Java.

3. Recherchez la clé d’instrumentation de la nouvelle ressource. Vous devez coller cette clé dans votre projet de code sous peu.

   

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

Choisissez votre type de projet.

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

    dependencies {
      compile group: 'com.microsoft.azure', name: 'applicationinsights-web-auto', version: '2.6.4'
      // or applicationinsights-web for manual web filter registration
      // or applicationinsights-core for bare API
    }

Questions fréquemment posées

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

  • applicationinsights-web-auto fournit des métriques qui suivent les nombres de demandes et les temps de réponse HTTP en inscrivant automatiquement le filtre de servlet Application Insights au moment de l’exécution.
  • applicationinsights-web vous fournit également des métriques qui suivent les nombres de demandes de servlet HTTP et les temps de réponse. Toutefois, l’inscription manuelle du filtre servlet Application Insights dans votre application est requise.
  • applicationinsights-core vous donne l’API nue, par exemple, si votre application n’est pas basée sur servlet.

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

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

Ajouter un fichier ApplicationInsights.xml

Ajoutez ApplicationInsights.xml au dossier des ressources de votre projet ou assurez-vous qu’il est ajouté au chemin de classe de déploiement de votre projet. Copiez le code XML suivant dans celui-ci.

Remplacez la clé d’instrumentation par celle que vous avez obtenue à partir du 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 de configuration peut se trouver dans n’importe quel emplacement accessible à votre application. La propriété -Dapplicationinsights.configurationDirectory système spécifie le répertoire qui contient ApplicationInsights.xml. Par exemple, un fichier de configuration situé à E:\myconfigs\appinsights\ApplicationInsights.xml serait 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 Requête HTTP est facultatif. Il envoie automatiquement des données de télémétrie sur les demandes et les temps de réponse au portail.
• La corrélation d’événements est un ajout au composant de requête HTTP. Il affecte un identificateur à chaque requête reçue par le serveur. Il ajoute ensuite cet identificateur en tant que propriété à chaque élément de télémétrie en tant que propriété Operation.Id. Il vous permet de mettre en corrélation les données de télémétrie associées à chaque requête en définissant un filtre dans la recherche de diagnostic.

Autres façons de définir la clé d’instrumentation

Le Kit de développement logiciel (SDK) 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 le définir 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 un meilleur nommage 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.

Afficher vos données de télémétrie dans Application Insights

Revenez à votre ressource Application Insights dans le portail Azure.

Les données de requêtes HTTP s’affichent dans le volet vue d’ensemble. Si ce n’est pas le cas, attendez quelques secondes, puis sélectionnez Actualiser.

En savoir plus sur les métriques.

Cliquez sur n’importe quel graphique pour afficher des métriques agrégées plus détaillées.

Données d’instance

Cliquez sur un type de requête spécifique pour afficher des instances individuelles.

Log Analytics : Langage de requête puissant

Lorsque vous accumulez davantage de données, vous pouvez exécuter des requêtes pour agréger des données et rechercher des instances individuelles. Log Analytics est un outil puissant pour comprendre les performances et l’utilisation, et à des fins de diagnostic.

Installer votre application sur le serveur

Maintenant, publiez votre application sur le serveur, laissez les utilisateurs l’utiliser et regardez les données de télémétrie s’afficher dans le portail.

• Assurez-vous que votre pare-feu permet à votre application d’envoyer des données de télémétrie à ces ports :

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

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

• Sur les serveurs Windows, installez :

  • Microsoft Visual C++ Redistributable

    Ce composant active les compteurs de performances.

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

La meilleure approche et la plus simple pour surveiller vos applications s’exécutant sur n’importe quel fournisseur de ressources Azure consiste à utiliser Application Insights Java 3.x.

Exceptions et échecs de requête

Les exceptions non gérées et les échecs de requête sont automatiquement collectés 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 consigner les méthodes internes spécifiées et les appels effectués via JDBC, avec des données de minutage et pour l’affectation automatique de noms des opérations.

Suivi distribué W3C

Le Kit de développement logiciel (SDK) Java Application Insights prend désormais en charge le suivi distribué W3C.

La configuration du Kit de développement logiciel (SDK) entrante est expliquée plus en détail dans la corrélation de télémétrie dans Application Insights.

La configuration du Kit de développement logiciel (SDK) sortante est définie dans le fichier AI-Agent.xml .

Compteurs de performance

Sélectionnez Examiner>les métriques pour afficher une plage de compteurs de performances.

Personnaliser la collection de compteurs de performances

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

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

Collecter plus de compteurs de performances

Vous pouvez spécifier davantage de 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é dans le portail Application Insights.
• objectName: nom de l’objet JMX.
• attribute: attribut du nom de l’objet JMX à extraire.
• type (facultatif) : type de l’attribut de l’objet JMX :
  • Valeur par défaut : type simple, tel qu’int ou long.
  • composite: les données du compteur de perf sont au format de Attribute.Data.
  • tabular: les données de compteur perf sont au format d’une ligne de tableau.

Compteurs de performances Windows

Chaque compteur de performances Windows est membre d’une catégorie (de la même façon qu’un champ est membre d’une classe). Les catégories peuvent être globales ou 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é dans le portail Application Insights.
• categoryName: catégorie de compteur de performances (objet de performance) avec laquelle ce compteur de performances est associé.
• counterName: nom du compteur de performances.
• instanceName: nom de l’instance de catégorie de compteur de performances ou d’une 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 provient du processus JVM actuel sur lequel votre application s'exécute, spécifiez "__SELF__".

Compteurs de performances Unix

Installez collectd avec le plug-in Application Insights pour obtenir un large éventail de données système et réseau.

Obtenir des données utilisateur et de session

Vous envoyez maintenant des données de télémétrie à partir de votre serveur web. Pour obtenir la vue complète de votre application à 360 degrés, vous pouvez ajouter d’autres analyses :

• Ajoutez des données de télémétrie à vos pages web pour surveiller les vues de page et les métriques utilisateur.
• Configurez des tests web pour vous assurer que votre application reste active et réactive.

Envoyer vos propres données de télémétrie

Maintenant que vous avez installé le Kit de développement logiciel (SDK), vous pouvez utiliser l’API pour envoyer vos propres données de télémétrie :

• Suivez les événements et les métriques personnalisés pour découvrir ce que font les utilisateurs avec votre application.
• Recherchez des événements et des journaux pour faciliter le diagnostic des problèmes.

Tests web de disponibilité

Application Insights peut tester votre site web à intervalles réguliers pour vérifier qu’il est opérationnel et répond bien.

En savoir plus sur la configuration des tests web de disponibilité.

Résolution des problèmes

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

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

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

Explorer les journaux de suivi Java dans Application Insights

Si vous utilisez Logback ou Log4J (v1.2 ou v2.0) pour le suivi, vous pouvez envoyer automatiquement vos journaux de trace à Application Insights où vous pouvez explorer et rechercher sur ces derniers.

Utiliser 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 modifier 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 journalisation de 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>

Alternatives

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 de développement logiciel (SDK) Application Insights pour Java, si vous ne l’avez pas déjà fait.

Ajouter des bibliothèques de journalisation à votre projet

Choisissez la façon appropriée pour votre projet.

Maven

Si votre projet est déjà configuré pour utiliser Maven pour la génération, fusionnez l’un des extraits de code suivants dans votre fichier pom.xml . Actualisez ensuite les dépendances du projet pour obtenir les fichiers binaires téléchargés.

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 pour la génération, ajoutez l’une des lignes suivantes au dependencies groupe dans votre fichier build.gradle . Actualisez ensuite les dépendances du projet pour obtenir les fichiers binaires téléchargés.

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

Utiliser le lien JAR

Suivez les instructions pour installer manuellement le Kit de développement logiciel (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 pour l'appendice approprié. Ajoutez le fichier jar appender téléchargé au projet.

Ajouter l’appender à votre infrastructure de journalisation

Pour commencer à obtenir des traces, 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 ajouts Application Insights peuvent être référencés par n’importe quel enregistreur d’événements configuré et pas nécessairement par l’enregistreur d’événements racine, comme indiqué dans les exemples de code précédents.

Explorer vos traces dans le portail Application Insights

Maintenant que vous avez configuré votre projet pour envoyer des traces à Application Insights, vous pouvez afficher et rechercher ces traces dans le portail Application Insights dans le volet De recherche .

Les exceptions soumises via les loggers s’affichent sur le portail comme télémétrie Exception.

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

Si vous avez instrumenté votre application web Java avec le Kit de développement logiciel (SDK) Application Insights, vous pouvez utiliser l’agent Java pour obtenir des insights plus approfondis, sans aucune modification du code :

• Dépendances : données sur les appels effectués par votre application à d’autres composants, notamment :

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

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

  • Log4j 1.2
  • Log4j2
  • Logback

• Meilleur nommage des opérations : utilisé pour l’agrégation des requêtes dans le portail.

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

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

Installer l’agent Application Insights pour Java

1. Sur la machine exécutant votre serveur Java, téléchargez l’agent 2.x. Vérifiez que la version de l’agent Java 2.x que vous utilisez correspond à la version du SDK Java 2.x Application Insights que vous utilisez.

2. Modifiez le script de démarrage du serveur d’applications et 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>

Configurations supplémentaires (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>de l’application.

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

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

   L’agent doit être empaqueté en tant que ressource dans votre projet afin qu’il se termine dans le répertoire D :/home/site/wwwroot/ . Pour vérifier que votre agent se trouve dans le répertoire App Service approprié, accédez à Laconsole Debug>> et examinez le contenu du répertoire de site.

3. Enregistrez les paramètres, puis redémarrez votre application. Ces étapes s’appliquent uniquement aux services d’application s’exécutant sur Windows.

Activer le suivi distribué W3C

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

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

Assurez-vous que les configurations entrantes et sortantes (agent) sont exactement identiques.

Afficher les données

Dans la ressource Application Insights, les durées d’exécution agrégées des dépendances et des méthodes distantes apparaissent sous la vignette Performances.

Pour rechercher des instances individuelles de rapports de dépendance, d’exception et de méthode, ouvrez La recherche.

En savoir plus sur la façon de diagnostiquer les problèmes de dépendance.

Questions ou problèmes ?

Utilisez les ressources suivantes :

• Aucune donnée ? Définissez des exceptions de pare-feu.
• Résolvez les problèmes liés à Java.

Filtrer les données de télémétrie dans votre application web Java

Les filtres permettent de sélectionner les données de télémétrie envoyées par votre application web Java à Application Insights. Il existe des filtres prêtes à l’emploi que vous pouvez utiliser. Vous pouvez également écrire vos propres filtres personnalisés.

Les filtres prêts à l'emploi sont les suivants :

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

Définir des filtres

Dans ApplicationInsights.xml, ajoutez une TelemetryProcessors section semblable à cet exemple :

    <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 de processeurs intégrés.

Filtres intégrés

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

Filtre de télémétrie des métriques

           <Processor type="MetricTelemetryFilter">
                  <Add name="NotNeeded" value="metric1,metric2"/>
           </Processor>

• NotNeeded: Liste séparée par des virgules des noms de métriques personnalisés

Filtre de 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 fait référence au temps nécessaire pour charger la page. Si ce paramètre est défini, les pages chargées plus rapidement que cette fois ne sont pas signalées.
• NotNeededNames: liste séparée par des virgules des noms de page.
• NotNeededUrls: liste séparée par des virgules de fragments d’URL. Par exemple, "home" filtre toutes les pages qui ont « accueil » dans l’URL.

Filtre de requête de télémétrie

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

Filtre source synthétique

Filtre toutes les données de télémétrie qui ont des valeurs dans la SyntheticSource propriété. Les demandes des bots, des araignées et des tests de disponibilité sont incluses.

Filtre les données de télémétrie pour toutes les requêtes synthétiques :

           <Processor type="SyntheticSourceFilter" />

Filtre les données de télémétrie pour des 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 sources synthétiques

Filtre d’é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 de télémétrie de trace

Filtre les traces des journaux journalisées à l’aide de TrackTrace() ou d’un collecteur de cadre de journalisation :

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

• Les FromSeverityLevel valeurs valides sont les suivantes :

  • OFF : filtre toutes les traces.
  • TRACE : Aucun filtrage. Est égal au niveau TRACE.
  • INFO : filtre le niveau TRACE.
  • AVERTISSEMENT : filtre TRACE et INFO.
  • ERREUR : filtre les AVERTISSEMENTS, INFORMATIONS et TRACES.
  • CRITIQUE : filtre tout sauf CRITIQUE.

Filtres personnalisés

Les sections suivantes vous montrent les étapes à suivre pour créer vos propres filtres personnalisés.

Coder 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

Maintenant, 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és doivent être inscrits dans votre classe d’application principale en tant que bean. Elles seront ensuite déclenchées 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

Cette section propose un conseil de résolution des problèmes.

Mon filtre ne fonctionne pas

Vérifiez que vous avez fourni des valeurs de paramètre valides. Par exemple, les durées doivent être des entiers. Les valeurs non valides entraîneront l’ignorance du filtre. Si votre filtre personnalisé lève une exception d’un constructeur ou d’une méthode set, elle sera ignorée.

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

Pour explorer les métriques de performances du système Linux dans Application Insights, installez collectd ensemble avec son plug-in Application Insights. Cette solution open source collecte diverses statistiques système et réseau.

En règle générale, vous allez utiliser collectd si vous avez déjà instrumenté votre service web Java avec Application Insights. Il vous donne plus de données pour vous aider à améliorer les performances de votre application ou à diagnostiquer les problèmes.

Obtenir votre clé d’instrumentation

Dans le portail Azure, ouvrez la ressource Application Insights dans laquelle vous souhaitez que les données apparaissent. Vous pouvez également créer une ressource.

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

Installer collectd et ses plug-ins

Sur vos machines serveur Linux :

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

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

   • Mettez à jour JVMArg pour java.class.path afin d'inclure le fichier jar suivant. Mettez à jour le numéro de version pour 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 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 collectés, qui peuvent collecter différentes données à partir de différentes sources.

Redémarrez collectd conformément à son manuel.

Afficher les données dans Application Insights

Dans votre ressource Application Insights, ouvrez Métriques et ajoutez des graphiques. Sélectionnez les métriques que vous souhaitez afficher dans la catégorie Personnalisée .

Par défaut, les métriques sont agrégées sur toutes les machines hôtes à partir desquelles les métriques ont été collectées. Pour afficher les métriques par hôte, dans le volet Détails du graphique , activez le regroupement, puis choisissez de regrouper par CollectD-Host.

Exclure le 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 activés collectd read .

Pour exclure les données de plug-ins ou de sources de données spécifiques :

• Modifiez le fichier de configuration.

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

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

Séparez les directives avec un saut de ligne.

Problèmes?

Cette section propose des conseils de dépannage.

Je ne vois pas de données dans le portail

Essayez ces options :

• Ouvrez La recherche pour voir si les événements bruts sont arrivés. Parfois, ils prennent plus de temps pour 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 cette ligne dans <Plugin ApplicationInsightsWriter>:
  • SDKLogger true
• Ouvrez un terminal et démarrez collectd en mode détaillé pour voir les problèmes qu’il signale :
  • sudo collectd -f

Problème connu

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

• Symptôme : Le collectd journal affiche des erreurs qui incluent « IA : ... SyntaxError : symbole inattendu N. »
• Solution de contournement : exclure les données collectées par le plug-in d'écriture lié au problème.

Utiliser Micrometer avec le Kit de développement logiciel (SDK) Java Application Insights (non recommandé)

La surveillance des applications avec Micrometer mesure les métriques du code d’application basé sur JVM et vous permet d’exporter les données vers vos systèmes de surveillance préférés. Cette section explique comment utiliser Micrometer avec Application Insights pour les applications Spring Boot et non-Spring Boot.

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

Suivez ces étapes :

1. Mettez à jour le fichier pom.xml de votre application Spring Boot et ajoutez 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. Générez votre application et exécutez-la.

Les étapes précédentes doivent vous aider à utiliser les métriques pré-agrégées automatiquement récupérées dans Azure Monitor.

Utiliser Spring 2.x

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

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

Suivez ces étapes :

1. Mettez à jour le fichier pom.xml de votre application Spring Boot et ajoutez 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. Générez votre application et exécutez-la.

Les étapes précédentes doivent vous permettre d’exécuter des métriques pré-agrégées automatiquement dans Azure Monitor. Pour plus d’informations sur la façon d’affiner le starter Application Insights Spring Boot, consultez le README sur GitHub.

Métriques par défaut :

• Métriques configurées automatiquement pour Tomcat, JVM, Logback Metrics, Log4J Metrics, Uptime Metrics, Processor Metrics et FileDescriptorMetrics.
• Par exemple, si Netflix Hystrix est présent sur le classpath, nous obtenons également ces métriques.
• Les métriques suivantes peuvent être disponibles en ajoutant les haricots respectifs :
  • CacheMetrics (CaffeineCache, , EhCache2, GuavaCache, HazelcastCacheet JCache)
  • DataBaseTableMetrics
  • HibernateMetrics
  • JettyMetrics
  • OkHttp3 Métrique
  • Kafka Métrique

Désactivez la collecte automatique des métriques :

• Métriques JVM :
  • management.metrics.binders.jvm.enabled=false
• Métriques de journalisation :
  • management.metrics.binders.logback.enabled=false
• Métriques de temps d’activité :
  • management.metrics.binders.uptime.enabled=false
• Métriques du processeur :
  • management.metrics.binders.processor.enabled=false
• FileDescriptorMetrics :
  • management.metrics.binders.files.enabled=false
• Métriques Hystrix si la bibliothèque est activée classpath:
  • management.metrics.binders.hystrix.enabled=false
• Métriques AspectJ si la bibliothèque est présente sur classpath:
  • spring.aop.enabled=false

Utiliser Micrometer avec des applications web autres que Spring Boot

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

• Application Insights Web Auto 2.5.0 ou version ultérieure
• Micrometer Azure Registry 1.1.0 ou version ultérieure
• Ressource Application Insights

Suivez ces étapes :

1. Ajoutez les dépendances suivantes dans 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 ressources. Pour plus d’informations, consultez Ajouter un fichier ApplicationInsights.xml.

3. Exemple de classe Servlet (une métrique du minuteur est émise) :

       @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 en savoir plus sur les métriques, consultez la documentation Micrometer.

Vous trouverez d’autres exemples de code sur la création de différents types de métriques dans le dépôt GitHub de Micrometer officiel.

Intégrer davantage la collecte de métriques

Les sections suivantes vous montrent comment collecter plus de métriques.

SpringBoot/Spring

Créez un bean de la catégorie métrique respective. Par exemple, disons que vous ayez besoin des métriques de Guava Cache :

    @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 une liste complète, consultez le dépôt GitHub Micrometer.

Applications en dehors de Spring

Ajoutez le code de liaison suivant au fichier de configuration :

    New GuavaCacheMetrics().bind(registry);

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

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

Résumé de l’API

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

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

Prerequisites

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

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

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

  import com.microsoft.applicationinsights.TelemetryClient;
  

Obtenir une instance TelemetryClient

Obtenir une instance de TelemetryClient:

private TelemetryClient telemetry = new TelemetryClient();

TelemetryClient est thread sécurisé.

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

telemetry.getContext().getUser().setId("...");
telemetry.getContext().getDevice().setId("...");

TrackEvent

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

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

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

telemetry.trackEvent("WinGame");

Événements personnalisés dans Log Analytics

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

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

TrackMetric

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

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

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

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

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

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

Exemples de valeurs uniques

Pour envoyer une valeur de métrique unique :

telemetry.trackMetric("queueLength", 42.0);

Métriques personnalisées dans Log Analytics

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

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

Affichages de page

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

Les données utilisateur et session sont envoyées en tant que propriétés, ainsi que les vues de page, de sorte que les graphiques utilisateur et de session sont actifs lorsqu’il existe des données de télémétrie d’affichage de page.

Affichages de pages personnalisés

telemetry.trackPageView("GameReviewPage");

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

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

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

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

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

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

pageViews
| summarize count() by client_Browser

Pour associer des vues de page aux appels AJAX, associez avec les dépendances :

pageViews
| join (dependencies) on operation_Id

TrackRequest

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

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

La méthode recommandée pour envoyer des données de télémétrie de requête consiste à traiter la requête comme un contexte d'opération.

Contexte d’opération

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

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

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

Demandes dans Log Analytics

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

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

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

TrackException

Envoyer des exceptions à Application Insights :

• Pour les compter, comme indication de la fréquence d’un problème.
• Pour examiner les occurrences individuelles.

Les rapports incluent les traces de pile.

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

Les exceptions sont interceptées automatiquement. Vous n’avez donc pas toujours besoin d’appeler TrackException explicitement.

Exceptions dans Log Analytics

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

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

exceptions
| summarize sum(itemCount) by type

La majeure partie des informations importantes de la pile sont déjà extraites dans des variables distinctes, mais vous pouvez décomposer la details structure pour obtenir davantage d'informations. Étant donné que cette structure est dynamique, vous devez convertir le résultat en type attendu. Par exemple:

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

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

exceptions
| join (requests) on operation_Id

TrackTrace

Utilisez TrackTrace pour diagnostiquer les problèmes en envoyant un « fil d'Ariane » à Application Insights. Vous pouvez envoyer des blocs de données de diagnostic et les inspecter dans La recherche de diagnostic.

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

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

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

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

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

Map<String, Integer> properties = new HashMap<>();
properties.put("Database", db.ID);
telemetry.trackTrace("Slow Database response", SeverityLevel.Warning, properties);

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

Traces dans Log Analytics

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

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

TrackDependency

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

boolean success = false;
Instant startTime = Instant.now();
try {
    success = dependency.call();
}
finally {
    Instant endTime = Instant.now();
    Duration delta = Duration.between(startTime, endTime);
    RemoteDependencyTelemetry dependencyTelemetry = new RemoteDependencyTelemetry("My Dependency", "myCall", delta, success);
    dependencyTelemetry.setTimeStamp(startTime);
    telemetry.trackDependency(dependencyTelemetry);
}

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

Dépendances dans Log Analytics

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

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

dependencies
| summarize sum(itemCount) by target

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

dependencies
| join (requests) on operation_Id

Vidage des données

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

telemetry.flush();
//Allow some time for flushing before shutting down
Thread.sleep(5000);

Utilisateurs authentifiés

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

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

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

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

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

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

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

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

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

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

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

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

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

Map<String, String> properties = new HashMap<String, String>();
properties.put("game", currentGame.getName());
properties.put("difficulty", currentGame.getDifficulty());

Map<String, Double> metrics = new HashMap<String, Double>();
metrics.put("Score", currentGame.getScore());
metrics.put("Opponents", currentGame.getOpponentCount());

telemetry.trackEvent("WinGame", properties, metrics);

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

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

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

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

Notez que :

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

Événements de chronométrage

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

long startTime = System.currentTimeMillis();

// Perform timed action

long endTime = System.currentTimeMillis();
Map<String, Double> metrics = new HashMap<>();
metrics.put("ProcessingTime", (double)endTime-startTime);

// Setup some properties
Map<String, String> properties = new HashMap<>();
properties.put("signalSource", currentSignalSource.getName());

// Send the event
telemetry.trackEvent("SignalProcessed", properties, metrics);

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

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

import com.microsoft.applicationinsights.TelemetryClient;
import com.microsoft.applicationinsights.TelemetryContext;
...

TelemetryClient gameTelemetry = new TelemetryClient();
TelemetryContext context = gameTelemetry.getContext();
context.getProperties().put("Game", currentGame.Name);

gameTelemetry.TrackEvent("WinGame");

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

Désactiver la télémétrie

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

telemetry.getConfiguration().setTrackingDisabled(true);

Chaîne de connexion dynamique

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

Au lieu d’obtenir la chaîne de connexion à partir du fichier de configuration, vous pouvez la définir dans la méthode d’initialisation de votre code :

// Initialize once, e.g., at startup
TelemetryClient telemetry = new TelemetryClient();

// Prefer env var; falls back to hard-coded for illustration
String cs = System.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING");
if (cs != null && !cs.isEmpty()) {
    telemetry.getContext().setConnectionString(cs);
}

TelemetryContext

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

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

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

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

Limites

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

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

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

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

Étapes suivantes

• Ajoutez la surveillance à vos pages web pour surveiller les temps de chargement des pages, les appels AJAX et les exceptions de navigateur.
• Écrivez des données de télémétrie personnalisées pour suivre l’utilisation dans le navigateur ou sur le serveur.
• Utilisez Log Analytics pour des requêtes puissantes sur la télémétrie à partir de votre application.
• Utilisez la recherche de diagnostic.
• Envisagez l’échantillonnage comme alternative au filtrage qui n’asymétrie pas vos métriques.
• Pour en savoir plus sur Micrometer, consultez la documentation Micrometer.
• Pour en savoir plus sur Spring sur Azure, consultez la documentation Spring sur Azure.
• Pour plus d’informations, consultez Azure pour les développeurs Java.