Überwachen Ihrer Node.js-Dienste und -Apps mit Application InsightsMonitor your Node.js services and apps with Application Insights

Mit Azure Application Insights werden Ihre Back-End-Dienste und -Komponenten nach der Bereitstellung überwacht, damit Sie Leistungsprobleme und andere Probleme erkennen und schnell diagnostizieren können.Azure Application Insights monitors your backend services and components after deployment, to help you discover and rapidly diagnose performance and other issues. Sie können Application Insights für Node.js-Dienste verwenden, die in Ihrem Datencenter, auf Azure-VMs und in Web-Apps und sogar in anderen öffentlichen Clouds gehostet werden.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.

Fügen Sie das SDK in Ihren Code ein, und richten Sie dann in Azure eine entsprechende Application Insights-Ressource ein, um Ihre Überwachungsdaten zu empfangen, zu speichern und zu untersuchen.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. Das SDK sendet Daten zur weiteren Analyse und Untersuchung an diese Ressource.The SDK sends data to that resource for further analysis and exploration.

Das Node.js SDK kann ein- und ausgehende HTTP-Anforderungen, Ausnahmen und einige Systemmetriken automatisch überwachen.The Node.js SDK can automatically monitor incoming and outgoing HTTP requests, exceptions, and some system metrics. Ab Version 0.20 kann das SDK auch einige Drittanbieterpakete überwachen, z.B. MongoDB, MySQL und Redis.Beginning in version 0.20, the SDK also can monitor some common third-party packages, like MongoDB, MySQL, and Redis. Alle Ereignisse, die sich auf eine eingehende HTTP-Anforderung beziehen, werden zur Beschleunigung der Problembehandlung korreliert.All events related to an incoming HTTP request are correlated for faster troubleshooting.

Sie können die TelemetryClient-API verwenden, um weitere Aspekte Ihrer App und Ihres Systems manuell zu instrumentieren und zu überwachen.You can use the TelemetryClient API to manually instrument and monitor additional aspects of your app and system. Die TelemetryClient-API wird weiter unten in diesem Artikel näher beschrieben.We describe the TelemetryClient API in more detail later in this article.

Erste SchritteGet started

Führen Sie die folgenden Aufgaben durch, um die Überwachung für eine App oder einen Dienst einzurichten.Complete the following tasks to set up monitoring for an app or service.

VoraussetzungenPrerequisites

Stellen Sie zuerst sicher, dass Sie über ein Azure-Abonnement verfügen, oder beschaffen Sie sich kostenlos ein neues Abonnement.Before you begin, make sure that you have an Azure subscription, or get a new one for free. Falls Ihre Organisation bereits über ein Azure-Abonnement verfügt, kann Ihr Administrator Sie anhand dieser Anleitung hinzufügen.If your organization already has an Azure subscription, an administrator can follow these instructions to add you to it.

Einrichten einer Application Insights-RessourceSet up an Application Insights resource

  1. Melden Sie sich beim Azure-Portal an.Sign in to the Azure portal.

  2. Klicken Sie auf Ressource erstellen > Entwicklertools > Application Insights.Select Create a resource > Developer tools > Application Insights. Die Ressource enthält u.a. einen Endpunkt zum Empfangen von Telemetriedaten, Speicherplatz für diese Daten, gespeicherte Berichte und Dashboards, eine Regel- und Warnungskonfiguration.The resource includes an endpoint for receiving telemetry data, storage for this data, saved reports and dashboards, rule and alert configuration, and more.

  3. Wählen Sie auf der Seite für die Ressourcenerstellung im Feld Anwendungstyp die Option Node.js-Anwendung.On the resource creation page, in the Application Type box, select Node.js Application. Der App-Typ bestimmt, welche Dashboards und Berichte erstellt werden.The app type determines the default dashboards and reports that are created. (Alle Application Insights-Ressourcen können Daten für jede Sprache und Plattform sammeln.)(Any Application Insights resource can collect data from any language and platform.)

