Monitorare le applicazioni e i servizi Node.js con Application Insights (API classica)

Application Insights monitora i componenti dopo la distribuzione per individuare le prestazioni e altri problemi. È possibile utilizzare Application Insights per i servizi Node.js ospitati nel data center locale, in nelle VM di Azure e nelle app Web, e anche in altri cloud pubblici.

Per ricevere, archiviare ed esplorare i dati di monitoraggio, includere l'SDK nel codice. Successivamente, configurare una risorsa di Application Insights corrispondente in Azure. L'SDK invia i dati a tale risorsa per ulteriori attività di analisi ed esplorazione.

La libreria client Node.js può monitorare automaticamente le richieste HTTP in ingresso e in uscita, le eccezioni e alcune metriche di sistema. A partire dalla versione 0.20, la libreria client può anche monitorare alcuni pacchetti di terze parti comuni, ad esempio MongoDB, MySQL e Redis.

Tutti gli eventi relativi a una richiesta HTTP in ingresso vengono correlati per velocizzare la risoluzione dei problemi.

È possibile utilizzare l'API TelemetryClient per instrumentare e monitorare manualmente altri aspetti dell'app e del sistema. L'API TelemetryClient viene descritta in modo più dettagliato più avanti nell'articolo.

Inizia

Completare le attività seguenti per configurare il monitoraggio per un'app o un servizio.

Prerequisiti

Prima di iniziare, verificare di avere una sottoscrizione di Azure oppure ottenerne una nuova gratuitamente. Se l'organizzazione ha già una sottoscrizione di Azure, un amministratore può aggiungere l'utente alla sottoscrizione seguendo queste istruzioni.

Configurare una risorsa di Application Insights

1. Accedere al portale di Azure.
2. Creazione di unarisorsa di Application Insights.

Configurare la libreria client Node.js

Includere l'SDK nell'app affinché possa raccogliere i dati.

1. Copiare la stringa di connessione della risorsa dalla nuova risorsa. Application Insights si avvale della stringa di connessione per eseguire il mapping dei dati nella risorsa di Azure. Prima che l'SDK possa usare la stringa di connessione, è necessario specificare la stringa di connessione in una variabile di ambiente o nel codice.

   

2. Aggiungi la libreria client Node.js alle dipendenze dell'applicazione tramite package.json. Dalla cartella radice dell'app eseguire:

   npm install applicationinsights --save
   

   Nota

   Se stai utilizzando TypeScript, non installare pacchetti "typings" separati. Questo pacchetto NPM contiene scritture predefinite.

3. Carica esplicitamente la libreria nel tuo codice. Dato che l'SDK inserisce la strumentazione in molte altre librerie, caricare la libreria il prima possibile, anche prima di altre istruzioni require.

   let appInsights = require('applicationinsights');
   

4. È anche possibile fornire una stringa di connessione tramite la variabile di ambiente APPLICATIONINSIGHTS_CONNECTION_STRING, invece di trasmetterla manualmente a setup() o new appInsights.TelemetryClient(). Questa procedura consente di mantenere le stringhe di connessione fuori dal codice sorgente sottoposto a commit ed è possibile specificare stringhe di connessione diverse per ambienti diversi. Per configurare manualmente, chiamare appInsights.setup('[your connection string]');.

   Per altre opzioni di configurazione, vedere le sezioni riportate di seguito.

   È possibile provare l'SDK senza inviare i dati di telemetria impostando appInsights.defaultClient.config.disableAppInsights = true.

5. Iniziare automaticamente a raccogliere e inviare i dati chiamando appInsights.start();.

Monitorare l'app

L'SDK raccoglie automaticamente i dati di telemetria sul runtime Node.js e su alcuni moduli di terze parti comuni. Usare l'applicazione per generare alcuni di questi dati.

Nel portale di Azure passare quindi alla risorsa di Application Insights creata in precedenza. In Panoramica sequenza temporale cercare i primi punti dati. Per visualizzare altri dati dettagliati, selezionare diversi componenti nei grafici.

Per visualizzare la topologia individuata per l'app, è possibile usare Mappa delle applicazioni.

Nessun dato

Dato che l'SDK esegue l'invio dei dati in batch, potrebbe verificarsi un ritardo nella visualizzazione degli elementi nel portale. Se i dati non sono visibili nella risorsa, provare alcune delle correzioni seguenti:

