Freigeben über

Überwachen Ihrer Node.js-Dienste und -Apps mit Application Insights

  • Artikel

Application Insights überwachte Ihre Komponenten nach der Bereitstellung, um Leistungsprobleme und andere Probleme zu erkennen. 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.

Um Ihre Überwachungsdaten zu erhalten, zu speichern und zu durchsuchen, beziehen Sie das SDK in den Code ein. Richten Sie anschließend eine entsprechende Application Insights-Ressource in Azure ein. Das SDK sendet Daten zur weiteren Analyse und Untersuchung an diese Ressource.

Die Node.js-Clientbibliothek kann ein- und ausgehende HTTP-Anforderungen, Ausnahmen und einige Systemmetriken automatisch überwachen. Ab Version 0.20 kann die Clientbibliothek auch einige allgemeine Drittanbieterpakete überwachen, z. B. MongoDB, MySQL und Redis.

Alle Ereignisse, die sich auf eine eingehende HTTP-Anforderung beziehen, werden zur Beschleunigung der Problembehandlung korreliert.

Sie können die TelemetryClient-API verwenden, um weitere Aspekte Ihrer App und Ihres Systems manuell zu instrumentieren und zu überwachen. Die TelemetryClient-API wird weiter unten in diesem Artikel näher beschrieben.

Hinweis

Die folgende Dokumentation basiert auf der klassischen Application Insights-API. Der langfristige Plan für Application Insights besteht darin, Daten mithilfe von OpenTelemetry zu sammeln. Weitere Informationen finden Sie unter Aktivieren von Azure Monitor OpenTelemetry für .NET-, Node.js-, Python- und Java-Anwendungen und unserer OpenTelemetry Roadmap. Migrationsleitfaden sind für .NET, Node.js und Python verfügbar.

Erste Schritte

Führen Sie die folgenden Aufgaben durch, um die Überwachung für eine App oder einen Dienst einzurichten.

Voraussetzungen

Stellen Sie zuerst sicher, dass Sie über ein Azure-Abonnement verfügen, oder beschaffen Sie sich kostenlos ein neues Abonnement. Falls Ihre Organisation bereits über ein Azure-Abonnement verfügt, kann Ihr Administrator Sie anhand dieser Anleitung hinzufügen.

Einrichten einer Application Insights-Ressource

  1. Melden Sie sich beim Azure-Portal an.
  2. Erstellen Sie eine Application Insights-Ressource.

Hinweis

Am 31. März 2025 wird der Support für die auf Instrumentierungsschlüsseln basierende Erfassung eingestellt. Die Erfassung von Instrumentierungsschlüsseln funktioniert zwar weiterhin, wir stellen jedoch keine Updates und keinen Support mehr für das Feature bereit. Wechseln Sie zu Verbindungszeichenfolgen, damit Sie neue Funktionen nutzen können.

Einrichten der Node.js-Clientbibliothek

Beziehen Sie das SDK in Ihre App ein, damit sie Daten sammeln kann.

  1. Kopieren Sie die Verbindungszeichenfolge Ihrer Ressource aus der neuen Ressource. Die Verbindungszeichenfolge wird von Application Insights verwendet, um Ihrer Azure-Ressource Daten zuzuordnen. Damit die Verbindungszeichenfolge vom SDK verwendet werden kann, müssen Sie die Verbindungszeichenfolge in einer Umgebungsvariablen oder im Code angeben.

    Screenshot, der die Application Insights-Übersicht und die Verbindungszeichenfolge zeigt.

  2. Fügen Sie die Node.js-Clientbibliothek per package.json den Abhängigkeiten Ihrer App hinzu. Führen Sie im Stammordner Ihrer App Folgendes aus:

    npm install applicationinsights --save

    Hinweis

    Installieren Sie bei Verwendung von TypeScript keine separaten Pakete mit Typisierungen. Dieses npm-Paket enthält integrierte Typisierungen.

  3. Laden Sie die Bibliothek explizit im 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.

    let appInsights = require('applicationinsights');

  4. Sie können eine Verbindungszeichenfolge auch über die Umgebungsvariable APPLICATIONINSIGHTS_CONNECTION_STRING bereitstellen, anstatt sie manuell an setup() oder new appInsights.TelemetryClient() zu übergeben. Mit dieser Vorgehensweise können Sie Verbindungszeichenfolgen aus festgelegtem Quellcode heraushalten und unterschiedliche Verbindungszeichenfolgen für unterschiedliche Umgebungen angeben. Rufen Sie appInsights.setup('[your connection string]'); auf, um die Konfiguration manuell durchzuführen.

    Weitere Konfigurationsoptionen finden Sie in den folgenden Abschnitten.

    Sie können das SDK auch ohne das Senden von Telemetriedaten testen, indem Sie appInsights.defaultClient.config.disableAppInsights = true festlegen.

  5. Rufen Sie appInsights.start(); auf, um mit dem automatischen Sammeln und Senden von Daten zu beginnen.