Einrichten des Node.js-SDKSet up the Node.js SDK

Fügen Sie das SDK in Ihre App ein, damit Daten gesammelt werden können.Include the SDK in your app, so it can gather data.

  1. Kopieren Sie den Instrumentierungsschlüssel der Ressource (auch als ikey bezeichnet) aus dem Azure-Portal.Copy your resource's Instrumentation Key (also called an ikey) from the Azure portal. Der ikey wird von Application Insights verwendet, um Ihrer Azure-Ressource Daten zuzuordnen.Application Insights uses the ikey to map data to your Azure resource. Bevor Ihr ikey vom SDK verwendet werden kann, müssen Sie ihn in einer Umgebungsvariablen oder im Code angeben.Before the SDK can use your ikey, you must specify the ikey in an environment variable or in your code.

    Kopieren des Instrumentierungsschlüssels

  2. Fügen Sie die Node.js-SDK-Bibliothek per „package.json“ den Abhängigkeiten Ihrer App hinzu.Add the Node.js SDK library to your app's dependencies via package.json. Führen Sie im Stammordner Ihrer App Folgendes aus:From the root folder of your app, run:

    npm install applicationinsights --save
    
  3. Laden Sie die Bibliothek explizit im Code.Explicitly load the library in your code. Da das SDK die Instrumentierung auch in viele andere Bibliotheken einbettet, sollten Sie die Bibliothek so früh wie möglich laden – noch vor anderen require-Anweisungen.Because the SDK injects instrumentation into many other libraries, load the library as early as possible, even before other require statements.

    Fügen Sie oben in Ihrer ersten JS-Datei den folgenden Code hinzu.At the top of your first .js file, add the following code. Mit der setup-Methode wird der ikey (und somit die Azure-Ressource) konfiguriert, der standardmäßig für alle nachverfolgten Elemente verwendet werden soll.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();
    

    Sie können einen ikey auch über die Umgebungsvariable „APPINSIGHTS_INSTRUMENTATIONKEY“ bereitstellen, anstatt ihn manuell an setup() oder new appInsights.TelemetryClient() zu übergeben.You also can provide an ikey via the environment variable APPINSIGHTS_INSTRUMENTATIONKEY, instead of passing it manually to setup() or new appInsights.TelemetryClient(). Mit dieser Vorgehensweise können Sie ikeys aus festgelegtem Quellcode heraushalten und unterschiedliche ikeys für unterschiedliche Umgebungen angeben.This practice lets you keep ikeys out of committed source code, and you can specify different ikeys for different environments.

    Weitere Konfigurationsoptionen finden Sie in den folgenden Abschnitten.For additional configuration options, see the following sections.

    Sie können das SDK auch ohne das Senden von Telemetriedaten testen, indem Sie appInsights.defaultClient.config.disableAppInsights = true festlegen.You can try the SDK without sending telemetry by setting appInsights.defaultClient.config.disableAppInsights = true.

Überwachen Ihrer AppMonitor your app

Das SDK sammelt automatisch Telemetriedaten zur Node.js-Laufzeit und zu einigen Drittanbietermodulen.The SDK automatically gathers telemetry about the Node.js runtime and about some common third-party modules. Verwenden Sie Ihre Anwendung, um einige dieser Daten zu generieren.Use your application to generate some of this data.

Navigieren Sie im Azure-Portal dann zu der zuvor erstellten Application Insights-Ressource.Then, in the Azure portal go to the Application Insights resource that you created earlier. Suchen Sie in der Übersichtszeitachse nach Ihren ersten Datenpunkten.In the Overview timeline, look for your first few data points. Wählen Sie in den Diagrammen verschiedene Komponenten aus, um detailliertere Daten anzuzeigen.To see more detailed data, select different components in the charts.