• Continuare a usare l'applicazione. Eseguire altre azioni per generare dati di telemetria aggiuntivi.
• Fare clic su Aggiorna nella visualizzazione risorse nel portale. I grafici si aggiornano periodicamente in automatico, ma l'aggiornamento manuale ha effetto immediato.
• Verificare che le porte in uscita necessarie siano aperte.
• Usare l'opzione Cerca per cercare eventi specifici.
• Vedere le domande frequenti.

Utilizzo di base

Per la raccolta predefinita di richieste HTTP, eventi più richiesti della libreria di terze parti, eccezioni non gestite e metriche di sistema:

let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

Caricare il prima possibile la libreria di Application Insights require("applicationinsights") negli script prima di caricare altri pacchetti. Questo passaggio è necessario affinché la libreria di Application Insights possa preparare i pacchetti successivi per il rilevamento. Se si verificano conflitti con altre librerie che eseguono operazioni di preparazione simili, provare a caricare la libreria di Application Insights in un secondo momento.

A causa del modo in cui JavaScript gestisce i callback, è richiesto più lavoro per tenere traccia di una richiesta tra dipendenze esterne e i callback successivi. Per impostazione predefinita, questo rilevamento aggiuntivo è abilitato. Disabilitarla chiamando setAutoDependencyCorrelation(false) come descritto nella sezione Configurazione dell'SDK.

Eseguire la migrazione dalle versioni precedenti alla versione 0.22

Sono state apportate modifiche significative se si confrontano le versioni precedenti alla versione 0.22 e quelle successive. Tali modifiche sono progettate per garantire coerenza con altri SDK di Application Insights e consentire un'estendibilità futura.

In generale, è possibile eseguire la migrazione effettuando le azioni seguenti:

• Sostituire i riferimenti a appInsights.client con appInsights.defaultClient.
• Sostituire i riferimenti a appInsights.getClient() con new appInsights.TelemetryClient().
• Sostituire tutti gli argomenti per i metodi client.track* con un singolo oggetto contenente proprietà denominate come argomenti. Per ogni tipo di dati di telemetria, vedere hint del tipo IDE predefinito o TelemetryTypes per l'oggetto escluso per ciascun tipo di dati di telemetria.

Se si accede alle funzioni di configurazione dell'SDK senza concatenarle a appInsights.setup(), è possibile trovare queste funzioni in appInsights.Configurations. Un esempio è appInsights.Configuration.setAutoCollectDependencies(true). Esaminare le modifiche apportate alla configurazione predefinita nella sezione successiva.

Configurazione dell'SDK

L'oggetto appInsights offre molti metodi di configurazione. Essi sono elencati nel frammento di codice seguente con i relativi valori predefiniti.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

Per correlare completamente gli eventi in un servizio, assicurarsi di impostare .setAutoDependencyCorrelation(true). Con questa opzione impostata, l'SDK può tenere traccia del contesto tra callback asincroni in Node.js.

Consultare le descrizioni nei suggerimenti di tipo integrati dell'IDE o in applicationinsights.ts per informazioni dettagliate e argomenti opzionali secondari.

Tracciamento distribuito

Le architetture moderne di cloud e microservizi hanno abilitato servizi semplici e indipendenti che riducono i costi aumentando la disponibilità e la velocità effettiva. Tuttavia, ha reso i sistemi generali più difficili da ragionare e eseguire il debug. La traccia distribuita risolve questo problema fornendo un profiler di prestazioni che opera come le pile di chiamate nelle architetture cloud e microsservizi.

Monitoraggio di Azure offre due esperienze per l'utilizzo dei dati di traccia distribuiti: la visualizzazione diagnostica delle transazioni per una singola transazione/richiesta e la visualizzazione mappa dell'applicazione per mostrare l'interazione dei sistemi.

Application Insights può monitorare ogni componente separatamente e rilevare quale componente è responsabile di errori o riduzione delle prestazioni usando la correlazione di telemetria distribuita. Questo articolo illustra il modello di dati, le tecniche di propagazione del contesto, i protocolli e l'implementazione di tattiche di correlazione su linguaggi e piattaforme diversi usati da Application Insights.

Abilitare la traccia distribuita tramite Application Insights utilizzando l'autoinstrumentazione o gli SDK