Hinweis

Im Rahmen der Verwendung der Application Insights-Instrumentierung sammeln und senden wir Diagnosedaten an Microsoft. Diese Daten helfen uns, Application Insights auszuführen und zu verbessern. Sie haben die Möglichkeit, die Sammlung nicht wesentlicher Daten zu deaktivieren. Weitere Informationen.

Überwachen Ihrer App

Das SDK sammelt automatisch Telemetriedaten zur Node.js-Laufzeit und zu einigen gängigen Drittanbietermodulen. Verwenden Sie Ihre Anwendung, um einige dieser Daten zu generieren.

Navigieren Sie im Azure-Portal dann zu der zuvor erstellten Application Insights-Ressource. Suchen Sie in der Übersichtszeitachse nach Ihren ersten Datenpunkten. Wählen Sie in den Diagrammen verschiedene Komponenten aus, um detailliertere Daten anzuzeigen.

Sie können die Topologie, die für Ihre App ermittelt wird, über die Anwendungsübersicht anzeigen.

Keine Daten

Da das SDK Daten zur Übermittlung in Batches zusammenfasst, kann es ggf. eine Weile dauern, bis die Elemente im Portal angezeigt werden. Falls in Ihrer Ressource keine Daten angezeigt werden, können Sie folgende Lösungsmöglichkeiten ausprobieren:

  • Fahren Sie mit der Verwendung der Anwendung fort. Führen Sie mehr Aktionen durch, um mehr Telemetriedaten zu generieren.
  • Wählen Sie in der Ressourcenansicht des Portals Aktualisieren aus. Diagramme aktualisieren sich regelmäßig selbst, aber bei der manuellen Aktualisierung wird der Vorgang sofort erzwungen.
  • Stellen Sie sicher, dass die erforderlichen ausgehenden Ports geöffnet sind.
  • Verwenden Sie Suchen, um nach bestimmten Ereignissen zu suchen.
  • Lesen Sie die häufig gestellten Fragen.

Grundlegende Verwendung

Für die sofort einsetzbare Sammlung von HTTP-Anforderungen, Ereignissen von beliebten Drittanbieterbibliotheken, nicht behandelten Ausnahmen und Systemmetriken:


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

Hinweis

Ist die Verbindungszeichenfolge in der Umgebungsvariable APPLICATIONINSIGHTS_CONNECTION_STRING festgelegt, kann .setup() ohne Argumente aufgerufen werden. Dies erleichtert die Verwendung verschiedener Verbindungszeichenfolgen für unterschiedliche Umgebungen.

Laden Sie noch vor anderen Paketen die Application Insights-Bibliothek (require("applicationinsights")) so früh wie möglich in Ihre Skripts. Dieser Schritt ist erforderlich, damit die Application Insights-Bibliothek spätere Pakete für die Nachverfolgung vorbereiten kann. Treten Konflikte mit anderen Bibliotheken auf, die eine ähnliche Vorbereitung durchführen, laden Sie die Application Insights-Bibliothek danach.

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 weitere Arbeitsschritte erforderlich. Standardmäßig ist diese zusätzliche Nachverfolgung aktiviert. Deaktivieren Sie sie, indem Sie setAutoDependencyCorrelation(false) aufrufen, wie im Abschnitt SDK-Konfiguration beschrieben.

