Introduzione ad Application Insights in un progetto Web JavaGet started with Application Insights in a Java web project

Application Insights è un servizio di analisi estendibile per gli sviluppatori Web che semplifica la comprensione delle prestazioni e dell'uso dell'applicazione live.Application Insights is an extensible analytics service for web developers that helps you understand the performance and usage of your live application. È possibile usarlo per instrumentare automaticamente le richieste, tenere traccia delle dipendenze e raccogliere i contatori delle prestazioni, diagnosticare problemi di prestazioni ed eccezioni e scrivere codice per tenere traccia delle operazioni eseguite dagli utenti con l'app.Use it 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.

Screenshot dei dati di esempio della panoramica

Application Insights supporta le app Java in esecuzione in Linux, Unix o Windows.Application Insights supports Java apps running on Linux, Unix, or Windows.

Sono necessari:You need:

1. ottenere una chiave di strumentazione Application Insights1. Get an Application Insights instrumentation key

  1. Accedere al portale di Microsoft Azure.Sign in to the Microsoft Azure portal.

  2. Creare una risorsa di Application Insights.Create an Application Insights resource. Impostare il tipo di applicazione nell'applicazione Web Java.Set the application type to Java web application.

  3. Ottenere la chiave di strumentazione della nuova risorsa.Find the instrumentation key of the new resource. Questa chiave dovrà a breve essere incollata nel progetto di codice.You'll need to paste this key into your code project shortly.

    Nella panoramica della nuova risorsa, fare clic su Proprietà e copiare la chiave di strumentazione

2. aggiungere il Application Insights SDK per Java al progetto2. Add the Application Insights SDK for Java to your project

Scegliere il modo più appropriato per il progetto.Choose the appropriate way for your project.

Se si usa Maven: If you're using Maven...

Se il progetto è già stato configurato per usare Maven per la compilazione, unire il codice seguente al file pom.xml.If your project is already set up to use Maven for build, merge the following code to your pom.xml file.

Aggiornare quindi le dipendenze progetto per fare in modo che i file binari vengano scaricati.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>

Se si usa Gradle: If you're using Gradle...

Se il progetto è già stato configurato per usare Gradle per la compilazione, unire il codice seguente al file build.gradle.If your project is already set up to use Gradle for build, merge the following code to your build.gradle file.

Aggiornare quindi le dipendenze progetto per fare in modo che i file binari vengano scaricati.Then refresh the project dependencies to get the binaries downloaded.

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

In caso contrario, se le dipendenze vengono gestite manualmente:Otherwise, if you are manually managing dependencies ...

Scaricare la versione più recente e copiare i file necessari nel progetto, sostituendo tutte le versioni precedenti.Download the latest version and copy the necessary files into your project, replacing any previous versions.

Domande...Questions...

  • Qual è la relazione tra i componenti -web-auto, -web e -core?What's the relationship between the -web-auto, -web and -core components?

    • applicationinsights-web-auto fornisce metriche che tengono traccia dei conteggi delle richieste di servlet HTTP e dei tempi di risposta, registrando automaticamente il filtro del servlet Application Insights in fase di esecuzione.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 fornisce anche le metriche per tenere traccia dei conteggi delle richieste di servlet HTTP e dei tempi di risposta, ma richiede la registrazione manuale del filtro Application Insights servlet nell'applicazione.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 offre solo l'API bare, ad esempio se l'applicazione non è basata su servlet.applicationinsights-core gives you just the bare API, for example, if your application is not servlet-based.
  • Come si esegue l'aggiornamento alla versione più recente dell'SDK?How should I update the SDK to the latest version?

    • Se si usa Gradle o Maven:If you are using Gradle or Maven...
      • Aggiornare il file di compilazione per specificare la versione più recente.Update your build file to specify the latest version.
    • Se le dipendenze vengono gestite manualmente:If you are manually managing dependencies...

3. aggiungere un file ApplicationInsights. XML3. Add an ApplicationInsights.xml file

Aggiungere ApplicationInsights.xml alla cartella resources del progetto oppure verificare che sia stato aggiunto al percorso della classe di distribuzione del progetto.Add ApplicationInsights.xml to the resources folder in your project, or make sure it is added to your project’s deployment class path. Copiarvi il seguente file XML.Copy the following XML into it.

Sostituire la chiave di strumentazione recuperata dal portale di Azure.Substitute the instrumentation key 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>