Gli agenti e gli SDK di Application Insights per .NET, .NET Core, Java, Node.jse JavaScript supportano la traccia distribuita in modo nativo.

Dopo avere installato e configurato la versione corretta di Application Insights SDK, le informazioni di traccia vengono raccolte automaticamente per le librerie, le tecnologie e i framework più diffusi da agenti di raccolta delle dipendenze dell'SDK automatici. L'elenco completo delle tecnologie supportate è disponibile nella documentazione sulla raccolta automatica delle dipendenze.

Qualsiasi tecnologia può anche essere rilevata manualmente con una chiamata a TrackDependency in TelemetryClient.

Modello di dati per la correlazione dei dati di telemetria

Application Insights definisce un modello di dati per la correlazione di dati di telemetria distribuita. Per associare i dati di telemetria a un'operazione logica, ogni elemento di telemetria ha un campo di contesto denominato operation_Id. Ogni elemento di telemetria nella traccia distribuita condivide questo identificatore. Pertanto, anche se si perdono i dati di telemetria da un singolo livello, è comunque possibile associare i dati di telemetria segnalati da altri componenti.

Un'operazione logica distribuita è in genere costituita da un set di operazioni più piccole elaborate da uno dei componenti. I dati di telemetria delle richieste definiscono queste operazioni. Ogni elemento di telemetria della richiesta ha un proprio id che lo identifica in modo univoco e globale. E tutti gli elementi di telemetria, ad esempio tracce ed eccezioni, associati alla richiesta devono impostare su operation_parentId il valore della richiesta id.

La telemetria delle dipendenze rappresenta ogni operazione in uscita, ad esempio una chiamata HTTP a un altro componente. Definisce anche il proprio id, un elemento univoco a livello globale. La telemetria delle richieste, avviata dalla chiamata di dipendenza, usa questo id come operation_parentId.

È possibile compilare una vista dell'operazione logica distribuita usando operation_Id, operation_parentIde request.id con dependency.id. Questi campi definiscono anche l'ordine di causalità delle chiamate di telemetria.

In un ambiente di microservizi, le tracce dei componenti possono passare a elementi di archiviazione diversi. Ogni componente può avere una propria stringa di connessione in Application Insights. Per ottenere dati di telemetria per l'operazione logica, Application Insights esegue query sui dati da ogni elemento di archiviazione.

Quando il numero di elementi di archiviazione è grande, è necessario un suggerimento su dove cercare successivamente. Il modello di dati di Application Insights definisce due campi per risolvere questo problema: request.source e dependency.target. Il primo campo identifica il componente che ha avviato la richiesta di dipendenza. Il secondo campo identifica il componente che ha restituito la risposta della chiamata di dipendenza.

Per informazioni sull'esecuzione di query da più istanze diverse, vedere Eseguire query sui dati tra aree di lavoro, applicazioni e risorse di Log Analytics in Monitoraggio di Azure.

Example

Esaminiamo un esempio. Un'applicazione denominata Stock Prices mostra il prezzo di mercato corrente di un titolo usando un'API esterna denominata Stock. L'applicazione Prezzi azionari ha una pagina denominata Pagina stock visualizzata dal Web browser client tramite GET /Home/Stock. L'applicazione esegue una query sull'API Stock usando la chiamata GET /api/stock/valueHTTP .

È possibile analizzare i dati di telemetria risultanti eseguendo una query:

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

Nei risultati tutti gli elementi di telemetria condividono la radice operation_Id. Quando viene effettuata una chiamata Ajax dalla pagina, viene assegnato un nuovo ID univoco (qJSXU) ai dati di telemetria delle dipendenze e l'ID di pageView viene usato come operation_ParentId. La richiesta del server usa quindi l'ID Ajax come operation_ParentId.

Quando la chiamata GET /api/stock/value viene effettuata a un servizio esterno, è necessario conoscere l'identità del server in modo da poter impostare il dependency.target campo in modo appropriato. Quando il servizio esterno non supporta il monitoraggio, target viene impostato sul nome host del servizio. Un esempio è stock-prices-api.com. Tuttavia, se il servizio si identifica restituendo un'intestazione HTTP predefinita, target contiene l'identità del servizio che consente ad Application Insights di compilare una traccia distribuita eseguendo query sui dati di telemetria da tale servizio.