Migrieren von Versionen vor Version 0.22

Mit Version 0.22 wurden wichtige Änderungen eingeführt. Mit diesen Änderungen wurde die Konsistenz mit anderen Application Insights SDKs erhöht, und künftige Erweiterungen wurden ermöglicht.

Im Allgemeinen können Sie die Migration mit folgenden Aktionen durchführen:

  • Ersetzen Sie Verweise auf appInsights.client durch appInsights.defaultClient.
  • Ersetzen Sie Verweise auf appInsights.getClient() durch new appInsights.TelemetryClient().
  • Ersetzen Sie alle Argumente für „client.track*“-Methoden durch ein einzelnes Objekt, das als Argumente benannte Eigenschaften enthält. Das erwartete Objekt der einzelnen Telemetrietypen finden Sie in den integrierten Typhinweisen Ihrer IDE oder unter TelemetryTypes.

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). Informationen zu Änderungen an der Standardkonfiguration finden Sie im nächsten Abschnitt.

SDK-Konfiguration

Das appInsights-Objekt stellt eine Vielzahl von Konfigurationsmethoden bereit. Diese werden im folgenden Codeausschnitt mit den jeweiligen Standardwerten aufgelistet.

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

Legen Sie .setAutoDependencyCorrelation(true) fest, um die Ereignisse für einen Dienst vollständig zu korrelieren. Wenn diese Option festgelegt ist, kann das SDK den Kontext übergreifend für asynchrone Rückrufe in Node.js nachverfolgen.

Ausführliche Informationen zu den Methoden und optionalen sekundären Argumenten finden Sie in den Beschreibungen der integrierten Typhinweise Ihrer IDE oder unter applicationinsights.ts.

Hinweis

Mit der Standardkonfiguration von setAutoCollectConsole werden Aufrufe von console.log (sowie anderer Konsolenmethoden) ausgeschlossen. Es werden nur Aufrufe von unterstützten Protokollierungen von Drittanbietern (wie Winston und Bunyan) gesammelt. Mit setAutoCollectConsole(true, true) können Sie dieses Verhalten ändern, um künftig Aufrufe von console-Methoden einzuschließen.

Stichproben

Standardmäßig sendet das SDK alle gesammelten Daten an den Application Insights-Dienst. Wenn Sie die Stichprobenentnahme aktivieren möchten, um die Datenmenge zu reduzieren, legen Sie das samplingPercentage-Feld für das config-Objekt eines Clients fest. Wenn Sie dabei samplingPercentage auf „100“ festlegen (Standardeinstellung), werden alle Daten gesendet. Bei „0“ werden keine Daten gesendet.

Bei der automatischen Korrelation werden alle Daten, die einer einzelnen Anforderung zugeordnet sind, als Einheit ein- oder ausgeschlossen.

Fügen Sie etwa folgenden Code hinzu, um die Stichprobenerstellung zu aktivieren:

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

Mehrere Rollen für Anwendungen mit mehreren Komponenten

In einigen Szenarien kann Ihre Anwendung aus mehreren Komponenten bestehen, die Sie alle mit derselben Verbindungszeichenfolge instrumentieren möchten. Sie können diese Komponenten weiterhin als separate Einheiten im Portal anzeigen, als ob sie separate Verbindungszeichenfolgen verwenden würden. Ein Beispiel sind separate Knoten in der Anwendungsübersicht. Sie müssen das Feld RoleName manuell konfigurieren, um die Telemetrie einer Komponente von anderen Komponenten zu unterscheiden, die Daten an Ihre Application Insights-Ressource senden.

Verwenden Sie den folgenden Code, um das Feld RoleName festzulegen:

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

