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

Mit 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.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 Rechenzentrum, auf virtuellen Azure-Computern, 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, 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. Erstellen Sie eine Application Insights-Ressource.Create an Application Insights resource

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 iKey genannt) aus der neu erstellten Ressource.Copy your resource's instrumentation Key (also called an ikey) from your newly created resource. 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
    

    Hinweis

    Installieren Sie bei Verwendung von TypeScript keine separaten Pakete mit Typisierungen.If you are using TypeScript, do not install separate "typings" packages. Dieses npm-Paket enthält integrierte Typisierungen.This NPM package contains built-in typings.

  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.

    let appInsights = require('applicationinsights');
    
  4. Sie können einen Instrumentierungsschlüssel 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. Rufen Sie für die manuelle Konfiguration appInsights.setup('[your ikey]'); auf.To configure manually call appInsights.setup('[your ikey]');.

    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.

  5. Rufen Sie appInsights.start(); auf, um mit dem automatischen Sammeln und Senden von Daten zu beginnen.Start automatically collecting and sending data by calling appInsights.start();.

Überwachen Ihrer AppMonitor your app

Das SDK sammelt automatisch Telemetriedaten zur Node.js-Laufzeit und zu einigen gängigen Drittanbietermodulen.The SDK automatically gathers telemetry about the Node.js runtime and 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.

Sie können die Topologie, die für Ihre App ermittelt wird, über die Anwendungsübersicht anzeigen.To view the topology that is discovered for your app, you can use Application map.

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

Grundlegende VerwendungBasic Usage

Für die sofort einsetzbare Sammlung von HTTP-Anforderungen, Ereignissen von beliebten Drittanbieterbibliotheken, nicht behandelten Ausnahmen und Systemmetriken:For out-of-the-box collection of HTTP requests, popular third-party library events, unhandled exceptions, and system metrics:


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

Hinweis

Ist der Instrumentierungsschlüssel in der Umgebungsvariable APPINSIGHTS_INSTRUMENTATIONKEY festgelegt, kann .setup() ohne Argumente aufgerufen werden.If the instrumentation key is set in the environment variable APPINSIGHTS_INSTRUMENTATIONKEY, .setup() can be called with no arguments. Dies erleichtert die Verwendung verschiedener Instrumentierungsschlüssel für unterschiedliche Umgebungen.This makes it easy to use different ikeys for different environments.

Laden Sie noch vor anderen Paketen die Application Insights-Bibliothek (require("applicationinsights")) so früh wie möglich in Ihre Skripts.Load the Application Insights library ,require("applicationinsights"), as early as possible in your scripts before loading other packages. Dies ist erforderlich, damit die Application Insights-Bibliothek spätere Pakete für die Nachverfolgung vorbereiten kann.This is needed so that the Application Insights library can prepare later packages for tracking. Treten Konflikte mit anderen Bibliotheken auf, die eine ähnliche Vorbereitung durchführen, laden Sie die Application Insights-Bibliothek nach diesen anderen Bibliotheken.If you encounter conflicts with other libraries doing similar preparation, try loading the Application Insights library after those.

Aufgrund der Art und Weise, wie JavaScript Rückrufe verarbeitet, sind für die Verfolgung einer Anforderung über mehrere externe Abhängigkeiten und spätere Rückrufe hinweg zusätzliche Arbeitsschritte erforderlich.Because of the way JavaScript handles callbacks, additional work is necessary to track a request across external dependencies and later callbacks. Diese zusätzliche Nachverfolgung ist standardmäßig aktiviert. Rufen Sie wie im Abschnitt Konfiguration unten beschrieben setAutoDependencyCorrelation(false) auf, um die Funktion zu deaktivieren.By default this additional tracking is enabled; disable it by calling setAutoDependencyCorrelation(false) as described in the configuration section below.

Migrieren von Versionen vor Version 0.22Migrating from versions prior to 0.22

Mit Version 0.22 wurden wichtige Änderungen eingeführt.There are breaking changes between releases prior to version 0.22 and after. Mit diesen Änderungen wurde die Konsistenz mit anderen Application Insights SDKs erhöht, und künftige Erweiterungen wurden ermöglicht.These changes are designed to bring consistency with other Application Insights SDKs and allow future extensibility.

