Démarrage rapide : Prise en main d'Application Insights dans un projet web JavaQuickstart: Get started with Application Insights in a Java web project

Dans ce démarrage rapide, vous utilisez Application Insights pour instrumenter automatiquement des requêtes, effectuer le suivi des dépendances, recueillir 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.In this quickstart, you use Application Insights to automatically instrument request, track dependencies, and collect performance counters, diagnose performance issues and exceptions, and write code to track what users do with your app.

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 is an extensible analytics service for web developers that helps you understand the performance and usage of your live application. Application Insights prend en charge les applications Java exécutées sur Linux, Unix ou Windows.Application Insights supports Java apps running on Linux, Unix, or Windows.

Conditions préalables requisesPrerequisites

Obtenir une clé d'instrumentation Application InsightsGet an Application Insights instrumentation key

  1. Connectez-vous au portail Azure.Sign in to the Azure portal.

  2. Dans le Portail Azure, créez une ressource Application Insights.In the Azure portal, create an Application Insights resource. Définissez le type d’application sur Application web Java.Set the application type to Java web application.

  3. Obtenez la clé d'instrumentation de la nouvelle ressource.Find the instrumentation key of the new resource. Vous devrez la coller rapidement dans le code de votre projet.You'll need to paste this key into your code project shortly.

    Dans la nouvelle vue d'ensemble des ressources, cliquez sur Propriétés et copiez la clé d'instrumentation.

Ajoutez le Kit de développement logiciel (SDK) Application Insights pour Java à votre projetAdd the Application Insights SDK for Java to your project

Choisissez votre type de projet.Choose your project type.

Si votre projet est déjà configuré pour être généré avec Maven, fusionnez le code suivant dans votre fichier pom.xml.If your project is already set up to use Maven for build, merge the following code to your pom.xml file.

Actualisez ensuite les dépendances du projet pour télécharger les fichiers binaires.Then, refresh the project dependencies to get the binaries downloaded.

    <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.5.0</version>
      </dependency>
    </dependencies>

QuestionsQuestions

  • Quelle est la relation entre les composants -web-auto, -web et -core ?What's the relationship between the -web-auto, -web and -core components?

    • applicationinsights-web-auto fournit des métriques qui effectuent le suivi du nombre de demandes servlet HTTP et des temps de réponse, en inscrivant automatiquement le filtre servlet Application Insights au moment de l’exécution.applicationinsights-web-auto gives you metrics that track HTTP servlet request counts and response times, by automatically registering the Application Insights servlet filter at runtime.
    • applicationinsights-web fournit également des métriques qui effectuent le suivi du nombre de demandes HTTP servlet et des temps de réponse, mais nécessite une inscription manuelle du filtre de servlet Application Insights dans votre application.applicationinsights-web also gives you metrics that track HTTP servlet request counts and response times, but requires manual registration of the Application Insights servlet filter in your application.
    • applicationinsights-core vous offre uniquement l’API seule, par exemple si votre application n’est pas basée sur un servlet.applicationinsights-core gives you just the bare API, for example, if your application isn't servlet-based.
  • Comment dois-je mettre à jour le Kit de développement logiciel (SDK) vers la dernière version ?How should I update the SDK to the latest version?

Ajouter un fichier ApplicationInsights.xmlAdd an ApplicationInsights.xml file

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.Add ApplicationInsights.xml to the resources folder in your project, or make sure it's added to your project’s deployment class path. Copiez-y le code XML suivant.Copy the following XML into it.

Remplacez la clé d’instrumentation par celle que vous avez obtenue sur le Portail Azure.Replace the instrumentation key with the one that you got from the Azure portal.

<?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.Optionally, the configuration file can be in any location accessible to your application. La propriété système -Dapplicationinsights.configurationDirectory spécifie le répertoire qui contient le fichier ApplicationInsights.xml.The system property -Dapplicationinsights.configurationDirectory specifies the directory that contains 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".For example, a configuration file located at E:\myconfigs\appinsights\ApplicationInsights.xml would be configured with the property -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.The instrumentation key is sent along with every item of telemetry and tells Application Insights to display it in your resource.
  • Le composant de demande HTTP est facultatif.The HTTP Request component is optional. Il envoie automatiquement la télémétrie concernant les demandes et les temps de réponse au portail.It automatically sends telemetry about requests and response times to the portal.
  • La corrélation des événements est un complément au composant de requête HTTP.Event correlation is an addition to the HTTP request component. Elle assigne un identificateur à chaque requête reçue par le serveur.It assigns an identifier to each request received by the server. Elle ajoute ensuite cet identificateur en tant que propriété à chaque élément de télémétrie comme propriété « Operation.Id ».It then adds this identifier as a property to every item of telemetry as the property 'Operation.Id'. Il vous permet de mettre en corrélation la télémétrie associée à chaque demande en définissant un filtre dans recherche de diagnostic.It allows you to correlate the telemetry associated with each request by setting a filter in diagnostic search.