Browser SDK-Ladeprogramm

Hinweis

Als öffentliche Vorschauversion verfügbar. Ergänzende Nutzungsbedingungen für Microsoft Azure-Vorschauversionen

Die automatische Web-Instrumentierung kann für Node Server über die Einschleusung von JavaScript (Web) SDK Loader-Skripten per Konfiguration aktiviert werden.

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

oder durch Festlegen der Umgebungsvariable APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = true aktiviert werden.

Die Webinstrumentierung wird für Knotenserver-Antworten aktiviert, wenn alle folgenden Anforderungen erfüllt sind:

  • Die Antwort weist den Statuscode 200 auf.
  • Die Antwortmethode lautet GET.
  • Die Serverantwort weist „html“ als Content-Type auf.
  • Die Serverantwort enthält sowohl das Tag <head> als auch das Tag </head>.
  • Wenn die Antwort komprimiert ist, darf sie nur einen Content-Encoding-Typ aufweisen, und der Codierungstyp muss gzip, br oder deflate sein.
  • Die Antwort enthält keine aktuellen oder Sicherungs-CDN-Endpunkte für die Webinstrumentierung. (Aktuelle und Sicherungs-CDN-Endpunkte für die Webinstrumentierung finden Sie hier.)

Der CDN-Endpunkt für die Webinstrumentierung kann durch Festlegen der Umgebungsvariable APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints" geändert werden. Die Verbindungszeichenfolge für die Webinstrumentierung kann durch Festlegen der Umgebungsvariable APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string" geändert werden.

Hinweis

Die Webinstrumentierung kann die Antwortzeit des Servers verlangsamen, insbesondere dann, wenn die Antwort sehr groß oder komprimiert ist. Falls mittlere Schichten angewendet werden, kann dies dazu führen, dass die Webinstrumentierung nicht funktioniert und die ursprüngliche Antwort zurückgegeben wird.

Automatische Instrumentierung von Drittanbietern

Damit Kontext über mehrere asynchrone Aufrufe hinweg nachverfolgt werden kann, müssen Sie in Drittanbieterbibliotheken wie MongoDB und Redis einige Änderungen vornehmen. Standardmäßig verwendet Application Insights diagnostic-channel-publishers, um einige dieser Bibliotheken mit einem Monkey-Patch zu versehen. Sie können diese Funktion ändern, indem Sie die Umgebungsvariable APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL festlegen.

Hinweis

Wenn Sie diese Umgebungsvariable festlegen, werden Ereignisse möglicherweise dem entsprechenden Vorgang nicht korrekt zugeordnet.

Sie können einzelne Monkey-Patches deaktivieren, indem Sie die APPLICATION_INSIGHTS_NO_PATCH_MODULES-Umgebungsvariable auf eine durch Kommas getrennte Liste mit Paketen festlegen, die deaktiviert werden sollen. Verwenden Sie beispielsweise APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis, um das Patchen der Pakete console und redis zu vermeiden.

Derzeit werden neun Pakete instrumentiert: bunyan,console,mongodb,mongodb-core,mysql,redis,winston,pg und pg-pool. Informationen zu den genauen Versionen der Pakete, die mit einem Patch versehen werden, finden Sie in der Infodatei zu diagnostic-channel-publishers.

Je nachdem, ob setAutoCollectConsole aktiviert ist oder nicht, werden durch die bunyan-, winston- und console-Patches Application Insights-Ablaufverfolgungsereignisse generiert. Die restlichen Patches generieren, wenn setAutoCollectDependencies aktiviert ist, Application Insights-Abhängigkeitsereignisse.

Livemetriken

Verwenden Sie setSendLiveMetrics(true), um Livemetriken von Ihrer App an Azure zu senden. Das Filtern von Livemetriken wird im Portal derzeit nicht unterstützt.

Erweiterte Metriken

Hinweis