Im Allgemeinen können Sie die Migration auf folgende Weise durchführen:In general, you can migrate with the following:

  • Ersetzen Sie Verweise auf appInsights.client durch appInsights.defaultClient.Replace references to appInsights.client with appInsights.defaultClient.
  • Ersetzen Sie Verweise auf appInsights.getClient() durch new appInsights.TelemetryClient().Replace references to appInsights.getClient() with new appInsights.TelemetryClient()
  • Ersetzen Sie alle Argumente für „client.track*“-Methoden durch ein einzelnes Objekt, das als Argumente benannte Eigenschaften enthält.Replace all arguments to client.track* methods with a single object containing named properties as arguments. Das erwartete Objekt der einzelnen Telemetrietypen finden Sie in den integrierten Typhinweisen Ihrer IDE oder unter TelemetryTypes.See your IDE's built-in type hinting or TelemetryTypes for the excepted object for each type of telemetry.

Wenn Sie ohne Verkettung mit appInsights.setup() auf die SDK-Konfigurationsfunktionen zugreifen, befinden sich diese Funktionen jetzt unter appInsights.Configurations (z. B. appInsights.Configuration.setAutoCollectDependencies(true)).If you access SDK configuration functions without chaining them to appInsights.setup(), you can now find these functions at appInsights.Configurations (for example, appInsights.Configuration.setAutoCollectDependencies(true)). Informationen zu Änderungen an der Standardkonfiguration finden Sie im nächsten Abschnitt.Review the changes to the default configuration in the next section.

SDK-KonfigurationSDK configuration

Das appInsights-Objekt stellt eine Reihe von Konfigurationsmethoden bereit.The appInsights object provides a number of configuration methods. Diese werden im folgenden Codeausschnitt mit den jeweiligen Standardwerten aufgelistet.They are listed in the following snippet with their default values.

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

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.

Informationen zu den Methoden und optionalen sekundären Argumenten finden Sie in den Beschreibungen der integrierten Typhinweise Ihrer IDE oder unter applicationinsights.ts.Review their descriptions in your IDE's built-in type hinting, or applicationinsights.ts for detailed information on what these control, and optional secondary arguments.

Hinweis

Mit der Standardkonfiguration von setAutoCollectConsole werden Aufrufe von console.log (sowie anderer Konsolenmethoden) ausgeschlossen.By default setAutoCollectConsole is configured to exclude calls to console.log (and other console methods). Es werden nur Aufrufe von unterstützten Protokollierungen von Drittanbietern (wie Winston und Bunyan) gesammelt.Only calls to supported third-party loggers (for example, winston and bunyan) will be collected. Mit setAutoCollectConsole(true, true) können Sie dieses Verhalten ändern, um künftig Aufrufe von console-Methoden einzuschließen.You can change this behavior to include calls to console methods by using setAutoCollectConsole(true, true).

StichprobenSampling

Standardmäßig sendet das SDK alle gesammelten Daten an den Application Insights-Dienst.By default, the SDK will send all collected data to the Application Insights service. Wenn Sie viele Daten sammeln, können Sie die Erstellung von Stichproben aktivieren, um die Menge der gesendete Daten zu verringern.If you collect a lot of data, you might want to enable sampling to reduce the amount of data sent. Legen Sie hierzu das Feld samplingPercentage des config-Objekts eines Clients fest.Set the samplingPercentage field on the config object of a client to accomplish this. Wenn Sie dabei samplingPercentage auf „100“ festlegen (Standardeinstellung), werden alle Daten gesendet. Bei „0“ werden keine Daten gesendet.Setting samplingPercentage to 100(the default) means all data will be sent and 0 means nothing will be sent.

Bei der automatischen Korrelation werden alle Daten, die einer einzelnen Anforderung zugeordnet sind, als Einheit ein- oder ausgeschlossen.If you are using automatic correlation, all data associated with a single request will be included or excluded as a unit.

Fügen Sie etwa folgenden Code hinzu, um die Stichprobenerstellung zu aktivieren:Add code such as the following to enable sampling:

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

Mehrere Rollen für Anwendungen mit mehreren KomponentenMultiple roles for multi-components applications

Angenommen, Ihre Anwendung besteht aus mehreren Komponenten, die alle mit demselben Instrumentierungsschlüssel instrumentiert werden sollen. Doch diese Komponenten werden im Portal noch immer als separate Einheiten angezeigt – ganz so, als ob separate Instrumentierungsschlüssel genutzt werden sollten (etwa als separate Knoten in der Anwendungsübersicht). Konfigurieren Sie in diesem Fall das Feld „RoleName“ manuell, um die Telemetriedaten der einzelnen Komponenten von denen anderer Komponenten, die Daten an Ihre Application Insights-Ressource senden, unterscheiden zu können.If your application consists of multiple components that you wish to instrument all with the same instrumentation key and still see these components as separate units in the portal, as if they were using separate instrumentation keys (for example, as separate nodes on the Application Map), you may need to manually configure the RoleName field to distinguish one component's telemetry from other components sending data to your Application Insights resource.

