Condividi tramite

Application Insights per Java 2.x

Attenzione

Questo articolo si applica ad Application Insights Java 2.x, che non è più consigliato.

La documentazione per la versione più recente è disponibile in Application Insights Java 3.x.

Questo articolo illustra come usare Application Insights Java 2.x. Questo articolo illustra come:

  • Introduzione e informazioni su come instrumentare le richieste, tenere traccia delle dipendenze, raccogliere contatori delle prestazioni, diagnosticare problemi di prestazioni ed eccezioni e scrivere codice per tenere traccia delle operazioni eseguite dagli utenti con l'app.
  • Inviare i log di traccia ad Application Insights ed esplorarli usando il portale di Application Insights.
  • Monitorare le dipendenze, intercettato le eccezioni e i tempi di esecuzione dei metodi nelle app Web Java.
  • Filtrare i dati di telemetria nell'app Web Java.
  • Esplorare le metriche delle prestazioni del sistema Linux in Application Insights usando collectd.
  • Misurare le metriche per il codice dell'applicazione basato su JVM (Java Virtual Machine). Esporta i dati nei sistemi di monitoraggio preferiti utilizzando Micrometer Application Monitoring.

Annotazioni

Il 31 marzo 2025, il supporto per l'inserimento delle chiavi di strumentazione terminerà. L'inserimento delle chiavi di strumentazione continuerà a funzionare, ma non saranno più garantiti aggiornamenti o supporto per la funzionalità. Eseguire la transizione alle stringhe di connessione per sfruttare le nuove funzionalità.

Introduzione ad Application Insights in un progetto Web Java

In questa sezione si usa Application Insights SDK per instrumentare le richieste, tenere traccia delle dipendenze, raccogliere contatori delle prestazioni, diagnosticare problemi di prestazioni ed eccezioni e scrivere codice per tenere traccia delle operazioni eseguite dagli utenti con l'app.

Application Insights è un servizio di analisi estendibile per sviluppatori Web che consente di comprendere le prestazioni e l'utilizzo dell'applicazione live. Application Insights supporta le app Java in esecuzione in Linux, Unix o Windows.

Prerequisiti

È necessario:

Ottenere la chiave di strumentazione di Application Insights

  1. Accedi al portale di Azure.

  2. Nel portale di Azure creare una risorsa di Application Insights. Impostare il tipo di applicazione su Applicazione Web Java.

  3. Trova la chiave di strumentazione della nuova risorsa. A breve sarà necessario incollare questa chiave nel progetto di codice.

    Screenshot del riquadro Panoramica per una risorsa di Application Insights nel portale di Azure con la chiave di strumentazione evidenziata.

Aggiungere Application Insights SDK per Java al progetto

Scegliere il tipo di progetto.

Se il progetto è già configurato per l'uso di Maven per la compilazione, unire il codice seguente al file pom.xml . Aggiornare quindi le dipendenze del progetto per ottenere i file binari scaricati.

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

Domande frequenti

  • Qual è la relazione tra i -web-autocomponenti , -webe -core ?

    • applicationinsights-web-auto offre metriche che tengono traccia dei conteggi delle richieste e dei tempi di risposta HTTP registrando automaticamente il filtro servlet di Application Insights in fase di esecuzione.
    • applicationinsights-web fornisce anche metriche che tengono traccia dei conteggi delle richieste servlet HTTP e dei tempi di risposta. Tuttavia, è necessaria la registrazione manuale del filtro servlet di Application Insights nell'applicazione.
    • applicationinsights-core offre un'API di base, ad esempio se l'applicazione non è basata su servlet.

  • Come aggiornare l'SDK alla versione più recente?

    • A partire da novembre 2020, per il monitoraggio delle applicazioni Java, è consigliabile usare Application Insights Java 3.x. Per altre informazioni su come iniziare, vedere Application Insights Java 3.x.

Aggiungere un file di ApplicationInsights.xml

Aggiungere ApplicationInsights.xml alla cartella resources nel progetto o assicurarsi che sia stata aggiunta al percorso della classe di distribuzione del progetto. Copiare il codice XML seguente in esso.

Sostituire la chiave di strumentazione con quella ottenuta dal portale di 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>

Facoltativamente, il file di configurazione può trovarsi in qualsiasi posizione accessibile all'applicazione. La proprietà -Dapplicationinsights.configurationDirectory di sistema specifica la directory che contiene ApplicationInsights.xml. Ad esempio, un file di configurazione che si trova in E:\myconfigs\appinsights\ApplicationInsights.xml verrebbe configurato con la proprietà -Dapplicationinsights.configurationDirectory="E:\myconfigs\appinsights".

  • La chiave di strumentazione viene inviata insieme a ogni elemento di telemetria e indica ad Application Insights di visualizzarla nella risorsa.
  • Il componente richiesta HTTP è facoltativo. Invia automaticamente i dati di telemetria relativi alle richieste e ai tempi di risposta al portale.
  • La correlazione degli eventi è un'aggiunta al componente della richiesta HTTP. Assegna un identificatore a ogni richiesta ricevuta dal server. Aggiunge quindi questo identificatore come proprietà a ogni elemento di telemetria come proprietà Operation.Id. Consente di correlare i dati di telemetria associati a ogni richiesta impostando un filtro nella ricerca diagnostica.

Modi alternativi per impostare la chiave di strumentazione

Application Insights SDK cerca la chiave in questo ordine:

  • Proprietà di sistema: -DAPPINSIGHTS_INSTRUMENTATIONKEY=your_ikey
  • Variabile di ambiente: APPINSIGHTS_INSTRUMENTATIONKEY
  • File di configurazione: ApplicationInsights.xml

È anche possibile impostarlo nel codice:

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

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

Aggiungere l'agente

Installare l'agente Java per acquisire chiamate HTTP in uscita, query JDBC, registrazione delle applicazioni e migliorare la denominazione delle operazioni.

Eseguire l'applicazione

Eseguirlo in modalità di debug nel computer di sviluppo o pubblicarlo nel server.

Visualizzare i dati di telemetria in Application Insights

Tornare alla risorsa di Application Insights nel portale di Azure.

I dati delle richieste HTTP sono visualizzati nel riquadro di panoramica. Se non è presente, attendere alcuni secondi e poi selezionare Aggiorna.

Screenshot che mostra i dati di esempio generali.

Altre informazioni sulle metriche.

Fare clic su qualsiasi grafico per visualizzare metriche aggregate più dettagliate.

Screenshot che mostra un riquadro degli errori di Application Insights con grafici.

Dati dell'istanza

Fare clic su un tipo di richiesta specifico per visualizzare le singole istanze.

Screenshot che mostra l'approfondimento di una specifica visualizzazione di esempio.

Log Analytics: linguaggio di query avanzato