Wählen Sie zum Anzeigen der Topologie, die für Ihre App ermittelt wird, die Schaltfläche Anwendungszuordnung.To view the topology that is discovered for your app, select the Application map button. Wählen Sie Komponenten in der Karte aus, um weitere Details anzuzeigen.Select components in the map to see more details.

Einfache App-Zuordnung

Weitere Informationen zu Ihrer App und zur Problembehandlung erhalten Sie, indem Sie im Abschnitt UNTERSUCHEN die anderen verfügbaren Ansichten auswählen.To learn more about your app, and to troubleshoot problems, in the INVESTIGATE section, select the other views that are available.

Abschnitt „Untersuchen“

Sie sehen keine Daten?No data?

Da das SDK Daten zur Übermittlung in Batches zusammenfasst, kann es ggf. eine Weile dauern, bis die Elemente im Portal angezeigt werden.Because the SDK batches data for submission, there might be a delay before items are displayed in the portal. Falls in Ihrer Ressource keine Daten angezeigt werden, können Sie folgende Lösungsmöglichkeiten ausprobieren:If you don't see data in your resource, try some of the following fixes:

  • Fahren Sie mit der Verwendung der Anwendung fort.Continue to use the application. Führen Sie mehr Aktionen durch, um mehr Telemetriedaten zu generieren.Take more actions to generate more telemetry.
  • Klicken Sie in der Ressourcenansicht des Portals auf Aktualisieren.Click Refresh in the portal resource view. Diagramme aktualisieren sich regelmäßig selbst, aber bei der manuellen Aktualisierung wird der Vorgang sofort erzwungen.Charts periodically refresh on their own, but manually refreshing forces them to refresh immediately.
  • Stellen Sie sicher, dass die erforderlichen ausgehenden Ports geöffnet sind.Verify that required outgoing ports are open.
  • Verwenden Sie Suchen, um nach bestimmten Ereignissen zu suchen.Use Search to look for specific events.
  • Lesen Sie die häufig gestellten Fragen.Check the FAQ.

SDK-KonfigurationSDK configuration

Die Konfigurationsmethoden und Standardwerte des SDK sind im folgenden Codebeispiel aufgelistet.The SDK's configuration methods and default values are listed in the following code example.

Legen Sie .setAutoDependencyCorrelation(true) fest, um die Ereignisse für einen Dienst vollständig zu korrelieren.To fully correlate events in a service, be sure to set .setAutoDependencyCorrelation(true). Wenn diese Option festgelegt ist, kann das SDK den Kontext übergreifend für asynchrone Rückrufe in Node.js nachverfolgen.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();

TelemetryClient-APITelemetryClient API

Eine vollständige Beschreibung der TelemetryClient-API finden Sie unter Application Insights-API für benutzerdefinierte Ereignisse und Metriken.For a full description of the TelemetryClient API, see Application Insights API for custom events and metrics.

Sie können alle Anforderungen, Ereignisse, Metriken oder Ausnahmen mit dem Application Insights-Node.js-SDK nachverfolgen.You can track any request, event, metric, or exception by using the Application Insights Node.js SDK. Im folgenden Codebeispiel werden einige APIs veranschaulicht, die Sie verwenden können: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
});

Nachverfolgen Ihrer AbhängigkeitenTrack your dependencies

Nutzen Sie den folgenden Code, um Ihre Abhängigkeiten nachzuverfolgen: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});

Hinzufügen einer benutzerdefinierten Eigenschaft zu allen EreignissenAdd a custom property to all events

Verwenden Sie den folgenden Code, um allen Ereignissen eine benutzerdefinierte Eigenschaft hinzuzufügen:Use the following code to add a custom property to all events:

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

Nachverfolgen von HTTP GET-AnforderungenTrack HTTP GET requests

Verwenden Sie den folgenden Code, um HTTP GET-Anforderungen nachzuverfolgen: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();
});

Nachverfolgen der ServerstartzeitTrack server startup time

Verwenden Sie den folgenden Code, um die Serverstartzeit nachzuverfolgen: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});
});

Nächste SchritteNext steps