Legen Sie das Feld „RoleName“ auf folgende Weise fest:Use the following to set the RoleName field:

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

Automatische Instrumentierung von DrittanbieternAutomatic third-party instrumentation

Damit Kontext über mehrere asynchrone Aufrufe hinweg nachverfolgt werden kann, müssen Sie in Drittanbieterbibliotheken wie MongoDB und Redis einige Änderungen vornehmen.In order to track context across asynchronous calls, some changes are required in third party libraries such as MongoDB and Redis. Standardmäßig verwendet Application Insights diagnostic-channel-publishers, um einige dieser Bibliotheken mit einem Monkey-Patch zu versehen.By default, Application Insights will use diagnostic-channel-publishers to monkey-patch some of these libraries. Sie können diese Einstellung ändern, indem Sie die Umgebungsvariable APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL festlegen.This can be disabled by setting the APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL environment variable.

Hinweis

Wenn Sie diese Umgebungsvariable festlegen, werden Ereignisse möglicherweise dem entsprechenden Vorgang nicht mehr korrekt zugeordnet.By setting that environment variable, events may no longer be correctly associated with the right operation.

Sie können einzelne Monkey-Patches deaktivieren, indem Sie die Umgebungsvariable APPLICATION_INSIGHTS_NO_PATCH_MODULES auf eine durch Kommas getrennte Liste mit Paketen festlegen, die deaktiviert werden sollen (z. B. APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis). Auf diese Weise werden die Pakete console und redis nicht mit einem Patch versehen.Individual monkey-patches can be disabled by setting the APPLICATION_INSIGHTS_NO_PATCH_MODULES environment variable to a comma separated list of packages to disable (for example, APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis) to avoid patching the console and redis packages.

Derzeit werden die folgenden neun Pakete instrumentiert: bunyan, console, mongodb, mongodb-core, mysql, redis, winston, pg und pg-pool.Currently there are nine packages that are instrumented: bunyan,console,mongodb,mongodb-core,mysql,redis,winston,pg, and pg-pool. Eine Auflistung der Versionen, die mit einem Patch versehen werden, finden Sie in der Infodatei zu diagnostic-channel-publishers.Visit the diagnostic-channel-publishers' README for information about exactly which version of these packages are patched.

Je nachdem, ob setAutoCollectConsole aktiviert ist oder nicht, werden durch die bunyan-, winston- und console-Patches Application Insights-Ablaufverfolgungsereignisse generiert.The bunyan, winston, and console patches will generate Application Insights trace events based on whether setAutoCollectConsole is enabled. Die restlichen Patches generieren bei Aktivierung von setAutoCollectDependencies Application Insights-Abhängigkeitsereignisse.The rest will generate Application Insights Dependency events based on whether setAutoCollectDependencies is enabled.

LivemetrikenLive Metrics

Verwenden Sie setSendLiveMetrics(true), um Livemetriken von Ihrer App an Azure zu senden.To enable sending Live Metrics from your app to Azure, use setSendLiveMetrics(true). Das Filtern von Livemetriken wird im Portal derzeit nicht unterstützt.Filtering of live metrics in the portal is currently not supported.

Erweiterte MetrikenExtended metrics

Hinweis

Ab Version 1.4.0 wird das Senden von erweiterten nativen Metriken unterstützt.The ability to send extended native metrics was added in version 1.4.0

Wenn Sie das Senden von erweiterten nativen Metriken von Ihrer App an Azure aktivieren möchten, installieren Sie das separate Paket für native Metriken.To enable sending extended native metrics from your app to Azure, install the separate native metrics package. Das SDK wird nach der Installation automatisch geladen und beginnt mit dem Sammeln von nativen Node.js-Metriken.The SDK will automatically load when it is installed and start collecting Node.js native metrics.

npm install applicationinsights-native-metrics

Derzeit sammelt das Paket für native Metriken automatisch die CPU-Zeit für die automatische Speicherbereinigung, für die Takte von Ereignisschleifen sowie für die Heapnutzung:Currently, the native metrics package performs autocollection of garbage collection CPU time, event loop ticks, and heap usage:

  • Automatische Speicherbereinigung: Die für die einzelnen Typen der automatischen Speicherbereinigung aufgewendete CPU-Zeit sowie die Anzahl der Vorkommen der einzelnen Typen.Garbage collection: The amount of CPU time spent on each type of garbage collection, and how many occurrences of each type.
  • Ereignisschleife: Die Anzahl der Takte sowie die insgesamt aufgewendete CPU-Zeit.Event loop: How many ticks occurred and how much CPU time was spent in total.
  • Heapnutzung und Nicht-Heapnutzung: Anteil der Heap-Speicherauslastung Ihrer App.Heap vs non-heap: How much of your app's memory usage is in the heap or non-heap.