Man mano che si accumulano più dati, è possibile eseguire query per aggregare i dati e trovare singole istanze. Log Analytics è uno strumento potente per comprendere le prestazioni e l'utilizzo e per scopi di diagnostica.

Screenshot che mostra un esempio di Log Analytics nel portale di Azure.

Installare l'app nel server

Pubblicare ora l'app nel server, consentire agli utenti di usarla e visualizzare i dati di telemetria nel portale.

  • Assicurarsi che il firewall consenta all'applicazione di inviare dati di telemetria a queste porte:

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

  • Se il traffico in uscita deve essere instradato attraverso un firewall, definire le proprietà http.proxyHost di sistema e http.proxyPort.

  • Su server Windows, installare:

Servizio app di Azure, servizio Azure Kubernetes, configurazione delle macchine virtuali

L'approccio migliore e più semplice per monitorare le applicazioni in esecuzione in qualsiasi provider di risorse di Azure consiste nell'usare Application Insights Java 3.x.

Eccezioni e errori di richiesta

Le eccezioni non gestite e gli errori delle richieste vengono raccolti automaticamente dal filtro Web di Application Insights.

Per raccogliere dati su altre eccezioni, è possibile inserire chiamate a trackException() nel codice.

Monitorare le chiamate ai metodi e le dipendenze esterne

Installare l'agente Java per registrare i metodi interni specificati e le chiamate effettuate tramite JDBC, con dati di intervallo e per la denominazione automatica delle operazioni.

Traccia distribuita W3C

Application Insights Java SDK supporta ora la traccia distribuita W3C.

La configurazione dell'SDK in ingresso è illustrata ulteriormente in Correlazione dei dati di telemetria in Application Insights.

La configurazione dell'SDK in uscita viene definita nel file AI-Agent.xml .

Contatori delle prestazioni

Selezionare Analizza>metriche per visualizzare un intervallo di contatori delle prestazioni.

Screenshot che mostra il riquadro Metriche per una risorsa di Application Insights nel portale di Azure con l'opzione process private bytes selezionata.

Personalizzare la raccolta dei contatori delle prestazioni

Per disabilitare la raccolta del set standard di contatori delle prestazioni, aggiungere il codice seguente nel nodo radice del file ApplicationInsights.xml :

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

Raccogliere più contatori delle prestazioni

È possibile specificare più contatori delle prestazioni da raccogliere.