Intestazioni di correlazione utilizzando W3C TraceContext

Application Insights esegue la transizione a W3C Trace-Context, che definisce:

• traceparent: Trasporta l'ID globale dell'operazione e l'identificatore univoco della chiamata.
• tracestate: contiene il contesto di tracciamento specifico del sistema.

La versione più recente di Application Insights SDK supporta il protocollo Trace-Context, ma potrebbe essere necessario acconsentire esplicitamente. La retrocompatibilità con il protocollo di correlazione precedente supportato dall'SDK di Application Insights è mantenuta.

Il protocollo HTTP di correlazione, detto anche Request-Id, è deprecato. Questo protocollo definisce due intestazioni:

• Request-Id: porta l'ID univoco globale della chiamata.
• Correlation-Context: contiene la raccolta di coppie nome-valore delle proprietà di tracciamento distribuito.

Application Insights definisce anche l'estensione per il protocollo HTTP di correlazione. Usa le coppie nome-valore Request-Context per propagare la raccolta di proprietà usate dal chiamante o dal destinatario della chiamata. Il SDK di Application Insights utilizza questo header per impostare i campi dependency.target e request.source.

I modelli di dati W3C Trace-Context e Application Insights sono mappati nel modo seguente:

Per altre informazioni, vedere Modello di dati di telemetria di Application Insights.

Campionamento

Per impostazione predefinita, l'SDK invia tutti i dati raccolti al servizio Application Insights. Se si desidera abilitare il campionamento e ridurre la quantità di dati, impostare il campo samplingPercentage sull'oggetto config di un client. L'impostazione samplingPercentage su 100 (impostazione predefinita) indica che tutti i dati saranno inviati, mentre 0 indica che non vi sarà alcun invio.

Se si usa la correlazione automatica, tutti i dati associati a una singola richiesta vengono inclusi o esclusi come un'unica unità.

Aggiungere del codice come il seguente per abilitare il campionamento:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

Più ruoli per applicazioni multi-componente

In alcuni scenari, l'applicazione potrebbe essere costituita da più componenti che si desidera instrumentare, tutti con la stessa stringa di connessione. Nel portale si vogliono comunque visualizzare questi componenti come unità separate, come se stessero utilizzando stringhe di connessione separate. Un esempio è costituito dai nodi separati nella Mappa delle applicazioni. È necessario configurare manualmente il campo RoleName per distinguere i dati di telemetria di un componente dagli altri componenti che inviano dati alla risorsa di Application Insights.

Usare il codice seguente per impostare il campo RoleName:

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

Caricatore dell'SDK del browser

La strumentazione Web automatica può essere abilitata per il server del nodo tramite l'inserimento di script del caricatore dell'SDK JavaScript (Web) per configurazione.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

oppure impostando la variabile di ambiente APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = true.

La strumentazione Web è abilitata nelle risposte del server del nodo quando vengono soddisfatti tutti i requisiti seguenti:

• La risposta ha il codice di stato 200.
• Il metodo di risposta è GET.
• La risposta del server ha Content-Type html.
• La risposta del server contiene i tag <head> e </head>.
• Se la risposta è compressa, deve avere un solo tipo Content-Encoding e il tipo di codifica deve essere uno tra gzip, br o deflate.
• La risposta non contiene gli endpoint correnti/di backup della rete CDN della strumentazione Web. (endpoint correnti e di backup della rete CDN della strumentazione Web qui)

L'endpoint della rete CDN di Strumentazione Web può essere modificato impostando la variabile APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints"di ambiente . La stringa di connessione di Strumentazione Web può essere modificata impostando la variabile di ambiente APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

Strumentazione automatica di terze parti

Per tenere traccia del contesto tra chiamate asincrone, sono richieste alcune modifiche nelle librerie di terze parti, ad esempio MongoDB e Redis. Per impostazione predefinita, Application Insights usa diagnostic-channel-publishers per applicare delle patch ad alcune di queste librerie. Questa funzionalità può essere disabilitata impostando la variabile di ambiente APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL.

Le singole patch possono essere disabilitate impostando la variabile di ambiente APPLICATION_INSIGHTS_NO_PATCH_MODULES su un elenco delimitato da virgole di pacchetti da disabilitare. Ad esempio, usare APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis per evitare di applicare patch ai pacchetti console e redis.