Modi der verteilten AblaufverfolgungDistributed Tracing modes

Standardmäßig sendet das SDK Header, die von anderen Anwendungen/Diensten, die mit einem Application Insights SDK instrumentiert sind, gelesen werden.By default, the SDK will send headers understood by other applications/services instrumented with an Application Insights SDK. Optional können Sie das Senden/Empfangen von W3C-Headern für Ablaufverfolgungskontext neben den vorhandenen KI-Headern aktivieren, damit Korrelationen mit vorhandenen Legacydiensten nicht unterbrochen werden.You can optionally enable sending/receiving of W3C Trace Context headers in addition to the existing AI headers, so you will not break correlation with any of your existing legacy services. Durch Aktiveren von W3C-Headern kann Ihre App eine Korrelation mit anderen Diensten herstellen, die zwar nicht mit Application Insights instrumentiert sind, aber diesen W3C-Standard übernehmen.Enabling W3C headers will allow your app to correlate with other services not instrumented with Application Insights, but do adopt this W3C standard.

const appInsights = require("applicationinsights");
appInsights
  .setup("<your ikey>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .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 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
});

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

Das folgende Beispiel zeigt ein Hilfsprogramm, das mithilfe von trackMetric die Dauer der Zeitplanung von Ereignisschleifen misst:An example utility using trackMetric to measure how long event loop scheduling takes:

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

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 manuell nachzuverfolgen:Use the following code to manually track HTTP GET requests:

Hinweis

Standardmäßig werden alle Anforderungen nachverfolgt.All requests are tracked by default. Rufen Sie vor dem Aufruf von „start()“ den Befehl „.setAutoCollectRequests(false)“ auf, um die automatische Sammlung zu deaktivieren.To disable automatic collection, call .setAutoCollectRequests(false) before calling start().

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

Alternativ dazu können Sie Anforderungen auch mithilfe der trackNodeHttpRequest-Methode nachverfolgen:Alternatively you can track requests using trackNodeHttpRequest method:

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

Vorverarbeiten von Daten mit TelemetrieprozessorenPreprocess data with telemetry processors

Mithilfe von Telemetrieprozessoren können Sie die gesammelten Daten vor der Aufbewahrung verarbeiten und filtern.You can process and filter collected data before it is sent for retention using Telemetry Processors. Telemetrieprozessoren werden nacheinander in der Reihenfolge aufgerufen, in der sie hinzugefügt wurden, bevor das Telemetrieelement an die Cloud gesendet wird.Telemetry processors are called one by one in the order they were added before the telemetry item is sent to the cloud.

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

Gibt ein Telemetrieprozessor „FALSE“ zurück, wird das entsprechende Telemetrieelement nicht gesendet.If a telemetry processor returns false, that telemetry item will not be sent.

Alle Telemetrieprozessoren erhalten zur Überprüfung und Änderung die Telemetriedaten und deren Umschlag.All telemetry processors receive the telemetry data and its envelope to inspect and modify. Zudem erhalten sie auch ein Kontextobjekt.They also receive a context object. Der Inhalt dieses Objekts wird durch den contextObjects-Parameter beim Aufruf einer Nachverfolgungsmethode für manuell nachverfolgte Telemetriedaten definiert.The contents of this object is defined by the contextObjects parameter when calling a track method for manually tracked telemetry. Für automatisch gesammelte Telemetriedaten wird dieses Objekt mit den verfügbaren Anforderungsinformationen und dem permanenten Anforderungsinhalt aufgefüllt, die von appInsights.getCorrelationContext() bereitgestellt werden (wenn die automatische Abhängigkeitskorrelation aktiviert ist).For automatically collected telemetry, this object is filled with available request information and the persistent request content as provided by appInsights.getCorrelationContext() (if automatic dependency correlation is enabled).

Der TypeScript-Typ eines Telemetrieprozessors lautet:The TypeScript type for a telemetry processor is:

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

Ein Prozessor zum Entfernen von Daten der Stapelüberwachung aus Ausnahmen könnte beispielsweise folgendermaßen aussehen:For example, a processor that removes stacks trace data from exceptions might be written and added as follows:

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

Verwenden mehrerer InstrumentierungsschlüsselUse multiple instrumentation keys

