Monitorare servizi e app Node.js con Application InsightsMonitor your Node.js services and apps with Application Insights

Azure Application Insights monitora i componenti e i servizi back-end dopo la distribuzione, per consentire di individuare e diagnosticare rapidamente i problemi di prestazioni e di altro tipo.Azure Application Insights monitors your backend services and components after deployment, to help you discover and rapidly diagnose performance and other issues. È possibile usare Azure Application Insights per i servizi Node.js ospitati nel data center locale, in app Web, in VM di Azure e anche in altri cloud pubblici.You can use Application Insights for Node.js services that are hosted in your datacenter, in Azure VMs and web apps, and even in other public clouds.

Per ricevere, archiviare ed esplorare i dati di monitoraggio, includere l'SDK nel codice e quindi configurare una risorsa di Application Insights corrispondente in Azure.To receive, store, and explore your monitoring data, include the SDK in your code, and then set up a corresponding Application Insights resource in Azure. L'SDK invia i dati a tale risorsa per ulteriori attività di analisi ed esplorazione.The SDK sends data to that resource for further analysis and exploration.

Node.js SDK può monitorare automaticamente le richieste HTTP in ingresso e in uscita, le eccezioni e alcune metriche di sistema.The Node.js SDK can automatically monitor incoming and outgoing HTTP requests, exceptions, and some system metrics. A partire dalla versione 0.20, l'SDK può anche monitorare alcuni pacchetti comuni di terze parti, ad esempio MongoDB, MySQL e Redis.Beginning in version 0.20, the SDK also can monitor some common third-party packages, like MongoDB, MySQL, and Redis. Tutti gli eventi relativi a una richiesta HTTP in ingresso vengono correlati per velocizzare la risoluzione dei problemi.All events related to an incoming HTTP request are correlated for faster troubleshooting.

È possibile usare l'API TelemetryClient per instrumentare e monitorare manualmente altri aspetti dell'app e del sistema.You can use the TelemetryClient API to manually instrument and monitor additional aspects of your app and system. L'API TelemetryClient viene descritta in modo più dettagliato più avanti nell'articolo.We describe the TelemetryClient API in more detail later in this article.

Grafici di monitoraggio delle prestazioni di esempio

Attività inizialiGet started

Completare le attività seguenti per configurare il monitoraggio per un'app o un servizio.Complete the following tasks to set up monitoring for an app or service.

PrerequisitiPrerequisites

Prima di iniziare, verificare di avere una sottoscrizione di Azure oppure ottenerne una nuova gratuitamente.Before you begin, make sure that you have an Azure subscription, or get a new one for free. Se l'organizzazione ha già una sottoscrizione di Azure, un amministratore può aggiungere l'utente alla sottoscrizione seguendo queste istruzioni.If your organization already has an Azure subscription, an administrator can follow these instructions to add you to it.

Configurare una risorsa di Application InsightsSet up an Application Insights resource

  1. Accedere al portale di Azure.Sign in to the Azure portal.
  2. Selezionare Nuovo > Strumenti di sviluppo > Application Insights.Select New > Developer tools > Application Insights. La risorsa include un endpoint per la ricezione dei dati di telemetria, l'archiviazione di tali dati, dei report salvati e dei dashboard, la configurazione di regole e avvisi e altro ancora.The resource includes an endpoint for receiving telemetry data, storage for this data, saved reports and dashboards, rule and alert configuration, and more.

    Creare una risorsa Application Insights

  3. Nella pagina di creazione della risorsa scegliere Applicazione Node.js nella casella Tipo di applicazione.On the resource creation page, in the Application Type box, select Node.js Application. Il tipo di app determina i dashboard e i report predefiniti che vengono creati.The app type determines the default dashboards and reports that are created. Qualsiasi risorsa di Application Insights può raccogliere dati da qualsiasi linguaggio e piattaforma.(Any Application Insights resource can collect data from any language and platform.)

    Modulo per la nuova risorsa di Application Insights

Configurare Node.js SDKSet up the Node.js SDK

Includere l'SDK nell'app affinché possa raccogliere i dati.Include the SDK in your app, so it can gather data.

  1. Copiare la chiave di strumentazione della risorsa (detta anche ikey) dal portale di Azure.Copy your resource's Instrumentation Key (also called an ikey) from the Azure portal. Application Insights usa la chiave di strumentazione per eseguire il mapping dei dati alla risorsa di Azure.Application Insights uses the ikey to map data to your Azure resource. Affinché l'SDK possa usare la chiave di strumentazione, è necessario specificare tale chiave in una variabile di ambiente o nel codice.Before the SDK can use your ikey, you must specify the ikey in an environment variable or in your code.

    Copiare la chiave di strumentazione

  2. Aggiungere la libreria Node.js SDK alle dipendenze dell'app tramite package.json.Add the Node.js SDK library to your app's dependencies via package.json. Dalla cartella radice dell'app eseguire:From the root folder of your app, run:

    npm install applicationinsights --save
    
  3. Caricare in modo esplicito la libreria nel codice.Explicitly load the library in your code. Dato che l'SDK inserisce la strumentazione in molte altre librerie, caricare la libreria il prima possibile, anche prima di altre istruzioni require.Because the SDK injects instrumentation into many other libraries, load the library as early as possible, even before other require statements.

    All'inizio del primo file con estensione js aggiungere il codice seguente.At the top of your first .js file, add the following code. Il metodo setup configura la chiave di strumentazione, e quindi la risorsa di Azure, da usare per impostazione predefinita per tutti gli elementi monitorati.The setup method configures the ikey (and thus, the Azure resource) to be used by default for all tracked items.

    const appInsights = require("applicationinsights");
    appInsights.setup("<instrumentation_key>");
    appInsights.start();
    

    È anche possibile specificare una chiave di strumentazione tramite la variabile di ambiente APPINSIGHTS_INSTRUMENTATIONKEY, invece di passarla manualmente a setup() o new appInsights.TelemetryClient().You also can provide an ikey via the environment variable APPINSIGHTS_INSTRUMENTATIONKEY, instead of passing it manually to setup() or new appInsights.TelemetryClient(). Questa procedura consente di non includere le chiavi di strumentazione nel codice sorgente sottoposto a commit e di specificare chiavi di strumentazione diverse per ambienti diversi.This practice lets you keep ikeys out of committed source code, and you can specify different ikeys for different environments.

    Per altre opzioni di configurazione, vedere le sezioni seguenti.For additional configuration options, see the following sections.

    È possibile provare l'SDK senza inviare i dati di telemetria impostando appInsights.defaultClient.config.disableAppInsights = true.You can try the SDK without sending telemetry by setting appInsights.defaultClient.config.disableAppInsights = true.