Attualmente sono instrumentati nove pacchetti: bunyan,console,mongodb,mongodb-core,mysql,redis,winston,pg e pg-pool. Per informazioni sulla versione esatta di questi pacchetti con patch, vedere il README di diagnostic-channel-publishers.

Le patch bunyan, winston e console generano eventi di traccia di Application Insights a seconda della scelta di abilitare o meno setAutoCollectConsole. Il resto genera eventi di dipendenza di Application Insights a seconda della scelta di abilitare o meno setAutoCollectDependencies.

Metriche in tempo reale

Per abilitare l'invio di metriche live dall'app ad Azure, usare setSendLiveMetrics(true). Attualmente, i filtri delle metriche live nel portale non sono supportati.

Metriche estese

Per abilitare l'invio di metriche native estese dall'app ad Azure, installare il pacchetto di metriche native separato. L'SDK si carica automaticamente quando viene installato e inizia a raccogliere le metriche native Node.js.

npm install applicationinsights-native-metrics

Attualmente, il pacchetto di metriche native esegue la raccolta automatica del tempo della CPU di Garbage Collection, dei tick del ciclo di eventi e dell'utilizzo dell'heap:

• Gestione dei rifiuti: La quantità di tempo della CPU impiegato per ogni tipo di gestione dei rifiuti e il numero di volte in cui ciascun tipo si verifica.
• Ciclo di eventi: numero di tick che si sono verificati e tempo della CPU impiegato in totale.
• Heap e non-heap: quanto della memoria dell'applicazione viene utilizzato nell'heap o nel non-heap.

Modalità di tracciamento distribuito

Per impostazione predefinita, l'SDK invia intestazioni riconosciute da altre applicazioni o servizi instrumentati con Application Insights SDK. È possibile abilitare l'invio e la ricezione di intestazioni del Contesto di traccia W3C, oltre alle intestazioni di IA esistenti. In questo modo, la correlazione con i servizi legacy esistenti non sarà interrotta. L'abilitazione delle intestazioni W3C consente all'app di correlarsi con altri servizi non instrumentati con Application Insights, ma che adottano questo standard W3C.

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

API TelemetryClient

Per una descrizione completa dell'API TelemetryClient, vedere API di Application Insights per metriche ed eventi personalizzati.

Con la libreria client di Application Insights per Node.js è possibile tenere traccia di qualsiasi richiesta, evento, metrica o eccezione. L'esempio di codice seguente illustra alcune API che è possibile usare:

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

Tenere traccia delle dipendenze

Usare il codice seguente per tenere traccia delle dipendenze:

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

Un'utilità di esempio che usa trackMetric per misurare il tempo necessario per la pianificazione del ciclo di eventi:

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

Aggiungi una proprietà personalizzata a tutti gli eventi

Usare il codice seguente per aggiungere una proprietà personalizzata a tutti gli eventi:

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

Tenere traccia delle richieste HTTP GET

Usare il codice seguente per tenere traccia manualmente delle richieste HTTP GET:

appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

In alternativa, è possibile rilevare le richieste usando il metodo trackNodeHttpRequest:

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

Tenere traccia del tempo di avvio del server

Usare il codice seguente per tenere traccia dell'ora di avvio del server:

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

Flush

Per impostazione predefinita, i dati di telemetria vengono memorizzati nel buffer per 15 secondi prima dell'invio al server di inserimento. Se l'applicazione ha una durata breve, ad esempio uno strumento dell'interfaccia della riga di comando, potrebbe essere necessario scaricare manualmente i dati di telemetria memorizzati nel buffer quando l'applicazione termina, usando appInsights.defaultClient.flush().

Se l'SDK rileva un arresto anomalo dell'applicazione, chiama lo scaricamento per l'utente usando appInsights.defaultClient.flush({ isAppCrashing: true }). Con l'opzione di svuotamento isAppCrashing, si presume che l'applicazione sia in stato anomalo e non sia adatta per inviare telemetria. L'SDK salva invece tutti i dati di telemetria memorizzati nel buffer nell'archiviazione permanente e consente all'applicazione di essere terminata. Quando si riavvia, l'applicazione tenta di inviare tutti i dati di telemetria salvati nell'archiviazione permanente.

Filtrare e pre-elaborare i dati di telemetria