Ab Version 1.4.0 wird das Senden von erweiterten nativen Metriken unterstützt.

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. Das SDK wird nach der Installation automatisch geladen und beginnt mit dem Sammeln von nativen Node.js-Metriken.

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:

  • Automatische Speicherbereinigung: Die für die einzelnen Typen der automatischen Speicherbereinigung aufgewendete CPU-Zeit sowie die Anzahl der Vorkommen der einzelnen Typen.
  • Ereignisschleife: Die Anzahl der Takte sowie die insgesamt aufgewendete CPU-Zeit.
  • Heapnutzung und Nicht-Heapnutzung: Anteil der Heap-Speicherauslastung Ihrer App.

Modi der verteilten Ablaufverfolgung

Standardmäßig sendet das SDK Header, die von anderen Anwendungen oder Diensten, die mit einem Application Insights SDK instrumentiert sind, gelesen werden. Sie können das Senden und Empfangen der Header für W3C-Ablaufverfolgungskontext zusätzlich zu den vorhandenen KI-Headern aktivieren. Auf diese Weise unterbrechen Sie keine Korrelation mit Ihren vorhandenen Legacydiensten. Durch Aktiveren von W3C-Headern kann Ihre Anwendung eine Korrelation mit anderen Diensten herstellen, die zwar nicht mit Application Insights instrumentiert sind, aber diesen W3C-Standard übernehmen.

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

TelemetryClient-API

Eine vollständige Beschreibung der TelemetryClient-API finden Sie unter Application Insights-API für benutzerdefinierte Ereignisse und Metriken.

Sie können alle Anforderungen, Ereignisse, Metriken oder Ausnahmen mit der Application Insights-Clientbibliothek für Node.js nachverfolgen. Im folgenden Codebeispiel werden einige APIs veranschaulicht, die Sie verwenden können:

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

Nachverfolgen Ihrer Abhängigkeiten

Nutzen Sie den folgenden Code, um Ihre Abhängigkeiten nachzuverfolgen:

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:

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 Ereignissen

Verwenden Sie den folgenden Code, um allen Ereignissen eine benutzerdefinierte Eigenschaft hinzuzufügen:

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

Nachverfolgen von HTTP GET-Anforderungen

Verwenden Sie den folgenden Code, um HTTP GET-Anforderungen manuell nachzuverfolgen:

Hinweis

  • Standardmäßig werden alle Anforderungen nachverfolgt. Zum Deaktivieren der automatischen Sammlung rufen Sie .setAutoCollectRequests(false) vor start() auf.
  • Native Fetch-API-Anforderungen werden nicht automatisch von klassischen Application Insights-Instanzen nachverfolgt. Eine manuelle Abhängigkeitsnachverfolgung ist erforderlich.
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:

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

Nachverfolgen der Serverstartzeit

Verwenden Sie den folgenden Code, um die Serverstartzeit nachzuverfolgen:

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

Leerung

Standardmäßig wird die Telemetrie 15 Sekunden lang gepuffert, bevor sie an den Erfassungsserver gesendet wird. Wenn Ihre Anwendung eine kurze Lebensdauer hat (z. B. bei Befehlszeilenschnittstellentools), ist es möglicherweise erforderlich, die gepufferten Telemetriedaten manuell zu leeren, wenn die Anwendung beendet wird, und zwar mithilfe von appInsights.defaultClient.flush().

Wenn das SDK erkennt, dass die Anwendung abstürzt, ruft sie für Sie das Leeren mittels appInsights.defaultClient.flush({ isAppCrashing: true }) auf. Wenn die Option isAppCrashing von Flush angegeben wird, wird angenommen, dass sich die Anwendung in einem nicht ordnungsgemäßen Zustand befindet und die Telemetriedaten nicht senden kann. Stattdessen speichert das SDK alle gepufferten Telemetriedaten im persistenten Speicher und beendet die Anwendung. Wenn Ihre Anwendung erneut gestartet wird, versucht sie, alle Telemetriedaten zu senden, die im persistenten Speicher gespeichert wurden.

Vorverarbeiten von Daten mit Telemetrieprozessoren