Contatori JMX (esposti dalla macchina virtuale 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: nome visualizzato nel portale di Application Insights.
  • objectName: nome dell'oggetto JMX.
  • attribute: attributo del nome dell'oggetto JMX da recuperare.
  • type (facoltativo): tipo dell'attributo dell'oggetto JMX:
    • Impostazione predefinita: tipo semplice, ad esempio int o long.
    • composite: i dati del contatore delle prestazioni sono nel formato di Attribute.Data.
    • tabular: i dati del contatore delle prestazioni sono nel formato di una riga di tabella.
Contatori delle prestazioni di Windows

Ogni contatore delle prestazioni di Windows è un membro di una categoria (nello stesso modo in cui un campo è membro di una classe). Le categorie possono essere globali o hanno istanze numerate o denominate.

    <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: nome visualizzato nel portale di Application Insights.
  • categoryName: categoria del contatore delle prestazioni (oggetto prestazioni) a cui è associato questo contatore delle prestazioni.
  • counterName: nome del contatore delle prestazioni.
  • instanceName: nome dell'istanza della categoria del contatore delle prestazioni o di una stringa vuota (""), se la categoria contiene una singola istanza. Se categoryName è Process e il contatore delle prestazioni che si vuole raccogliere è dal processo JVM corrente in cui è in esecuzione l'app, specificare "__SELF__".

Contatori delle prestazioni Unix

Installare collectd con il plug-in Application Insights per ottenere un'ampia gamma di dati di sistema e di rete.

Ottenere dati utente e sessione

A questo momento si inviano dati di telemetria dal server Web. Per ottenere la visualizzazione completa a 360 gradi dell'applicazione, è possibile aggiungere altri monitoraggi:

Inviare dati di telemetria personalizzati

Ora che è stato installato l'SDK, è possibile usare l'API per inviare dati di telemetria personalizzati:

Test Web di disponibilità

Application Insights può testare il sito Web a intervalli regolari per verificare che sia attivo e risponda correttamente.

Altre informazioni su come configurare i test Web di disponibilità.

Risoluzione dei problemi

Vedere l'articolo sulla risoluzione dei problemi dedicato.

Testare la connettività tra l'host dell'applicazione e il servizio di inserimento

Gli SDK e gli agenti di Application Insights inviano dati di telemetria per l'inserimento come chiamate REST agli endpoint di inserimento. È possibile testare la connettività dal server Web o dal computer host dell'applicazione agli endpoint del servizio di inserimento usando client REST non elaborati da comandi PowerShell o curl. Vedere Risolvere i problemi di dati di telemetria delle applicazioni mancanti in Application Insights per Monitoraggio di Azure.

Esplorare i log di traccia Java in Application Insights

Se si usa Logback o Log4J (v1.2 o v2.0) per la traccia, è possibile inviare automaticamente i log di traccia ad Application Insights in cui è possibile esplorare e cercare.

Suggerimento

È necessario impostare la chiave di strumentazione di Application Insights una sola volta per l'applicazione. Se si usa un framework come Java Spring, è possibile che la chiave sia già stata registrata altrove nella configurazione dell'app.

Usare l'agente Java di Application Insights

Per impostazione predefinita, l'agente Java di Application Insights acquisisce automaticamente la registrazione delle operazioni eseguite a partire dal livello WARN e superiore.

È possibile modificare la soglia di registrazione acquisita usando il file AI-Agent.xml :

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

È possibile disabilitare l'acquisizione della registrazione dell'agente Java usando il file AI-Agent.xml :

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

Alternativi

Anziché usare l'agente Java, è possibile seguire queste istruzioni.

Installare Java Software Development Kit (SDK)

Seguire le istruzioni per installare Application Insights SDK per Java, se non è già stato fatto.

Aggiungere librerie di registrazione al progetto

Scegliere il modo appropriato per il progetto.

Intenditore

Se il progetto è già configurato per l'uso di Maven per la compilazione, unire uno dei frammenti di codice seguenti nel file pom.xml . Aggiornare quindi le dipendenze del progetto per ottenere i file binari scaricati.

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

Se il progetto è già configurato per usare Gradle per la compilazione, aggiungere una delle righe seguenti al dependencies gruppo nel file build.gradle . Aggiornare quindi le dipendenze del progetto per ottenere i file binari scaricati.

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

Seguire le linee guida per installare manualmente Application Insights Java SDK e scaricare il file JAR. Nella pagina Maven Central, selezionare il jar collegamento nella sezione di download per l'appender appropriato. Aggiungere il file JAR dell'appender scaricato al progetto.

Logger Download Libreria
Logback Logback appender Jar applicationinsights-logging-logback
Log4J v2.0 Log4J v2 appender Jar applicationinsights-logging-log4j2
Log4j v1.2 Log4J v1.2 appender Jar applicationinsights-logging-log4j1_2

Aggiungere l'appender al framework di registrazione

Per iniziare a ottenere tracce, unire il frammento di codice pertinente al file di configurazione Logback o 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>

È possibile fare riferimento agli appender di Application Insights da qualsiasi logger configurato e non necessariamente dal logger radice, come illustrato negli esempi di codice precedenti.

Esplorare le tracce nel portale di Application Insights

Dopo aver configurato il progetto per inviare tracce ad Application Insights, è possibile visualizzare e cercare queste tracce nel portale di Application Insights nel riquadro Ricerca .

Le eccezioni inviate tramite logger verranno visualizzate nel portale come dati di telemetria delle eccezioni .

Screenshot che mostra il riquadro Di ricerca per una risorsa di Application Insights nel portale di Azure.

Monitorare le dipendenze, intercettato le eccezioni e i tempi di esecuzione dei metodi nelle app Web Java

Se è stata instrumentata l'app Web Java con Application Insights SDK, è possibile usare l'agente Java per ottenere informazioni più approfondite, senza apportare modifiche al codice:

  • Dipendenze: dati sulle chiamate effettuate dall'applicazione ad altri componenti, tra cui:

    • Chiamate HTTP in uscita: le chiamate effettuate tramite Apache HttpClient, OkHttpe java.net.HttpURLConnection vengono acquisite.
    • Chiamate Redis: le chiamate effettuate tramite il client Jedis vengono acquisite.
    • Query JDBC: per MySQL e PostgreSQL, se la chiamata richiede più di 10 secondi, l'agente segnala il piano di query.

  • Registrazione delle applicazioni: raccogliere e correlare i log delle applicazioni con le richieste HTTP e altri dati di telemetria.

    • Log4j 1.2
    • Log4j2
    • Logback

  • Denominazione migliore delle operazioni: usata per l'aggregazione delle richieste nel portale.

    • Spring: basata su @RequestMapping.
    • JAX-RS: basato su @Path.

Per usare l'agente Java, installarlo nel server. Le app Web devono essere instrumentate con Application Insights Java SDK.

Installare l'agente di Application Insights per Java

  1. Sul computer che esegue il server Java, scarica l'agente 2.x. Assicurarsi che la versione dell'agente Java 2.x usata corrisponda alla versione di Application Insights Java SDK 2.x usata.

  2. Modificare lo script di avvio del server applicazioni e aggiungere l'argomento JVM seguente:

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

    Ad esempio, in Tomcat in un computer Linux:

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

  3. Riavviare il server applicazioni.

Configurare l'agente

Creare un file denominato AI-Agent.xml e inserirlo nella stessa cartella del file JAR dell'agente.

Impostare il contenuto del file XML. Modificare l'esempio seguente per includere o omettere le funzionalità desiderate.

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

Altre configurazioni (Spring Boot)

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

Per Servizio app di Azure, seguire questa procedura:

  1. Selezionare Impostazioni>Impostazioni dell'applicazione.

  2. In Impostazioni app aggiungere una nuova coppia chiave-valore:

    • Chiave: JAVA_OPTS
    • Valore: -javaagent:D:/home/site/wwwroot/applicationinsights-agent-2.6.4.jar

    L'agente deve essere pacchettizzato come risorsa nel progetto in modo che venga posizionato nella directory D:/home/site/wwwroot/. Per verificare che l'agente si trovi nella directory corretta del servizio App, vai su Strumenti di sviluppo>Strumenti avanzati>Console di debug e esamina il contenuto della directory del sito.

  3. Salvare le impostazioni e riavviare l'app. Questi passaggi si applicano solo ai servizi app in esecuzione in Windows.

Annotazioni

AI-Agent.xml e il file JAR dell'agente devono trovarsi nella stessa cartella. Vengono spesso inseriti nella cartella /resources del progetto.

Abilitare la traccia distribuita W3C

Aggiungere il frammento di codice seguente a AI-Agent.xml:

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

Annotazioni

La modalità di compatibilità con le versioni precedenti è abilitata per impostazione predefinita. Il enableW3CBackCompat parametro è facoltativo e deve essere usato solo quando si desidera disattivarlo.

Idealmente, questo potrebbe essere il caso in cui tutti i servizi sono stati aggiornati alle versioni più recenti degli SDK che supportano il protocollo W3C. È consigliabile passare alle versioni più recenti degli SDK con supporto W3C il prima possibile.

Assicurarsi che entrambe le configurazioni in ingresso e in uscita (agente) siano esattamente le stesse.

Visualizza i dati

Nella risorsa di Application Insights le dipendenze remote aggregate e i tempi di esecuzione dei metodi vengono visualizzati nel riquadro Prestazioni.

Per cercare singole istanze di report sulle dipendenze, sulle eccezioni e sui metodi, aprire Ricerca.

Altre informazioni su come diagnosticare i problemi di dipendenza.

Domande o problemi?

Usare le risorse seguenti:

Filtrare i dati di telemetria nell'app Web Java

I filtri consentono di selezionare i dati di telemetria inviati dall'app Web Java ad Application Insights. Esistono alcuni filtri predefiniti che è possibile usare. È anche possibile scrivere filtri personalizzati.

I filtri predefiniti includono:

  • Livello di gravità della traccia.
  • URL, parole chiave o codici di risposta specifici.
  • Risposte rapide. In altre parole, le richieste a cui l'app ha risposto rapidamente.
  • Nomi di eventi specifici.

Annotazioni

I filtri inclinano le metriche dell'app. Ad esempio, è possibile decidere che per diagnosticare risposte lente, si imposta un filtro per eliminare i tempi di risposta rapidi. È tuttavia necessario tenere presente che i tempi di risposta medi segnalati da Application Insights saranno quindi più lenti rispetto alla velocità effettiva. Inoltre, il numero di richieste sarà inferiore al conteggio reale.

Se si tratta di un problema, usare invece Campionamento.

Impostare i filtri

In ApplicationInsights.xmlaggiungere una TelemetryProcessors sezione simile all'esempio seguente:


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

Esaminare l'insieme completo dei processori integrati.

Filtri predefiniti

In questa sezione vengono illustrati i filtri predefiniti disponibili.

Filtro di telemetria metrica


           <Processor type="MetricTelemetryFilter">
                  <Add name="NotNeeded" value="metric1,metric2"/>
           </Processor>
  • NotNeeded: elenco delimitato da virgole di nomi di metriche personalizzati

Filtro di telemetria per la visualizzazione della pagina


           <Processor type="PageViewTelemetryFilter">
                  <Add name="DurationThresholdInMS" value="500"/>
                  <Add name="NotNeededNames" value="page1,page2"/>
                  <Add name="NotNeededUrls" value="url1,url2"/>
           </Processor>
  • DurationThresholdInMS: la durata fa riferimento al tempo impiegato per caricare la pagina. Se questo parametro è impostato, le pagine caricate più velocemente di questa volta non vengono segnalate.
  • NotNeededNames: elenco delimitato da virgole di nomi di pagina.
  • NotNeededUrls: elenco delimitato da virgole di frammenti URL. Ad esempio, "home" filtra tutte le pagine con "home" nell'URL.

Filtro di telemetria della richiesta


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

Filtro origine sintetica

Filtra tutti i dati di telemetria con valori nella SyntheticSource proprietà . Sono incluse le richieste provenienti da bot, ragni e test di disponibilità.

Filtra i dati di telemetria per tutte le richieste sintetiche:


           <Processor type="SyntheticSourceFilter" />

Filtra i dati di telemetria per origini sintetiche specifiche:


           <Processor type="SyntheticSourceFilter" >
                  <Add name="NotNeeded" value="source1,source2"/>
           </Processor>
  • NotNeeded: elenco delimitato da virgole di nomi di origine sintetica

Filtro eventi di telemetria

Filtra gli eventi personalizzati registrati tramite TrackEvent():


           <Processor type="TelemetryEventFilter" >
                  <Add name="NotNeededNames" value="event1, event2"/>
           </Processor>
  • NotNeededNames: elenco delimitato da virgole di nomi di eventi

Filtro di telemetria di traccia

Filtra le tracce del log registrate tramite TrackTrace() o un collettore del framework di logging:


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

  • I FromSeverityLevel valori validi sono:

    • OFF: Rimuove tutte le tracce.
    • TRACE: nessun filtro. Uguale al livello TRACE.
    • INFO: filtra il livello TRACE.
    • WARN: filtra fuori TRACE e INFO.
    • ERRORE: filtra WARN, INFO e TRACE.
    • CRITICAL: esclude tutto tranne CRITICAL.

Filtri personalizzati

Le sezioni seguenti illustrano i passaggi per creare filtri personalizzati.

Codificare il filtro

Nel codice creare una classe che implementa 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;
        }
    }