È possibile scrivere codice per filtrare, modificare o arricchire i dati di telemetria prima dell'invio dall'SDK. L'elaborazione include i dati inviati dai moduli di telemetria standard, ad esempio la raccolta di richieste HTTP e la raccolta delle dipendenze.

• Il filtro può modificare o rimuovere i dati di telemetria prima che vengano inviati dall'SDK implementando ITelemetryProcessor. Ad esempio, è possibile ridurre il volume di dati di telemetria escludendo le richieste dai robot. A differenza del campionamento, si ha il controllo completo su ciò che viene inviato o rimosso, ma influisce su qualsiasi metrica basata su log aggregati. A seconda della modalità di eliminazione degli elementi, è anche possibile perdere la possibilità di spostarsi tra gli elementi correlati.

• Aggiungere o modificare proprietà a tutti i dati di telemetria inviati dall'app implementando un oggetto ITelemetryInitializer. Ad esempio, è possibile aggiungere valori calcolati o numeri di versione in base ai quali filtrare i dati nel portale.

• Il campionamento riduce il volume di dati di telemetria senza influire sulle statistiche. Mantiene insieme i punti dati correlati in modo che sia possibile spostarsi tra di essi durante la diagnosi di un problema. Nel portale i conteggi totali vengono moltiplicati per compensare il campionamento.

Filtraggio

Questa tecnica consente di controllare direttamente gli elementi inclusi o esclusi dal flusso di telemetria. Il filtro può essere usato per eliminare gli elementi di telemetria dall'invio ad Application Insights. È possibile usare il filtro con il campionamento o separatamente.

Per filtrare i dati di telemetria, scrivere un processore di telemetria e registrarlo con TelemetryConfiguration. Tutti i dati di telemetria passano attraverso il processore. È possibile scegliere di rilasciarlo dal flusso o assegnarlo al processore successivo nella catena. I dati di telemetria dai moduli standard, ad esempio l'agente di raccolta richieste HTTP e l'agente di raccolta dipendenze, e i dati di telemetria rilevati manualmente sono inclusi. Ad esempio, è possibile filtrare i dati di telemetria relativi alle richieste dei robot o alle chiamate di dipendenza riuscite.

ITelemetryProcessor e ITelemetryInitializer

Qual è la differenza tra processori di telemetria e inizializzatori di telemetria?

• Ci sono alcune sovrapposizioni in ciò che è possibile fare con loro. Entrambi possono essere usati per aggiungere o modificare le proprietà dei dati di telemetria, anche se è consigliabile usare gli inizializzatori a tale scopo.
• Gli inizializzatori di telemetria vengono sempre eseguiti prima dei processori di telemetria.
• Gli inizializzatori di telemetria possono essere chiamati più volte. Per convenzione, non impostano alcuna proprietà già impostata.
• I processori di telemetria consentono di sostituire o rimuovere completamente un elemento di telemetria.
• Tutti gli inizializzatori di telemetria registrati vengono chiamati per ogni elemento di telemetria. Per i processori di telemetria, SDK garantisce la chiamata al primo processore di telemetria. Se il resto dei processori viene chiamato o meno viene deciso dai processori di telemetria precedenti.
• Usare gli inizializzatori di telemetria per arricchire i dati di telemetria con più proprietà o eseguire l'override di uno esistente. Usare un processore di telemetria per filtrare i dati di telemetria.

Aggiungere/modificare le proprietà

Usare gli inizializzatori di telemetria per arricchire i dati di telemetria con informazioni aggiuntive o per eseguire l'override delle proprietà di telemetria impostate dai moduli di telemetria standard.

Ad esempio, Application Insights per un pacchetto Web raccoglie i dati di telemetria sulle richieste HTTP. Per impostazione predefinita, contrassegna qualsiasi richiesta con un codice >di risposta =400 come non riuscita. Se invece si vuole considerare 400 come un risultato positivo, è possibile fornire un inizializzatore di telemetria che imposti la proprietà Success.

Se si specifica un inizializzatore di telemetria, viene chiamato ogni volta che viene chiamato uno dei metodi Track*(). Questo inizializzatore include Track() metodi chiamati dai moduli di telemetria standard. Per convenzione, questi moduli non impostano alcuna proprietà già impostata da un inizializzatore. Gli inizializzatori di telemetria vengono chiamati prima di chiamare i processori di telemetria, quindi tutti gli arricchimenti eseguiti dagli inizializzatori sono visibili ai processori.