Monitorare l'appMonitor your app

L'SDK raccoglie automaticamente dati di telemetria sul runtime Node.js e su alcuni moduli comuni di terze parti.The SDK automatically gathers telemetry about the Node.js runtime and about some common third-party modules. Usare l'applicazione per generare alcuni di questi dati.Use your application to generate some of this data.

Nel portale di Azure passare quindi alla risorsa di Application Insights creata in precedenza.Then, in the Azure portal go to the Application Insights resource that you created earlier. In Panoramica sequenza temporale cercare i primi punti dati.In the Overview timeline, look for your first few data points. Per visualizzare altri dati dettagliati, selezionare diversi componenti nei grafici.To see more detailed data, select different components in the charts.

Primi punti dati

Per visualizzare la topologia individuata per l'app, fare clic sul pulsante Mappa delle applicazioni.To view the topology that is discovered for your app, select the Application map button. Selezionare i componenti nella mappa per vedere altri dettagli.Select components in the map to see more details.

Mappa app di esempio

Per altre informazioni sull'app e per risolvere i problemi, nella sezione RICERCA CAUSA selezionare le altre visualizzazioni disponibili.To learn more about your app, and to troubleshoot problems, in the INVESTIGATE section, select the other views that are available.

Sezione Analisi

Dati non visualizzatiNo data?

Dato che l'SDK esegue l'invio dei dati in batch, potrebbe verificarsi un ritardo nella visualizzazione degli elementi nel portale.Because the SDK batches data for submission, there might be a delay before items are displayed in the portal. Se i dati non sono visibili nella risorsa, provare alcune delle correzioni seguenti:If you don't see data in your resource, try some of the following fixes:

  • Continuare a usare l'applicazione.Continue to use the application. Eseguire altre azioni per generare dati di telemetria aggiuntivi.Take more actions to generate more telemetry.
  • Fare clic su Aggiorna nella visualizzazione della risorsa nel portale.Click Refresh in the portal resource view. I grafici si aggiornano periodicamente in automatico, ma l'aggiornamento manuale ha effetto immediato.Charts periodically refresh on their own, but manually refreshing forces them to refresh immediately.
  • Verificare che le porte in uscita necessarie siano aperte.Verify that required outgoing ports are open.
  • Usare l'opzione Cerca per cercare eventi specifici.Use Search to look for specific events.
  • Vedere le domande frequenti.Check the FAQ.

Configurazione dell'SDKSDK configuration

I metodi di configurazione dell'SDK e i valori predefiniti sono indicati nell'esempio di codice seguente.The SDK's configuration methods and default values are listed in the following code example.

Per correlare completamente gli eventi in un servizio, assicurarsi di impostare .setAutoDependencyCorrelation(true).To fully correlate events in a service, be sure to set .setAutoDependencyCorrelation(true). Con questa opzione impostata, l'SDK può tenere traccia del contesto tra callback asincroni in Node.js.With this option set, the SDK can track context across asynchronous callbacks in Node.js.

const appInsights = require("applicationinsights");
appInsights.setup("<instrumentation_key>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .start();

API TelemetryClientTelemetryClient API

Per una descrizione completa dell'API TelemetryClient, vedere API di Application Insights per metriche ed eventi personalizzati.For a full description of the TelemetryClient API, see Application Insights API for custom events and metrics.

Con Application Insights Node.js SDK è possibile tenere traccia di qualsiasi richiesta, evento, metrica o eccezione.You can track any request, event, metric, or exception by using the Application Insights Node.js SDK. L'esempio di codice seguente illustra alcune API che è possibile usare:The following code example demonstrates some of the APIs that you can use:

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming ikey is in env var
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 dipendenzeTrack your dependencies

Usare il codice seguente per tenere traccia delle dipendenze:Use the following code to track your dependencies:

let appInsights = require("applicationinsights");
let client = appInsights.defaultClient;

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

client.trackDependency({dependencyTypeName: "dependency name", name: "command name", duration: duration, success: success});

Aggiungere una proprietà personalizzata a tutti gli eventiAdd a custom property to all events

Usare il codice seguente per aggiungere una proprietà personalizzata a tutti gli eventi:Use the following code to add a custom property to all events:

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

Tenere traccia delle richieste HTTP GETTrack HTTP GET requests

Usare il codice seguente per tenere traccia delle richieste HTTP GET:Use the following code to track HTTP GET requests:

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 serverTrack server startup time

Usare il codice seguente per tenere traccia dell'ora di avvio del server:Use the following code to track server startup time:

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

Passaggi successiviNext steps