Richiamare il filtro nel file di configurazione

Ora, in ApplicationInsights.xml:



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

Richiama il filtro (Java Spring)

Per le applicazioni basate sul framework Spring, i processori di telemetria personalizzati devono essere registrati nella classe principale dell'applicazione come bean. Verranno quindi distribuiti automaticamente all'avvio dell'applicazione.

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

È possibile creare parametri di filtro personalizzati in application.properties. Usare quindi il framework di configurazione esterna di Spring Boot per passare tali parametri al filtro personalizzato.

Risoluzione dei problemi

Questa sezione offre una descrizione per la risoluzione dei problemi.

Il filtro non funziona

Verificare di aver specificato valori di parametro validi. Ad esempio, le durate devono essere numeri interi. I valori non validi causeranno l'annullamento del filtro. Se il filtro personalizzato genera un'eccezione da un costruttore o un metodo set, verrà ignorato.

collectd: metriche delle prestazioni di Linux in Application Insights (deprecato)

Per esplorare le metriche delle prestazioni del sistema Linux in Application Insights, installare collectd insieme al plug-in di Application Insights. Questa soluzione open source raccoglie varie statistiche di sistema e di rete.

In genere, si userà collectd se il servizio Web Java è già stato instrumentato con Application Insights. Offre più dati per migliorare le prestazioni dell'app o diagnosticare i problemi.

Ottieni la chiave di strumentazione

Nel portale di Azure aprire la risorsa di Application Insights in cui si vogliono visualizzare i dati. In alternativa, è possibile creare una nuova risorsa.

Prendere una copia della chiave di strumentazione, che identifica la risorsa.

Screenshot che mostra il riquadro di panoramica per una risorsa di Application Insights nel portale di Azure con la chiave di strumentazione evidenziata.

Installare raccolto e il plug-in

Nei server Linux:

  1. Installare la versione 5.4.0 o successiva di collectd.
  2. Scarica il plug-in Application Insights collectd writer. Prendere nota del numero di versione.
  3. Copiare il file JAR del plug-in in /usr/share/collectd/java.
  4. Modifica /etc/collectd/collectd.conf:

    • Assicurarsi che il plug-in Java sia abilitato.

    • Aggiornare JVMArg per java.class.path in modo da includere il seguente file JAR. Aggiornare il numero di versione in modo che corrisponda a quello scaricato:

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

    • Aggiungere questo frammento di codice usando la chiave di strumentazione dalla risorsa:

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

      Ecco una parte di un file di configurazione di esempio:

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

Configurare altri plug-in di collectd, che possono raccogliere vari dati da origini diverse.

Riavviare collectd in base al relativo manuale.

Visualizza i dati in Application Insights

Nella risorsa di Application Insights aprire Metriche e aggiungere grafici. Selezionare le metriche da visualizzare nella categoria Personalizzata .

Per impostazione predefinita, le metriche vengono aggregate in tutti i computer host da cui sono state raccolte le metriche. Per visualizzare le metriche per host, nel riquadro Dei dettagli del grafico attivare Raggruppamento e quindi scegliere di raggruppare per CollectD-Host.

Escludere il caricamento di statistiche specifiche

Per impostazione predefinita, il plug-in di Application Insights invia tutti i dati raccolti da tutti i plug-in abilitati collectd read .

Per escludere dati da plug-in o origini dati specifiche:

  • Modificare il file di configurazione.

  • In <Plugin ApplicationInsightsWriter>aggiungere righe di direttiva come quelle nella tabella seguente:

    Direttiva Effetto
    Exclude disk Escludere tutti i dati raccolti dal disk plug-in.
    Exclude disk:read,write Escludere le origini denominate read e write dal disk plug-in.

Separare le direttive con una nuova riga.

Problematica?

Questa sezione offre suggerimenti per la risoluzione dei problemi.

I dati non vengono visualizzati nel portale

Provare queste opzioni:

  • Aprire Ricerca per verificare se sono arrivati gli eventi non elaborati. A volte richiedono più tempo per essere visualizzati in Esplora metriche.
  • Potrebbe essere necessario impostare eccezioni del firewall per i dati in uscita.
  • Abilitare il tracciamento nel plug-in Application Insights. Aggiungere questa riga all'interno di <Plugin ApplicationInsightsWriter>:
    • SDKLogger true
  • Aprire un terminale e avviare collectd in modalità verbosa per visualizzare eventuali problemi che segnala.
    • sudo collectd -f

Problema noto