Pre-elaborare i dati con i processori di telemetria

È possibile elaborare e filtrare i dati raccolti prima dell'invio per la conservazione usando i processori di telemetria. I processori di telemetria vengono chiamati uno alla volta, nell'ordine in cui sono stati aggiunti prima dell'invio dell'elemento di telemetria al cloud.

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

Se un processore di telemetria restituisce false, l'elemento di telemetria non viene inviato.

Tutti i processori di telemetria ricevono i dati di telemetria e la relativa busta per l'ispezione e la modifica. Inoltre, ricevono un oggetto di contesto. Il contenuto di questo oggetto viene definito dal parametro contextObjects quando si chiama un metodo di rilevamento dei dati di telemetria rilevati manualmente. Per i dati di telemetria raccolti automaticamente, questo oggetto viene compilato con le informazioni disponibili sulla richiesta e con il contenuto della richiesta persistente fornito da appInsights.getCorrelationContext() (se è abilitata la correlazione automatica delle dipendenze).

Il tipo TypeScript per un processore di telemetria è:

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

Ad esempio, un processore che rimuove i dati di traccia degli stack dalle eccezioni può essere scritto e aggiunto come segue:

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

Aggiungere un nome del ruolo cloud e un'istanza del ruolo cloud

Impostare il nome del ruolo cloud tramite tag di contesto diretto:

var appInsights = require("applicationinsights");
appInsights.setup('INSTRUMENTATION_KEY').start();
appInsights.defaultClient.context.tags["ai.cloud.role"] = "your role name";
appInsights.defaultClient.context.tags["ai.cloud.roleInstance"] = "your role instance";

Impostare il nome del ruolo cloud tramite il processore di telemetria:

var appInsights = require("applicationinsights");
appInsights.setup('INSTRUMENTATION_KEY').start();

appInsights.defaultClient.addTelemetryProcessor(envelope => {
    envelope.tags["ai.cloud.role"] = "your role name";
    envelope.tags["ai.cloud.roleInstance"] = "your role instance"
});

Usare più stringhe di connessione

È possibile creare più risorse di Application Insights e inviare dati diversi a ciascuna di esse usando le rispettive stringhe di connessione.

Ad esempio:

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

Opzioni di configurazione avanzate

L'oggetto client contiene una proprietà config con molte impostazioni facoltative per scenari avanzati. Per impostarli, usare:

client.config.PROPERTYNAME = VALUE;

Queste proprietà sono specifiche del client, pertanto è possibile configurare appInsights.defaultClient separatamente dai client creati con new appInsights.TelemetryClient().

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

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

1. Aggiungere Application Insights SDK al progetto.

2. Nel codice del dispositivo o del server Web includere:

   • .NET
   • Node.js

   using Microsoft.ApplicationInsights;
   

Ottenere un'istanza di TelemetryClient

Ottenere un'istanza di TelemetryClient:

private TelemetryClient telemetry = new TelemetryClient();

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

var telemetry = applicationInsights.defaultClient;

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

Inserire chiamate TrackEvent nel codice per contare i 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");

