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 rilevare e diagnosticare i problemi di prestazioni e le eccezioni e per scrivere il codice per tenere traccia della attività degli utenti con l'app.Use it to detect and diagnose performance issues and exceptions, and write code to track what users do with your app.

dati di esempio

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:

  • Oracle JRE 1.6 o versione successiva o isiZulu JRE 1.6 o versione successivaOracle JRE 1.6 or later, or Zulu JRE 1.6 or later
  • Una sottoscrizione a Microsoft Azure.A subscription to Microsoft Azure.

Se è disponibile un'App Web già attiva, è possibile seguire la procedura alternativa per aggiungere l'SDK al server Web in fase di esecuzione. Tale alternativa evita di ricompilare il codice, ma non si ottiene l'opzione per scrivere codice per tenere traccia delle attività dell'utente.If you have a web app that's already live, you could follow the alternative procedure to add the SDK at runtime in the web server. That alternative avoids rebuilding the code, but you don't get the option to write code to track user activity.

1. Ottenere una chiave di strumentazione di 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.

    Inserire un nome, scegliere l'app Web Java e fare clic su Crea

  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 SDK per Java di Application Insights 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 Eclipse per creare un progetto Web dinamico o Maven:If you're using Eclipse to create a Maven or Dynamic Web project ...

Usare il plug-in di Application Insights SDK per Java.Use the Application Insights SDK for Java plug-in.

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.


    <repositories>
       <repository>
          <id>central</id>
          <name>Central</name>
          <url>http://repo1.maven.org/maven2</url>
       </repository>
    </repositories>

    <dependencies>
      <dependency>
        <groupId>com.microsoft.azure</groupId>
        <artifactId>applicationinsights-web</artifactId>
        <!-- or applicationinsights-core for bare API -->
        <version>[1.0,)</version>
      </dependency>
    </dependencies>
  • Errori di convalida checksum o compilazione?Build or checksum validation errors? Provare a usare una versione specifica, ad esempio <version>1.0.n</version>.Try using a specific version, such as: <version>1.0.n</version>. La versione più recente è disponibile nelle note sulla versione dell'SDK o negli elementi Maven.You'll find the latest version in the SDK release notes or in our Maven artifacts.
  • È necessario eseguire l'aggiornamento a un nuovo SDK?Need to update to a new SDK? Aggiornare le dipendenze del progetto.Refresh your project's 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.


    repositories {
      mavenCentral()
    }

    dependencies {
      compile group: 'com.microsoft.azure', name: 'applicationinsights-web', version: '1.+'
      // or applicationinsights-core for bare API
    }
  • Errori di convalida checksum o compilazione? Provare a usare una versione specifica, come version:'1.0.n'.Build or checksum validation errors? Try using a specific version, such as: version:'1.0.n'. La versione più recente è disponibile nelle note sulla versione dell'SDK.You'll find the latest version in the SDK release notes.
  • Per eseguire l'aggiornamento a un nuovo SDKTo update to a new SDK
    • Aggiornare le dipendenze del progetto.Refresh your project's dependencies.

In caso contrario...Otherwise ...

Aggiungere manualmente SDK:Manually add the SDK:

  1. Scaricare Application Insights SDK per Java.Download the Application Insights SDK for Java.
  2. Estrarre i file binari dal file ZIP e aggiungerli al progetto.Extract the binaries from the zip file and add them to your project.

Domande...Questions...

  • Qual è la relazione tra i componenti -core e -web nel file ZIP?What's the relationship between the -core and -web components in the zip?

    • applicationinsights-core fornisce semplicemente l'API.applicationinsights-core gives you the bare API. Questo componente sarà sempre necessario.You always need this component.
    • applicationinsights-web fornisce le metriche che consentono di tenere traccia del numero e dei tempi di risposta delle richieste HTTP.applicationinsights-web gives you metrics that track HTTP request counts and response times. Questo componente può essere omesso se non si vuole che questi dati di telemetria vengano raccolti automaticamente.You can omit this component if you don't want this telemetry automatically collected. Ad esempio se si preferisce scrivere dati personalizzati.For example, if you want to write your own.
  • Per aggiornare il SDK, quando si pubblicano le modificheTo update the SDK when we publish changes

3. Aggiungere un file XML di Application Insights3. Add an Application Insights .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>
  • 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.Events 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.
  • La chiave di Application Insights può essere passata dinamicamente dal portale di Azure come proprietà di sistema (-DAPPLICATION_INSIGHTS_IKEY=ikey).The Application Insights key can be passed dynamically from the Azure portal as a system property (-DAPPLICATION_INSIGHTS_IKEY=your_ikey). Se non è presente una proprietà definita, viene verificata la presenza della variabile di ambiente (APPLICATION_INSIGHTS_IKEY) nelle impostazioni dell'app Azure.If there is no property defined, it checks for environment variable (APPLICATION_INSIGHTS_IKEY) in Azure App Settings. Se nessuna delle due proprietà è definita, viene usato il valore InstrumentationKey predefinito di ApplicationInsights.xml.If both the properties are undefined, the default InstrumentationKey is used from ApplicationInsights.xml. Questa sequenza consente di gestire dinamicamente valori InstrumentationKey diversi per ambienti diversi.This sequence helps you to manage different InstrumentationKeys for different environments dynamically.

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: -DAPPLICATION_INSIGHTS_IKEY=ikeySystem property: -DAPPLICATION_INSIGHTS_IKEY=your_ikey
  2. Variabile di ambiente: APPLICATION_INSIGHTS_IKEYEnvironment variable: APPLICATION_INSIGHTS_IKEY
  3. File di configurazione: ApplicationInsights.xmlConfiguration file: ApplicationInsights.xml

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


    telemetryClient.InstrumentationKey = "...";