Il plug-in di scrittura di Application Insights non è compatibile con alcuni plug-in di lettura. Alcuni plug-in talvolta inviano NaN, ma il plug-in di Application Insights prevede un numero a virgola mobile.

  • Sintomo: il collectd log mostra gli errori che includono "intelligenza artificiale: ... SyntaxError: token imprevisto N."
  • Soluzione alternativa: escludere i dati raccolti dai plug-in di scrittura del problema.

Il monitoraggio delle applicazioni micrometer misura le metriche per il codice dell'applicazione basato su JVM e consente di esportare i dati nei sistemi di monitoraggio preferiti. Questa sezione illustra come usare Micrometer con Application Insights per le applicazioni Spring Boot e non Spring Boot.

Usare Spring Boot 1.5x

Aggiungi le seguenti dipendenze al pom.xml o build.gradle:

  • Application Insights spring-boot-starter 2.5.0 o versione successiva.
  • Micrometer Azure Registry 1.1.0 o versione successiva.
  • Micrometer Spring Legacy 1.1.0 o versione successiva. Esegue il backport del codice autoconfig nel framework Spring.
  • Risorsa ApplicationInsights.

Segui questi passaggi:

  1. Aggiornare il filepom.xml dell'applicazione Spring Boot e aggiungerne le dipendenze seguenti:

    <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. Aggiornare il file application.properties o YML con la chiave di strumentazione di Application Insights usando la proprietà seguente:

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

  3. Compilare l'applicazione ed eseguirla.

I passaggi precedenti dovrebbero rendervi pronti a utilizzare le metriche preaggregate raccolte automaticamente in il Monitoraggio di Azure.

Usare Spring 2.x

Aggiungi le seguenti dipendenze al file pom.xml o build.gradle:

  • Application Insights Spring-boot-starter 2.1.2 o versione successiva
  • Azure-spring-boot-metrics-starters 2.0.7 o versione successiva
  • Risorsa di Application Insights

Segui questi passaggi:

  1. Aggiornare il filepom.xml dell'applicazione Spring Boot e aggiungerne la dipendenza seguente:

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

  2. Aggiornare il file application.properties o YML con la chiave di strumentazione di Application Insights usando la proprietà seguente:

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

  3. Compilare l'applicazione ed eseguirla.

I passaggi precedenti dovrebbero metterti in condizione di operare con le metriche preaggregate raccolte automaticamente in Azure Monitor. Per altre informazioni su come ottimizzare Application Insights Spring Boot Starter, vedere il README su GitHub.

Metriche predefinite:

  • Metriche configurate automaticamente per Tomcat, JVM, metriche di logback, metriche log4J, metriche del tempo di attività, metriche del processore e FileDescriptorMetrics.
  • Ad esempio, se Netflix Hystrix è presente nel percorso della classe, anche queste metriche vengono recuperate.
  • Le metriche seguenti possono essere disponibili aggiungendo i rispettivi fagioli:
    • CacheMetrics (CaffeineCache, EhCache2, GuavaCache, HazelcastCache, e JCache)
    • DataBaseTableMetrics
    • HibernateMetrics
    • JettyMetrics
    • OkHttp3 Metriche
    • Kafka Metriche

Disattivare la raccolta automatica delle metriche:

  • Metriche JVM:
    • management.metrics.binders.jvm.enabled=false
  • Metriche di Logback:
    • management.metrics.binders.logback.enabled=false
  • Metriche di uptime.
    • management.metrics.binders.uptime.enabled=false
  • Metriche del processore:
    • management.metrics.binders.processor.enabled=false
  • FileDescriptorMetrics:
    • management.metrics.binders.files.enabled=false
  • Metriche hystrix se la libreria è in classpath:
    • management.metrics.binders.hystrix.enabled=false
  • Metriche di AspectJ se la libreria è in classpath:
    • spring.aop.enabled=false

Annotazioni

Specificare le proprietà precedenti nel file application.properties o application.yml dell'applicazione Spring Boot.

Usare Micrometer con applicazioni Web non Spring Boot

Aggiungi le seguenti dipendenze al pom.xml o al build.gradle:

Segui questi passaggi:

  1. Aggiungere le dipendenze seguenti nel file pom.xml o 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. Se non è già stato fatto, aggiungere il file ApplicationInsights.xml nella cartella resources. Per altre informazioni, vedere Aggiungere un file di ApplicationInsights.xml.

  3. Classe Servlet di esempio (genera una metrica timer):

        @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. Classe di configurazione di esempio:

         @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) {

       }
     }

Per altre informazioni sulle metriche, vedere la documentazione relativa ai micrometri.

Altro codice di esempio su come creare diversi tipi di metriche è disponibile nel repository GitHub di Micrometer ufficiale.

Associare più raccolte di metriche

Le sezioni seguenti illustrano come raccogliere altre metriche.

SpringBoot/Spring

Creare un bean della rispettiva categoria di metriche. Si supponga, ad esempio, di aver bisogno di metriche di Guava Cache:

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

Diverse metriche non sono abilitate per impostazione predefinita, ma possono essere associate nel modo precedente. Per un elenco completo, vedere il repository GitHub di Micrometer.

App non Spring

Aggiungere il codice di associazione seguente al file di configurazione:

    New GuavaCacheMetrics().bind(registry);

API di base per eventi personalizzati e metriche

Inserire alcune righe di codice nell'applicazione per scoprire le operazioni eseguite dagli utenti o per diagnosticare i problemi. È possibile inviare dati di telemetria da app desktop e dispositivi, client Web e server Web. Usare l'API di telemetria di base di Application Insights per inviare metriche e eventi personalizzati e versioni personalizzate dei dati di telemetria standard. Questa API è la stessa API usata dagli agenti di raccolta dati standard di Application Insights.

Riepilogo API

L'API principale è uniforme in tutte le piattaforme, a parte alcune varianti come GetMetric (solo.NET).

Metodo Usato per
TrackPageView Pagine, schermate, riquadri o moduli.
TrackEvent Azioni utente e altri eventi. Usato per tenere traccia del comportamento dell'utente o per monitorare le prestazioni.
TrackMetric Misurazioni delle prestazioni, ad esempio lunghezze della coda, non correlate a eventi specifici.
TrackException Registrazione delle eccezioni per la diagnostica. Tracciare dove si verificano in relazione ad altri eventi ed esaminare le tracce dello stack.
TrackRequest Registrazione della frequenza e della durata delle richieste del server per l'analisi delle prestazioni.
TrackTrace Messaggi del log di diagnostica delle risorse. È anche possibile acquisire log di terze parti.
TrackDependency Registrazione della durata e della frequenza delle chiamate a componenti esterni da cui dipende l'app.

È possibile associare proprietà e metriche alla maggior parte di queste chiamate di telemetria.

Prerequisiti