Sie können mehrere Application Insights-Ressourcen erstellen, denen jeweils unterschiedliche Daten gesendet werden, wenn Sie für die einzelnen Ressourcen den entsprechenden Instrumentierungsschlüssel („iKey“) verwenden.You can create multiple Application Insights resources and send different data to each by using their respective instrumentation keys ("ikey").

Beispiel:For example:

let appInsights = require("applicationinsights");

// configure auto-collection under one ikey
appInsights.setup("_ikey-A_").start();

// track some events manually under another ikey
let otherClient = new appInsights.TelemetryClient("_ikey-B_");
otherClient.trackEvent({name: "my custom event"});

Erweiterte KonfigurationsoptionenAdvanced configuration options

Das Clientobjekt enthält eine config-Eigenschaft mit vielen optionalen Einstellungen für erweiterte Szenarios.The client object contains a config property with many optional settings for advanced scenarios. Diese Eigenschaften können auf folgende Weise festgelegt werden:These can be set as follows:

client.config.PROPERTYNAME = VALUE;

Diese Eigenschaften sind clientspezifisch, d. h. dass Sie appInsights.defaultClient-Clients und new appInsights.TelemetryClient()-Clients getrennt voneinander konfigurieren können.These properties are client specific, so you can configure appInsights.defaultClient separately from clients created with new appInsights.TelemetryClient().

EigenschaftProperty BESCHREIBUNGDescription
instrumentationKeyinstrumentationKey Ein Bezeichner für Ihre Application Insights-Ressource.An identifier for your Application Insights resource.
endpointUrlendpointUrl Der Erfassungsendpunkt, an den die Telemetrienutzlasten gesendet werden sollen.The ingestion endpoint to send telemetry payloads to.
quickPulseHostquickPulseHost Der Host für Live Metrics Stream, an den die Telemetriedaten der Livemetriken gesendet werden sollen.The Live Metrics Stream host to send live metrics telemetry to.
proxyHttpUrlproxyHttpUrl Ein Proxyserver für den HTTP-Datenverkehr des SDK (optional; der Standardwert wird aus der Umgebungsvariable http_proxy abgerufen).A proxy server for SDK HTTP traffic (Optional, Default pulled from http_proxy environment variable).
proxyHttpsUrlproxyHttpsUrl Ein Proxyserver für den HTTPS-Datenverkehr des SDK (optional; der Standardwert wird aus der Umgebungsvariable https_proxy abgerufen).A proxy server for SDK HTTPS traffic (Optional, Default pulled from https_proxy environment variable).
httpAgenthttpAgent Ein HTTP-Agent für den HTTP-Datenverkehr des SDK (optional; ist standardmäßig nicht definiert).An http.Agent to use for SDK HTTP traffic (Optional, Default undefined).
httpsAgenthttpsAgent Ein HTTP-Agent für den HTTPS-Datenverkehr des SDK (optional; ist standardmäßig nicht definiert).An https.Agent to use for SDK HTTPS traffic (Optional, Default undefined).
maxBatchSizemaxBatchSize Die maximale Anzahl von Telemetrieelementen, die in eine Nutzlast zum Erfassungsendpunkt eingeschlossen werden sollen (Standardwert: 250).The maximum number of telemetry items to include in a payload to the ingestion endpoint (Default 250).
maxBatchIntervalMsmaxBatchIntervalMs Die maximale Wartezeit, bis eine Nutzlast „maxBatchSize“ erreicht (Standardwert: 15000).The maximum amount of time to wait to for a payload to reach maxBatchSize (Default 15000).
disableAppInsightsdisableAppInsights Ein Flag, das angibt, ob die Übertragung von Telemetriedaten deaktiviert ist (Standardwert: false).A flag indicating if telemetry transmission is disabled (Default false).
samplingPercentagesamplingPercentage Der Prozentsatz der nachverfolgten Telemetrieelemente, der übertragen werden soll (Standardwert: 100).The percentage of telemetry items tracked that should be transmitted (Default 100).
correlationIdRetryIntervalMscorrelationIdRetryIntervalMs Die Wartezeit bis zum erneuten Versuch, die ID für komponentenübergreifende Korrelationen abzurufen (Standardwert: 30000).The time to wait before retrying to retrieve the ID for cross-component correlation (Default 30000).
correlationHeaderExcludedDomainscorrelationHeaderExcludedDomains Eine Liste der Domänen, die von Header Injection für komponentenübergreifende Korrelationen ausgeschlossen werden sollen (Standardwert siehe Config.ts).A list of domains to exclude from cross-component correlation header injection (Default See Config.ts).

Nächste SchritteNext steps