Il file di configurazione può risiedere in qualsiasi percorso accessibile all'applicazione.Optionally, the configuration file can reside in any location accessible to your application. La proprietà di sistema -Dapplicationinsights.configurationDirectory specifica la directory contenente il file ApplicationInsights.xml.The system property -Dapplicationinsights.configurationDirectory specifies the directory that contains ApplicationInsights.xml. Ad esempio, un file di configurazione con percorso E:\myconfigs\appinsights\ApplicationInsights.xml verrà configurato con la proprietà -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 chiave di strumentazione viene inviata insieme a tutti gli elementi di dati di telemetria e indica ad Application Insights di visualizzarla nella risorsa.The instrumentation key is sent along with every item of telemetry and tells Application Insights to display it in your resource.
  • Il componente delle richieste HTTP è facoltativo.The HTTP Request component is optional. Invia automaticamente i dati di telemetria sulle richieste e tempi di risposta al portale.It automatically sends telemetry about requests and response times to the portal.
  • La correlazione di eventi è un'aggiunta al componente delle richieste HTTP.Event correlation is an addition to the HTTP request component. Assegna un identificatore a ogni richiesta ricevuta dal server e lo aggiunge come proprietà a ogni elemento di telemetria, come proprietà "Operation.Id".It assigns an identifier to each request received by the server, and adds this identifier as a property to every item of telemetry as the property 'Operation.Id'. Consente di correlare i dati di telemetria associati a ogni richiesta impostando un filtro in Ricerca diagnostica.It allows you to correlate the telemetry associated with each request by setting a filter in diagnostic search.

Modi alternativi per impostare la chiave di strumentazioneAlternative ways to set the instrumentation key

Application Insights SDK cerca la chiave nell'ordine seguente.Application Insights SDK looks for the key in this order:

  1. Proprietà di sistema:-DAPPINSIGHTS_INSTRUMENTATIONKEY = iKeySystem property: -DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikey
  2. Variabile di ambiente: APPINSIGHTS_INSTRUMENTATIONKEYEnvironment variable: APPINSIGHTS_INSTRUMENTATIONKEY
  3. File di configurazione: ApplicationInsights.xmlConfiguration file: ApplicationInsights.xml

È anche possibile eseguirne l' impostazione nel codice:You can also set it in code:

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

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

4. Aggiungi agente4. Add agent

Installare l'agente Java per acquisire le chiamate http in uscita, le query JDBC, la registrazione delle applicazioni e una migliore denominazione delle operazioni.Install the Java Agent to capture outgoing HTTP calls, JDBC queries, application logging, and better operation naming.

5. eseguire l'applicazione5. Run your application

Eseguire l'applicazione in modalità debug nel computer di distribuzione oppure pubblicarla nel server.Either run it in debug mode on your development machine, or publish to your server.

6. visualizzare i dati di telemetria in Application Insights6. View your telemetry in Application Insights

Tornare alla risorsa di Application Insights nel portale di Microsoft Azure.Return to your Application Insights resource in Microsoft Azure portal.