Se non si ha ancora un riferimento in Application Insights SDK:

  • Aggiungere Application Insights SDK al progetto.

  • Nel codice del dispositivo o del server Web includere:

    import com.microsoft.applicationinsights.TelemetryClient;

Ottenere un'istanza di TelemetryClient

Ottieni un'istanza di TelemetryClient:

private TelemetryClient telemetry = new TelemetryClient();

TelemetryClient è sicuro per i thread.

Annotazioni

Se si usa Funzioni di Azure v2+ o Processi Web di Azure v3+, vedere Monitorare Funzioni di Azure.

Potrebbe essere necessario creare più istanze di TelemetryClient per altri moduli dell'app. Ad esempio, potrebbe essere presente un'istanza TelemetryClient della classe middleware per segnalare gli eventi della logica di business. È possibile impostare proprietà come UserId e DeviceId per identificare il computer. Queste informazioni vengono associate a tutti gli eventi inviati dall'istanza.

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

TrackEvent

In Application Insights un evento personalizzato è un punto dati che è possibile visualizzare in Esplora metriche come conteggio aggregato e in Ricerca diagnostica come singole occorrenze. Non è correlato a MVC o ad altri "eventi".

Inserisci TrackEvent chiamate nel codice per contare vari eventi. Ad esempio, è possibile tenere traccia della frequenza con cui gli utenti scelgono una determinata funzionalità. Oppure potresti voler sapere con quale frequenza raggiungono determinati obiettivi o commettono tipi specifici di errori.

Ad esempio, in un'app di gioco inviare un evento ogni volta che un utente vince il gioco:

telemetry.trackEvent("WinGame");

Eventi personalizzati in Log Analytics

I dati di telemetria sono disponibili nella customEvents tabella nella scheda Log di Application Insights o nell'esperienza di utilizzo. Gli eventi possono provenire da trackEvent(..) oppure dal plug-in Click Analytics Auto-collection.

Se il campionamento è in funzione, la itemCount proprietà mostra un valore maggiore di 1. Ad esempio, itemCount==10 significa che di 10 chiamate a trackEvent(), il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto degli eventi personalizzati, usare codice come customEvents | summarize sum(itemCount).

Annotazioni

itemCount ha un valore minimo di uno; il record stesso rappresenta un entry.

TrackMetric

Application Insights può creare un grafico delle metriche non associate a eventi specifici. Ad esempio, è possibile monitorare la lunghezza della coda a intervalli regolari. Con le metriche, le singole misurazioni sono di minore interesse rispetto alle variazioni e alle tendenze e quindi i grafici statistici sono utili.

Per inviare metriche ad Application Insights, è possibile usare l'API TrackMetric(..) . Esistono due modi per inviare una metrica:

  • Valore singolo. Ogni volta che si esegue una misurazione nell'applicazione, si invia il valore corrispondente ad Application Insights.

    Si supponga, ad esempio, di avere una metrica che descrive il numero di elementi in un contenitore. Durante un determinato periodo di tempo, inserire prima tre elementi nel contenitore e quindi rimuovere due elementi. Pertanto, chiameresti TrackMetric due volte. Prima di tutto, passare il valore 3 e quindi passare il valore -2. Application Insights archivia entrambi i valori.

  • Aggregazione. Quando si lavora con le metriche, ogni singola misura è raramente di interesse. È invece importante un riepilogo di ciò che è accaduto durante un determinato periodo di tempo. Un riepilogo di questo tipo è denominato aggregazione.

    Nell'esempio precedente la somma delle metriche di aggregazione per il periodo di tempo è 1 e il conteggio dei valori delle metriche è 2. Quando si usa l'approccio di aggregazione, si richiama TrackMetric una sola volta per periodo di tempo e si inviano i valori di aggregazione. È consigliabile questo approccio perché può ridurre significativamente il costo e il sovraccarico delle prestazioni inviando meno punti dati ad Application Insights, pur raccogliendo tutte le informazioni pertinenti.

Esempi di valore singolo

Per inviare un singolo valore metrica:

telemetry.trackMetric("queueLength", 42.0);

Metriche personalizzate in Log Analytics

I dati di telemetria sono disponibili nella customMetrics tabella in Application Insights Analytics. Ogni riga rappresenta una chiamata a trackMetric(..) nell'app.

  • valueSum: somma delle misurazioni. Per ottenere il valore medio, dividere per valueCount.
  • valueCount: numero di misurazioni aggregate in questa trackMetric(..) chiamata.

Annotazioni

valueCount ha un valore minimo di uno; il record stesso rappresenta un elemento.

Visualizzazioni pagina

Nell'app per dispositivi o per pagine web, la telemetria delle visualizzazioni delle pagine viene inviata automaticamente quando ogni schermata o pagina viene caricata. Tuttavia, è possibile modificare l'impostazione predefinita per tenere traccia delle visualizzazioni di pagina in momenti più o diversi. Ad esempio, in un'app che visualizza schede o riquadri, è possibile tenere traccia di una pagina ogni volta che l'utente apre un nuovo riquadro.

I dati utente e di sessione vengono inviati come proprietà insieme alle visualizzazioni di pagina, così i grafici utenti e di sessione si animano quando sono presenti dati di telemetria di visualizzazione di pagina.

Visualizzazioni pagina personalizzate

telemetry.trackPageView("GameReviewPage");

Telemetria delle pagine in Log Analytics

In Log Analytics due tabelle mostrano i dati delle operazioni del browser:

  • pageViews: contiene i dati relativi all'URL e al titolo della pagina.
  • browserTimings: contiene dati sulle prestazioni del client, ad esempio il tempo impiegato per elaborare i dati in ingresso.

Per trovare quanto tempo il browser richiede per elaborare pagine diverse:

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

Per scoprire la popolarità di browser diversi:

pageViews
| summarize count() by client_Browser

Per associare le visualizzazioni di pagina alle chiamate AJAX, collegare con le dipendenze:

pageViews
| join (dependencies) on operation_Id

TrackRequest

L'SDK del server usa TrackRequest per registrare le richieste HTTP.

È anche possibile chiamarlo manualmente se si desidera simulare le richieste in un contesto in cui non è in esecuzione il modulo del servizio Web.

Il modo consigliato per inviare i dati di telemetria delle richieste è la posizione in cui la richiesta funge da contesto operativo.

Contesto dell'operazione

È possibile correlare gli elementi di telemetria insieme associandoli al contesto dell'operazione. Il modulo standard di rilevamento delle richieste esegue questa operazione per le eccezioni e altri eventi inviati durante l'elaborazione di una richiesta HTTP. In Ricerca e Analisi è possibile trovare facilmente tutti gli eventi associati alla richiesta usando il relativo ID operazione.

Gli elementi di telemetria segnalati all'interno di un ambito operativo diventano sotto-elementi di tale operazione. È possibile annidare i contesti dell'operazione.