telemetry.trackEvent({name: "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 potrebbero provenire da trackEvent(..) o dal plug-in Click Analytics Autocollection.

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

GetMetric

Per informazioni su come usare in modo efficace la GetMetric() chiamata per acquisire metriche preaggregate in locale per le applicazioni .NET e .NET Core, vedere Raccolta di metriche personalizzate in .NET e .NET Core.

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:

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

telemetry.trackMetric({name: "queueLength", value: 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.

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

Quando si tiene traccia dei dati di telemetria manualmente, il modo più semplice per garantire la correlazione dei dati di telemetria consiste nell'usare questo modello:

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here uses the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

// Establish an operation context and associated telemetry item:
const operation = appInsights.startOperation(client, { name: "operationName" });

appInsights.wrapWithCorrelationContext(() => {
    // Telemetry sent in here uses the same operation ID.
    ...
    client.trackTrace({ message: "..." }); // or other track* calls
    ...

    // Set properties of containing telemetry item—for example:
    operation.telemetry.responseCode = "200";

    // Optional: explicitly send telemetry item:
    client.stopOperation(operation);

}, operation.context)(); // When callback completes, telemetry item is sent.

Insieme all'impostazione di un contesto dell'operazione, StartOperation crea un elemento di telemetria del tipo specificato. Invia l'elemento di telemetria quando si elimina l'operazione o si chiama esplicitamente StopOperation. Se si usa RequestTelemetry come tipo di telemetria, la relativa durata viene impostata sull'intervallo di tempo compreso tra inizio e arresto.

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 .

Per altre informazioni sul rilevamento delle operazioni personalizzate, vedere Tenere traccia delle operazioni personalizzate con Application Insights .NET SDK.

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:

• Per contarli, come indicazione della frequenza di un problema.
• Per esaminare le singole occorrenze.

I report includono le analisi dello stack.

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

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

Gli SDK rilevano automaticamente molte eccezioni, 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. Ad 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 mediante l'invio di una traccia di navigazione ad Application Insights. È possibile inviare blocchi di dati di diagnostica ed esaminarli in Ricerca diagnostica.

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

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

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

È 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. Ad esempio:

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

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.

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

Tenere presente che gli SDK del server includono un modulo di dipendenza che individua e tiene traccia di determinate chiamate di dipendenza automaticamente, ad esempio ai database e alle API REST. È necessario installare un agente nel server per eseguire il funzionamento del modulo.

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

Per disattivare il modulo di rilevamento delle dipendenze standard in C#, modificare ApplicationInsights.config ed eliminare il riferimento a DependencyCollector.DependencyTrackingTelemetryModule.

Dipendenze in Log Analytics

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

Se il campionamento è attivo, la proprietà itemCount 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, è possibile 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 shutdown.
System.Threading.Thread.Sleep(5000);

await telemetryClient.FlushAsync()
// No need to sleep

telemetry.flush();

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.

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Modo alternativo per impostare proprietà e metriche

Se è più conveniente, è possibile raccogliere i parametri di un evento in un oggetto separato:

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

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 da customDimensions o customMeasurements JSON, esso ha un tipo dinamico, quindi è necessario eseguire un cast a tostring o a todouble.
• Per tener conto della possibilità di campionamento, usare sum(itemCount) e non count().

Eventi di temporizzazione

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.

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

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

Proprietà predefinite per i dati di telemetria personalizzati

Se si desidera impostare i valori predefiniti delle proprietà per alcuni degli eventi personalizzati che si scrivono, impostarli in un'istanza di TelemetryClient. Sono collegati a ogni elemento di telemetria inviato da tale client.

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry is automatically sent with the context property:
gameTelemetry.TrackEvent("WinGame");

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

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

Per aggiungere proprietà a tutti i dati di telemetria, inclusi i dati dei moduli di raccolta standard, implementare ITelemetryInitializer.

Disabilitare telemetria

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

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

telemetry.config.disableAppInsights = true;

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

Modalità sviluppatore

Durante il debug, è utile che i dati di telemetria vengano accelerati attraverso la pipeline in modo da poter visualizzare immediatamente i risultati. Si ottengono anche altri messaggi che consentono di tracciare eventuali problemi con i dati di telemetria. Disattivarlo nell'ambiente di produzione perché potrebbe rallentare l'app.

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

Imposta la chiave di strumentazione per la telemetria personalizzata selezionata

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

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 modificarne le chiavi, a seconda dell'ambiente.

Anziché ottenere la chiave di strumentazione dal file di configurazione, è possibile impostarla nel codice. Impostare la chiave in un metodo di inizializzazione, ad esempio global.aspx.cs in un servizio ASP.NET:

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

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. Ad 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. In genere viene prelevato da ApplicationInsights.config.
• 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.

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.

Risoluzione dei problemi

Per informazioni sulla risoluzione dei problemi, inclusi gli scenari "nessun dato" e la personalizzazione dei log, vedere Risolvere i problemi di monitoraggio di Application Insights per le app e i servizi Node.js.

Passaggi successivi

• Per esaminare le domande frequenti, vedere:
  • Domande frequenti suNode.js
  • Domande frequenti sull'API di Application Insights per eventi personalizzati e metriche
• Monitorare i dati di telemetria nel portale.
• Informazioni su come usare Log Analytics e scrivere query di analisi sui dati di telemetria.