Autres méthodes pour définir la clé d’instrumentationAlternative ways to set the instrumentation key

Le kit de développement logiciel (SDK) d’Application Insights recherche la clé dans cet ordre :Application Insights SDK looks for the key in this order:

  1. Propriété système : -DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikeySystem property: -DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikey
  2. Variable d’environnement : APPINSIGHTS_INSTRUMENTATIONKEYEnvironment variable: APPINSIGHTS_INSTRUMENTATIONKEY
  3. Configuration de l'application : ApplicationInsights.xmlConfiguration file: ApplicationInsights.xml

Vous pouvez également définir la clé dans le code:You can also set it in code:

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

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

Ajouter un agentAdd agent

Installez l’agent Java pour capturer les appels HTTP sortants, les requêtes JDBC, la journalisation des applications et une meilleure appelation des opérations.Install the Java Agent to capture outgoing HTTP calls, JDBC queries, application logging, and better operation naming.

Exécuter votre applicationRun your application

Exécutez-le en mode débogage sur votre ordinateur de développement, ou publiez-le sur votre serveur.Either run it in debug mode on your development machine, or publish to your server.

Voir votre télémétrie dans Application InsightsView your telemetry in Application Insights

Revenez à votre ressource Application Insights sur le portail Microsoft Azure.Return to your Application Insights resource in Microsoft Azure portal.