In Ricerca il contesto dell'operazione viene usato per creare l'elenco Elementi correlati .

Screenshot che mostra l'elenco Elementi correlati.

Richieste in Log Analytics

In Application Insights Analytics le richieste sono visualizzate nella requests tabella.

Se il campionamento è in funzione, la itemCount proprietà mostra un valore maggiore di 1. Ad esempio, itemCount==10 significa che di 10 chiamate a trackRequest(), il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto delle richieste e della durata media segmentata in base ai nomi delle richieste, usare il codice, ad esempio:

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

TrackException

Inviare eccezioni ad Application Insights:

I report includono le tracce dello stack.

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

Le eccezioni vengono rilevate automaticamente, quindi non è sempre necessario chiamare TrackException in modo esplicito.

Eccezioni in Log Analytics

In Application Insights Analytics le eccezioni vengono visualizzate nella exceptions tabella.

Se il campionamento è in funzione, la itemCount proprietà mostra un valore maggiore di 1. Ad esempio, itemCount==10 significa che di 10 chiamate a trackException(), il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto delle eccezioni segmentate per tipo di eccezione, usare il codice, ad esempio:

exceptions
| summarize sum(itemCount) by type

La maggior parte delle informazioni importanti sullo stack è già estratta in variabili separate, ma è possibile separare la details struttura per ottenere di più. Poiché questa struttura è dinamica, è necessario eseguire il cast del risultato al tipo previsto. Per esempio:

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

Per associare le eccezioni alle richieste correlate, utilizza un join:

exceptions
| join (requests) on operation_Id

TrackTrace

Usare TrackTrace per diagnosticare i problemi inviando un "percorso di navigazione" ad Application Insights. È possibile inviare blocchi di dati di diagnostica ed esaminarli in Ricerca diagnostica.

Annotazioni

In Java, l'agente Java di Application Insights esegue automaticamente la raccolta e invia i log al portale.

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

Registrare un evento di diagnostica, ad esempio l'immissione o l'uscita di un metodo.

Parametro Description
message Dati di diagnostica. Può essere molto più lungo di un nome.
properties Mappa della stringa alla stringa. Altri dati vengono usati per filtrare le eccezioni nel portale. Di default è vuoto.
severityLevel Valori supportati: SeverityLevel.ts.

È possibile cercare il contenuto dei messaggi, ma a differenza dei valori delle proprietà, non è possibile filtrarlo.

Il limite di dimensioni su message è molto superiore al limite per le proprietà. Un vantaggio di TrackTrace è che è possibile inserire dati relativamente lunghi nel messaggio. Ad esempio, è possibile codificare i dati POST in questa posizione.

È anche possibile aggiungere un livello di gravità al messaggio. Analogamente ad altri dati di telemetria, è possibile aggiungere valori di proprietà per filtrare o cercare set di tracce diversi. Per esempio:

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

In Ricerca è quindi possibile filtrare facilmente tutti i messaggi di un particolare livello di gravità correlato a un determinato database.

Tracce in Log Analytics

In Application Insights Analytics le chiamate a TrackTrace vengono visualizzate nella traces tabella.

Se il campionamento è in funzione, la itemCount proprietà mostra un valore maggiore di 1. Ad esempio, itemCount==10 significa che di 10 chiamate a trackTrace(), il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto delle chiamate di traccia, usare codice come traces | summarize sum(itemCount).

TrackDependency

Usare la TrackDependency chiamata per tenere traccia dei tempi di risposta e delle percentuali di esito positivo delle chiamate a un frammento di codice esterno. I risultati vengono visualizzati nei grafici delle dipendenze nel portale. Il frammento di codice seguente deve essere aggiunto ovunque venga effettuata una chiamata di dipendenza.

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);
}

Annotazioni

In Java molte chiamate di dipendenza possono essere rilevate automaticamente usando l'agente Java di Application Insights.

Questa chiamata viene usata se si desidera tenere traccia delle chiamate che il rilevamento automatico non intercetta.

Dipendenze in Log Analytics

In Application Insights Analytics le trackDependency chiamate sono visualizzate nella dependencies tabella.

Se il campionamento è in funzione, la itemCount proprietà mostra un valore maggiore di 1. Ad esempio, itemCount==10 significa che di 10 chiamate a trackDependency(), il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto delle dipendenze segmentate per componente di destinazione, usare il codice, ad esempio:

dependencies
| summarize sum(itemCount) by target

Per associare le dipendenze alle richieste correlate, usare un join:

dependencies
| join (requests) on operation_Id

Cancellazione dei dati

In genere, l'SDK invia i dati a intervalli fissi, in genere 30 secondi o ogni volta che il buffer è pieno, che in genere è di 500 elementi. In alcuni casi, potrebbe essere necessario scaricare il buffer. Un esempio è se si usa l'SDK in un'applicazione che si arresta.

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

Annotazioni

Java SDK svuota automaticamente al spegnimento dell'applicazione.

Utenti autenticati

In un'app Web, gli utenti sono identificati dai cookie per impostazione predefinita. Un utente potrebbe essere conteggiato più volte se accede all'app da un computer o un browser diverso o se elimina i cookie.

Se gli utenti accedono all'app, è possibile ottenere un conteggio più accurato impostando l'ID utente autenticato nel codice del browser. Non è necessario usare il nome di accesso effettivo dell'utente. Deve essere solo un ID univoco per l'utente. Non deve includere spazi o caratteri ,;=|.

L'ID utente viene impostato anche in un cookie di sessione e inviato al server. Se l'SDK del server è installato, l'ID utente autenticato viene inviato come parte delle proprietà di contesto dei dati di telemetria client e server. È quindi possibile filtrare e cercare su di esso.

Se l'app raggruppa gli utenti negli account, è anche possibile passare un identificatore per l'account. Si applicano le stesse restrizioni relative ai caratteri.

In Esplora metriche è possibile creare un grafico che conta utenti, autenticati e account utente.

È anche possibile cercare punti dati client con nomi utente e account specifici.

Filtrare, cercare e segmentare i dati usando le proprietà

È possibile associare proprietà e misurazioni agli eventi, alle metriche, alle visualizzazioni di pagina, alle eccezioni e ad altri dati di telemetria.

Le proprietà sono valori stringa che è possibile usare per filtrare i dati di telemetria nei report di utilizzo. Ad esempio, se la tua app fornisce diversi giochi, puoi allegare il nome del gioco a ogni evento in modo da poter vedere quali giochi sono più popolari.

Esiste un limite di 8.192 sulla lunghezza della stringa. Per inviare blocchi di dati di grandi dimensioni, usare il parametro message di TrackTrace.

Le metriche sono valori numerici che possono essere presentati graficamente. Ad esempio, potresti voler vedere se c'è un aumento graduale dei punteggi ottenuti dai giocatori. I grafici possono essere segmentati in base alle proprietà inviate con l'evento in modo da poter ottenere grafici separati o in pila per giochi diversi.