4. Aggiungere un filtro HTTP4. Add an HTTP filter

L'ultimo passaggio di configurazione consente al componente delle richieste HTTP di registrare ogni richiesta Web.The last configuration step allows the HTTP request component to log each web request. Non necessario se si desidera l'API.(Not required if you just want the bare API.)

Individuare e aprire il file web.xml nel progetto e unire il codice seguente al di sotto del nodo app-web, in cui sono configurati i filtri dell'applicazione.Locate and open the web.xml file in your project, and merge the following code under the web-app node, where your application filters are configured.

Per ottenere risultati più accurati, il filtro deve essere mappato prima di tutti gli altri filtri.To get the most accurate results, the filter should be mapped before all other filters.


    <filter>
      <filter-name>ApplicationInsightsWebFilter</filter-name>
      <filter-class>
        com.microsoft.applicationinsights.web.internal.WebRequestTrackingFilter
      </filter-class>
    </filter>
    <filter-mapping>
       <filter-name>ApplicationInsightsWebFilter</filter-name>
       <url-pattern>/*</url-pattern>
    </filter-mapping>

Se si usa Spring Web MVC 3.1 o versione successivaIf you're using Spring Web MVC 3.1 or later

Modificare questi elementi in *-servlet.xml per includere il pacchetto di Application Insights:Edit these elements in *-servlet.xml to include the Application Insights package:


    <context:component-scan base-package=" com.springapp.mvc, com.microsoft.applicationinsights.web.spring"/>

    <mvc:interceptors>
        <mvc:interceptor>
            <mvc:mapping path="/**"/>
            <bean class="com.microsoft.applicationinsights.web.spring.RequestNameHandlerInterceptorAdapter" />
        </mvc:interceptor>
    </mvc:interceptors>

Se si usa Struts 2If you're using Struts 2

Aggiungere questa voce al file di configurazione Struts (in genere denominato struts.xml o struts-default.xml):Add this item to the Struts configuration file (usually named struts.xml or struts-default.xml):


     <interceptors>
       <interceptor name="ApplicationInsightsRequestNameInterceptor" class="com.microsoft.applicationinsights.web.struts.RequestNameInterceptor" />
     </interceptors>
     <default-interceptor-ref name="ApplicationInsightsRequestNameInterceptor" />

Se si dispone di intercettori definiti in uno stack predefinito, l'intercettore può semplicemente essere aggiunto a tale stack.(If you have interceptors defined in a default stack, the interceptor can simply be added to that stack.)

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

dati di esempio

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.

Application Insights presuppone che il formato delle richieste HTTP per le applicazioni MVC sia VERB controller/action.Application Insights assumes the format of HTTP requests for MVC applications is: VERB controller/action. Ad esempio, GET Home/Product/f9anuh81, GET Home/Product/2dffwrf5 e GET Home/Product/sdf96vws vengono raggruppati in GET Home/Product.For example, GET Home/Product/f9anuh81, GET Home/Product/2dffwrf5 and GET Home/Product/sdf96vws are grouped into GET Home/Product. Questo raggruppamento consente aggregazioni significative delle richieste, come il numero di richieste e il tempo medio di esecuzione per le richieste.This grouping enables meaningful aggregations of requests, such as number of requests and average execution time for requests.

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.

In Application Insights vengono visualizzati due tipi di dati, ovvero i dati aggregati, archiviati e visualizzati come medie, conteggi e somme, e i dati di istanza, ovvero singoli report di richieste HTTP, eccezioni, visualizzazioni di pagina o eventi personalizzati.Two kinds of data are displayed in Application Insights: aggregated data, stored and displayed as averages, counts, and sums; and instance data - individual reports of HTTP requests, exceptions, page views, or custom events.

Quando si visualizzano le proprietà di una richiesta, è possibile visualizzare gli eventi di telemetria associati, ad esempio le richieste e le eccezioni.When viewing the properties of a request, you can see the telemetry events associated with it such as requests and exceptions.

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'applicazione 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:

Eccezioni e richieste non eseguiteExceptions and request failures

Vengono raccolte automaticamente le eccezioni non gestite:Unhandled exceptions are automatically collected:

Aprire Impostazioni e quindi Errori

Per raccogliere dati su altre eccezioni, sono disponibili due opzioni:To collect data on other exceptions, you have two options:

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.

Contatori delle prestazioniPerformance counters

Per visualizzare un intervallo di contatori delle prestazioni, aprire Impostazioni e quindi Server.Open Settings, Servers, to see a range of performance counters.

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

I contatori delle prestazioni sono visibili come metriche personalizzate in Esplora metriche.Your performance counters are visible as custom metrics in Metrics Explorer.

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:

Acquisire le tracce dei logCapture log traces

È possibile usare Application Insights per analizzare approfonditamente log di Log4J, Logback o altri framework di registrazione.You can use Application Insights to slice and dice logs from Log4J, Logback, or other logging frameworks. È possibile correlare i log con le richieste HTTP e altri dati di telemetria.You can correlate the logs with HTTP requests and other telemetry. Informazioni.Learn how.

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 di 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. Per eseguire la configurazione, fare clic su Test Web.To set up, click Web tests.

Fare clic su Test Web e quindi su Aggiungi test Web

Se il sito è inattivo, si otterranno grafici dei tempi di risposta, nonché notifiche di posta elettronica.You'll get charts of response times, plus email notifications if your site goes down.

Esempio di test Web

Altre informazioni sui test Web di disponibilità.Learn more about availability web tests.

Domande?Questions? Problemi?Problems?

Risoluzione dei problemi JavaTroubleshooting Java

VideoVideo

Passaggi successiviNext steps