Mithilfe von Telemetrieprozessoren können Sie die gesammelten Daten vor der Aufbewahrung verarbeiten und filtern. Telemetrieprozessoren werden nacheinander in der Reihenfolge aufgerufen, in der sie hinzugefügt wurden, bevor das Telemetrieelement an die Cloud gesendet wird.

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.

Alle Telemetrieprozessoren erhalten zur Überprüfung und Änderung die Telemetriedaten und deren Umschlag. Zudem erhalten sie auch ein Kontextobjekt. Der Inhalt dieses Objekts wird durch den contextObjects-Parameter beim Aufruf einer Nachverfolgungsmethode für manuell nachverfolgte Telemetriedaten definiert. 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).

Der TypeScript-Typ eines Telemetrieprozessors lautet:

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:

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 Verbindungszeichenfolgen

Sie können mehrere Application Insights-Ressourcen erstellen, denen jeweils unterschiedliche Daten gesendet werden, wenn Sie für die einzelnen Ressourcen den entsprechenden Verbindungszeichenfolgen verwenden.

Beispiel:

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

Erweiterte Konfigurationsoptionen

Das Clientobjekt enthält eine config-Eigenschaft mit vielen optionalen Einstellungen für erweiterte Szenarios. Um sie festzulegen, verwenden Sie Folgendes:

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.

Eigenschaft Beschreibung
connectionString Ein Bezeichner für Ihre Application Insights-Ressource.
endpointUrl Der Erfassungsendpunkt, an den die Telemetrienutzlasten gesendet werden sollen.
quickPulseHost Der Host für Live Metrics Stream, an den die Telemetriedaten der Livemetriken gesendet werden sollen.
proxyHttpUrl Ein Proxyserver für SDK-HTTP-Datenverkehr. (Optional. Standard wird aus der http_proxy-Umgebungsvariable abgerufen.)
proxyHttpsUrl Ein Proxyserver für SDK-HTTPS-Datenverkehr. (Optional. Standard wird aus der https_proxy-Umgebungsvariable abgerufen.)
httpAgent Ein HTTP-Agent für den HTTP-Datenverkehr des SDK. (Optional. Standard ist nicht definiert.)
httpsAgent Ein HTTPS-Agent für den HTTPS-Datenverkehr des SDK. (Optional. Standard ist nicht definiert.)
maxBatchSize Die maximale Anzahl von Telemetrieelementen, die in eine Nutzlast zum Erfassungsendpunkt eingeschlossen werden sollen. (Der Standardwert ist 250.)
maxBatchIntervalMs Die maximale Wartezeit, bis eine Nutzlast „maxBatchSize“ erreicht. (Der Standardwert ist 15000.)
disableAppInsights Ein Flag, das angibt, ob die Übertragung von Telemetriedaten deaktiviert ist. (Der Standardwert ist false.)
samplingPercentage Der Prozentsatz der nachverfolgten Telemetrieelemente, der übertragen werden soll. (Der Standardwert ist 100.)
correlationIdRetryIntervalMs Die Wartezeit bis zum erneuten Versuch, die ID für komponentenübergreifende Korrelationen abzurufen. (Der Standardwert ist 30000.)
correlationHeaderExcludedDomains Eine Liste der Domänen, die von Header Injection für komponentenübergreifende Korrelationen ausgeschlossen werden sollen. (Standard. Siehe Config.ts.)

Häufig gestellte Fragen

Wie kann ich die Telemetriekorrelation deaktivieren?

Verwenden Sie die correlationHeaderExcludedDomains-Eigenschaft in der Konfiguration, um die Telemetriekorrelation zu deaktivieren. Weitere Informationen finden Sie unter ApplicationInsights-node.js.

Problembehandlung

Informationen zur Problembehandlung, einschließlich Szenarien, in denen keine Daten verfügbar sind, und das Anpassen von Protokollen, finden Sie unter Problembehandlung bei der Application Insights-Überwachung von Node.js-Apps und -Diensten.

Nächste Schritte