Monitorare servizi e app Node.js con Application Insights

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.

Operazioni preliminari

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. Aggiungere la libreria client Node.js alle dipendenze dell'app tramite package.json. Dalla cartella radice dell'app eseguire:

   npm install applicationinsights --save
   

   Nota

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

3. Caricare in modo esplicito la libreria nel 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.

Esaminare le descrizioni nell'hint del tipo IDE predefinito o applicationinsights.ts per informazioni dettagliate e gli argomenti secondari facoltativi.

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 della strumentazione Web può essere modificato impostando la variabile di ambiente APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints". La stringa di connessione della 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 attive

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:

• Garbage Collection: quantità di tempo della CPU impiegato per ogni tipo di Garbage Collection e numero di occorrenze di ciascun tipo.
• Ciclo di eventi: numero di tick che si sono verificati e tempo della CPU impiegato in totale.
• Heap e non heap: quantità di utilizzo heap o non heap della memoria dell'applicazione.

Modalità della traccia distribuita

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

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

Svuotamento

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 per scaricare isAppCrashing, si presuppone che l'applicazione sia in stato anomalo e non sia adatta per inviare i dati di 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.

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 gli stack di dati di traccia dalle eccezioni può essere scritto e aggiunto nel modo seguente:

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

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

Domande frequenti

In che modo è possibile disabilitare la correlazione dei dati di telemetria?

Per disabilitare la correlazione dei dati di telemetria, usare la proprietà correlationHeaderExcludedDomains nella configurazione. Per altre informazioni, vedere ApplicationInsights-node.js.

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

• Monitorare i dati di telemetria nel portale
• Presentazione dello strumento Analisi in Application Insights