Les données des demandes HTTP apparaissent dans le panneau Vue d’ensemble.HTTP requests data appears on the overview blade. (Si elles n’y sont pas, attendez quelques secondes et cliquez sur Actualiser).(If it isn't there, wait a few seconds and then click Refresh.)

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

En savoir plus sur les mesures.Learn more about metrics.

Cliquez sur un des graphiques pour afficher des métriques agrégées plus détaillées.Click through any chart to see more detailed aggregated metrics.

Volet Échecs d’Application Insights avec des graphiques

Données d’instanceInstance data

Cliquez sur un type de demande spécifique pour afficher les instances individuelles.Click through a specific request type to see individual instances.

Explorer un exemple de vue spécifique

Analytics : Tirez parti d’un puissant langage de requête.Analytics: Powerful query language

En accumulant toujours plus de données, vous pouvez exécuter des requêtes à la fois pour agréger les données et pour rechercher des instances individuelles.As you accumulate more data, you can run queries both to aggregate data and to find individual instances. Analytics est un outil puissant qui permet non seulement de comprendre les performances et l’utilisation, mais également d’effectuer des diagnostics.Analytics is a powerful tool for both for understanding performance and usage, and for diagnostic purposes.

Exemple d’Analytics

7. Installer votre application sur le serveur7. Install your app on the server

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.Now publish your app to the server, let people use it, and watch the telemetry show up on the portal.

  • Assurez-vous que votre pare-feu autorise votre application à envoyer les données de télémétrie vers ces ports :Make sure your firewall allows your application to send telemetry to these ports:

    • dc.services.VisualStudio.com:443dc.services.visualstudio.com:443
    • f5.services.visualstudio.com:443f5.services.visualstudio.com:443
  • Si le trafic sortant doit être acheminé via un pare-feu, définissez les propriétés système http.proxyHost et http.proxyPort.If outgoing traffic must be routed through a firewall, define system properties http.proxyHost and http.proxyPort.

  • Sur les serveurs Windows, installez :On Windows servers, install:

Configuration d’Azure App Service (Spring Boot)Azure App Service config (Spring Boot)

Les applications Spring Boot qui s’exécutent sur Windows nécessitent une configuration supplémentaire pour s’exécuter sur Azure App Services.Spring Boot apps running on Windows require additional configuration to run on Azure App Services. Modifiez le fichier web.config et ajoutez la configuration suivante :Modify web.config and add the following configuration:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified"/>
        </handlers>
        <httpPlatform processPath="%JAVA_HOME%\bin\java.exe" arguments="-Djava.net.preferIPv4Stack=true -Dserver.port=%HTTP_PLATFORM_PORT% -jar &quot;%HOME%\site\wwwroot\AzureWebAppExample-0.0.1-SNAPSHOT.jar&quot;">
        </httpPlatform>
    </system.webServer>
</configuration>

Exceptions et échecs de requêtesExceptions and request failures

Les exceptions non prises en charge et les échecs de demande sont collectés automatiquement par le filtre web Application Insights.Unhandled exceptions and request failures are automatically collected by the Application Insights web filter.

Pour collecter des données sur d’autres exceptions, vous pouvez insérer des appels à trackException() dans votre code.To collect data on other exceptions, you can insert calls to trackException() in your code.

Surveiller les appels de méthode et les dépendances externesMonitor method calls and external dependencies

Installez l’agent Java pour journaliser les méthodes internes spécifiées et les appels effectués via JDBC, avec des données de minutage.Install the Java Agent to log specified internal methods and calls made through JDBC, with timing data.

Et pour l’appellation automatique des opérations.And for automatic operation naming.

Traçage distribué W3CW3C distributed tracing

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

La configuration entrante du SDK est expliquée plus en détail dans notre article consacré à la corrélation.The incoming SDK configuration is explained further in our article on correlation.

La configuration sortante du SDK est définie dans le fichier AI-Agent.xml.Outgoing SDK configuration is defined in the AI-Agent.xml file.

Compteurs de performancePerformance counters

Ouvrez Examiner, Métriques afin d’afficher un ensemble de compteurs de performances.Open Investigate, Metrics, to see a range of performance counters.

Capture d’écran du volet Métriques avec les octets privés du processus sélectionnés

Personnaliser la collecte des compteurs de performancesCustomize performance counter collection

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 :To disable collection of the standard set of performance counters, add the following code under the root node of the ApplicationInsights.xml file:

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

Collecter des compteurs de performances supplémentairesCollect additional performance counters

Vous pouvez spécifier d'autres compteurs de performances à collecter.You can specify additional performance counters to be collected.

Compteurs JMX (exposés par la machine virtuelle Java)JMX counters (exposed by the Java Virtual Machine)

    <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.displayName – The name displayed in the Application Insights portal.
  • objectName : nom de l'objet JMX.objectName – The JMX object name.
  • attribute attribut du nom d'objet JMX à récupérerattribute – The attribute of the JMX object name to fetch
  • type (facultatif) : type d'attribut d'objet JMX :type (optional) - The type of JMX object’s attribute:
    • Par défaut : un type simple, comme int ou long.Default: a simple type such as int or long.
    • composite: les données du compteur de performances sont au format « Attribute.Data »composite: the perf counter data is in the format of 'Attribute.Data'
    • tabular: les données du compteur de performances sont au format ligne de tableautabular: the perf counter data is in the format of a table row

Compteurs de performances WindowsWindows performance counters

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).Each Windows performance counter is a member of a category (in the same way that a field is a member of a class). Les catégories peuvent être globales ou peuvent avoir des instances numérotées ou nommées.Categories can either be global, or can have numbered or named instances.

    <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.displayName – The name displayed in the Application Insights portal.
  • categoryName : catégorie du compteur de performances (objet de performances) à laquelle ce compteur de performances est associé.categoryName – The performance counter category (performance object) with which this performance counter is associated.
  • counterName : nom du compteur de performances.counterName – The name of the performance counter.
  • instanceName : nom de l'instance de catégorie de compteur de performances ou une chaîne vide ("") si la catégorie contient une seule instance.instanceName – The name of the performance counter category instance, or an empty string (""), if the category contains a single instance. Si categoryName est Process et que le compteur de performance que vous souhaitez collecter vient du processus en cours de la JVM sur laquelle votre application s'exécute, spécifiez "__SELF__".If the categoryName is Process, and the performance counter you'd like to collect is from the current JVM process on which your app is running, specify "__SELF__".

Compteurs de performances UnixUnix performance counters

Obtenir des données utilisateur et de sessionGet user and session data

Vous envoyez des données de télémétrie depuis votre serveur web.OK, you're sending telemetry from your web server. Vous pouvez désormais ajouter plus de surveillance pour obtenir une vue à 360 degrés de votre application :Now to get the full 360-degree view of your application, you can add more monitoring:

Envoyer votre propre télémétrieSend your own telemetry

Maintenant que vous avez installé le Kit de développement logiciel (SDK), vous pouvez utiliser l'API pour envoyer votre propre télémétrie.Now that you've installed the SDK, you can use the API to send your own telemetry.

Tests web de disponibilitéAvailability web tests

Application Insights peut tester votre site web à intervalles réguliers pour vérifier qu’il fonctionne et répond correctement.Application Insights can test your website at regular intervals to check that it's up and responding well.

En savoir plus sur la configuration des tests web de disponibilité.Learn more about how to set up availability web tests.

Des questions ?Questions? Des problèmes ?Problems?

Résolution des problèmes JavaTroubleshooting Java

Étapes suivantesNext steps