Nel pannello di panoramica vengono visualizzati i dati delle richieste HTTP.HTTP requests data appears on the overview blade. Se non sono visualizzati, attendere alcuni secondi e quindi fare clic su Aggiorna.(If it isn't there, wait a few seconds and then click Refresh.)

Screenshot dei dati di esempio della panoramica

Altre informazioni sulle metriche.Learn more about metrics.

Fare clic su qualsiasi grafico per visualizzare metriche aggregate più dettagliate.Click through any chart to see more detailed aggregated metrics.

Riquadro Errori Application Insights con grafici

Dati dell'istanzaInstance data

Fare clic su un tipo di richiesta specifico per visualizzare le singole istanze.Click through a specific request type to see individual instances.

Esaminare una visualizzazione di esempio specifica

Analytics: linguaggio di query avanzatoAnalytics: Powerful query language

Quando si accumulano molti dati, è possibile eseguire query per aggregare i dati e per individuare istanze singole.As you accumulate more data, you can run queries both to aggregate data and to find individual instances. Analisi è uno strumento avanzato per ottenere informazioni sulle prestazioni e sull'utilizzo e ai fini della diagnostica.Analytics is a powerful tool for both for understanding performance and usage, and for diagnostic purposes.

Esempio di Analytics

7. installare l'app nel server7. Install your app on the server

A questo punto è possibile pubblicare l'applicazione nel server, permettere agli utenti di utilizzarla e visualizzare la telemetria mostrata nel portale.Now publish your app to the server, let people use it, and watch the telemetry show up on the portal.

  • Verificare che il firewall consenta all'applicazione di inviare i dati di telemetria a queste porte: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
  • Se il traffico in uscita deve essere instradato attraverso un firewall, definire le proprietà di sistema http.proxyHost e http.proxyPort.If outgoing traffic must be routed through a firewall, define system properties http.proxyHost and http.proxyPort.

  • Nei server Windows installare:On Windows servers, install:

Configurazione del servizio app Azure (Spring boot)Azure App Service config (Spring Boot)

Le app Spring boot eseguite in Windows richiedono una configurazione aggiuntiva per l'esecuzione nei servizi app Azure.Spring Boot apps running on Windows require additional configuration to run on Azure App Services. Modificare Web. config e aggiungere quanto segue:Modify web.config and add the following:

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

Eccezioni e richieste non eseguiteExceptions and request failures

Le eccezioni non gestite e gli errori delle richieste vengono raccolti automaticamente dal filtro Application Insights Web.Unhandled exceptions and request failures are automatically collected by the Application Insights web filter.

Per raccogliere dati in altre eccezioni, è possibile inserire chiamate a trackexception () nel codice.To collect data on other exceptions, you can insert calls to trackException() in your code.

Monitorare le chiamate al metodo e le dipendenze esterneMonitor method calls and external dependencies

Installare l'agente Java per registrare i metodi interni specificati e le chiamate effettuate tramite JDBC, con i dati relativi alle durate.Install the Java Agent to log specified internal methods and calls made through JDBC, with timing data.

E per la denominazione automatica delle operazioni.And for automatic operation naming.

Analisi distribuita W3CW3C distributed tracing

L'SDK di Java di Application Insights adesso supporta l'analisi distribuita W3C.The Application Insights Java SDK now supports W3C distributed tracing.

La configurazione dell'SDK in ingresso viene illustrata più dettagliatamente nell'articolo sulla correlazione.The incoming SDK configuration is explained further in our article on correlation.

La configurazione dell'SDK in uscita è definita nel file AI-Agent.xml.Outgoing SDK configuration is defined in the AI-Agent.xml file.

Contatori delle prestazioniPerformance counters

Aprire esamina, metriche, per visualizzare un intervallo di contatori delle prestazioni.Open Investigate, Metrics, to see a range of performance counters.

Screenshot del riquadro metriche con i byte privati di processo selezionati

Personalizzare la raccolta del contatore delle prestazioniCustomize performance counter collection

Per disabilitare la raccolta del set standard di contatori delle prestazioni, aggiungere il seguente codice al di sotto del nodo principale del file 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>

Raccogliere dei contatori di prestazioni aggiuntiveCollect additional performance counters

È possibile specificare altri contatori di prestazioni da raccogliere.You can specify additional performance counters to be collected.

Contatori JMX (esposti da Java Virtual Machine)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 : il nome visualizzato nel portale di Application Insights.displayName – The name displayed in the Application Insights portal.
  • objectName : il nome dell'oggetto JMX.objectName – The JMX object name.
  • attribute : l'attributo del nome dell'oggetto JMX da recuperareattribute – The attribute of the JMX object name to fetch
  • type (facoltativo): il tipo di attributo dell'oggetto JMX:type (optional) - The type of JMX object’s attribute:
    • Impostazione predefinita: un tipo semplice come int o long.Default: a simple type such as int or long.
    • composite: i dati del contatore delle prestazioni sono nel formato 'Attribute.Data'composite: the perf counter data is in the format of 'Attribute.Data'
    • tabular: i dati del contatore delle prestazioni sono nel formato della riga di una tabellatabular: the perf counter data is in the format of a table row

Contatori delle prestazioni di WindowsWindows performance counters

Ogni contatore delle prestazioni Windows è un membro di una categoria (nello stesso modo in cui un campo è un membro di una classe).Each Windows performance counter is a member of a category (in the same way that a field is a member of a class). Le categorie possono essere globali o possono disporre di istanze numerate o denominate.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: il nome visualizzato nel portale di Application Insights.displayName – The name displayed in the Application Insights portal.
  • categoryName: la categoria del contatore delle prestazioni (oggetto prestazioni) a cui è associato questo contatore delle prestazioni.categoryName – The performance counter category (performance object) with which this performance counter is associated.
  • counterName: il nome del contatore delle prestazioni.counterName – The name of the performance counter.
  • instanceName: il nome dell'istanza di categoria del contatore delle prestazioni o una stringa vuota (""), se la categoria contiene una singola istanza.instanceName – The name of the performance counter category instance, or an empty string (""), if the category contains a single instance. Se categoryName è il processo e il contatore delle prestazioni di cui raccogliere i dati proviene dal processo JVM corrente su cui è in esecuzione l'app, specificare "__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__".

Contatori delle prestazioni UnixUnix performance counters

Ottenere i dati relativi a utenti e sessioniGet user and session data

I dati di telemetria vengono normalmente inviati dal server Web.OK, you're sending telemetry from your web server. Per un quadro completo a 360 gradi dell'applicazione, è però possibile aggiungere altre funzionalità di monitoraggio:Now to get the full 360-degree view of your application, you can add more monitoring:

Inviare i propri dati di telemetriaSend your own telemetry

Ora che è stato installato SDK, è possibile usare l'API per inviare i propri dati di telemetria.Now that you've installed the SDK, you can use the API to send your own telemetry.

Test Web della disponibilitàAvailability web tests

Application Insights può testare il sito Web a intervalli regolari per verificare che funzioni e risponda correttamente.Application Insights can test your website at regular intervals to check that it's up and responding well.

Altre informazioni su come configurare i test Web di disponibilità.Learn more about how to set up availability web tests.

Domande?Questions? Problemi?Problems?

Risoluzione dei problemi JavaTroubleshooting Java

Passaggi successiviNext steps