I valori delle metriche devono essere maggiori o uguali a 0 per essere visualizzati correttamente.

Esistono alcuni limiti al numero di proprietà, valori delle proprietà e metriche che è possibile usare.

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

Importante

Assicurarsi di non registrare informazioni personali nelle proprietà.

Avvertimento

Non riutilizzare la stessa istanza dell'elemento di telemetria (event in questo esempio) per chiamare Track*() più volte. Questa procedura potrebbe causare l'invio dei dati di telemetria con una configurazione non corretta.

Misurazioni e proprietà personalizzate in Log Analytics

In Log Analytics le metriche e le proprietà personalizzate vengono visualizzate negli customMeasurements attributi e customDimensions di ogni record di telemetria.

Ad esempio, se si aggiunge una proprietà denominata "game" ai dati di telemetria della richiesta, questa query conta le occorrenze di valori diversi di "gioco" e mostra la media della metrica personalizzata "score":

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

Si noti che:

  • Quando si estrae un valore dal JSON customDimensions o customMeasurements, ha un tipo dinamico, quindi è necessario effettuare il cast su tostring o todouble.
  • Per tenere conto della possibilità di campionamento, usare sum(itemCount) non count().

Eventi temporizzati

A volte si vuole creare un grafico del tempo necessario per eseguire un'azione. Ad esempio, potresti voler sapere quanto tempo gli utenti impiegano per prendere in considerazione le scelte in un gioco. Per ottenere queste informazioni, usare il parametro di misurazione.

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

Proprietà predefinite per i dati di telemetria personalizzati

Se desiderate impostare valori predefiniti delle proprietà per alcuni eventi personalizzati che scrivete, configurateli in un'istanza di TelemetryClient. Sono collegati a ogni elemento di telemetria inviato da tale 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");

Le singole chiamate di telemetria possono sovrascrivere i valori predefiniti nei dizionari delle proprietà.

Disabilitare telemetria

Per arrestare e avviare dinamicamente la raccolta e la trasmissione dei dati di telemetria:

telemetry.getConfiguration().setTrackingDisabled(true);

Stringa di connessione dinamica

Per evitare di combinare i dati di telemetria dagli ambienti di sviluppo, test e produzione, è possibile creare risorse di Application Insights separate e modificare le stringhe di connessione, a seconda dell'ambiente.

Anziché ottenere la stringa di connessione dal file di configurazione, è possibile impostarla nel metodo di inizializzazione del codice:

// 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 dispone di una proprietà Context, che contiene valori inviati insieme a tutti i dati di telemetria. Normalmente vengono impostati dai moduli di telemetria standard, ma è anche possibile impostarli manualmente. Per esempio:

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

Se si imposta uno di questi valori manualmente, è consigliabile rimuovere la riga pertinente da ApplicationInsights.config in modo che i valori e i valori standard non vengano confusi.

  • Componente: l'app e la relativa versione.
  • Dispositivo: dati sul dispositivo in cui è in esecuzione l'app. Nelle app Web si tratta del server o del dispositivo client da cui vengono inviati i dati di telemetria.
  • InstrumentationKey: risorsa di Application Insights in Azure in cui sono visualizzati i dati di telemetria.
  • Posizione: posizione geografica del dispositivo.
  • Operazione: nelle applicazioni web, la richiesta HTTP corrente. In altri tipi di app è possibile impostare questo valore per raggruppare gli eventi.
    • ID: valore generato che correla diversi eventi in modo che quando si esamina qualsiasi evento in Ricerca diagnostica, è possibile trovare elementi correlati.
    • Nome: identificatore, in genere l'URL della richiesta HTTP.
    • SyntheticSource: se non null o vuoto, una stringa che indica che l'origine della richiesta è stata identificata come un robot o un test Web. Per impostazione predefinita, viene esclusa dai calcoli in Esplora metriche.
  • Sessione: sessione dell'utente. L'ID è impostato su un valore generato, che viene modificato quando l'utente non è stato attivo per un periodo di tempo.
  • Utente: informazioni sull'utente.

Limits

Esistono alcuni limiti sul numero di metriche e eventi per applicazione, ovvero per chiave di strumentazione. I limiti dipendono dal piano tariffario scelto.

Conto risorse Limite predefinito Limite massimo Note
Totale dati al giorno 100 GB Contattare il supporto tecnico. È possibile impostare un limite per ridurre i dati. Se sono necessari più dati, è possibile aumentare il limite nel portale fino a 1.000 GB. Per capacità maggiori di 1.000 GB, inviare un messaggio di posta elettronica a AIDataCap@microsoft.com.
Throttling 32.000 eventi/secondo Contattare il supporto tecnico. Il limite viene misurato nell'arco di un minuto.
Log di conservazione dei dati Da 30 a 730 giorni 730 giorni Questa risorsa è per Log.
Metriche di conservazione dati 90 giorni 90 giorni Questa risorsa è per Esplora metriche.
Conservazione dettagliata dei risultati dei test a più passaggi di disponibilità 90 giorni 90 giorni Questa risorsa fornisce risultati dettagliati per ogni passaggio.
Dimensioni massime dei dati di telemetria 64 kB 64 kB
Numero massimo di dati di telemetria per batch 64.000 64.000
Lunghezza nomi di proprietà e metriche 150 150 Vedere schemi di tipo.
Lunghezza stringa valore di proprietà 8,192 8,192 Vedere schemi di tipo.
Lunghezza del messaggio di traccia e di eccezione 32,768 32,768 Vedere schemi di tipo.
Numero di test di disponibilità per ogni risorsa di Application Insights 100 100
Numero di test di disponibilità per gruppo di risorse 800 800 Vedere Azure Resource Manager
Numero massimo di reindirizzamenti per test di disponibilità 10 10
Frequenza minima dei test di disponibilità 300 secondi Frequenze di test personalizzate o inferiori a 5 minuti richiedono implementazioni TrackAvailability personalizzate.
Conservazione dei dati di .NET Profiler e Snapshot Debugger Due settimane Contattare il supporto tecnico. Il limite massimo di conservazione è di sei mesi.
Dati di Profiler .NET inviati al giorno Nessun limite Nessun limite.
Dati di Snapshot Debugger inviati al giorno 30 snapshot al giorno per ogni app monitorata Nessun limite. Il numero di snapshot raccolti per applicazione può essere modificato tramite la configurazione.

Per altre informazioni sui prezzi e sulle quote, vedere Fatturazione di Application Insights.

Per evitare di raggiungere il limite di velocità dei dati, usare il campionamento.

Per determinare per quanto tempo vengono conservati i dati, vedere Conservazione e privacy dei dati.

Passaggi successivi

  • Last updated on