Beheben von Fehlern beim Laden des SDK für JavaScript-Web-Apps

Die Ausnahme beim Fehlschlagen des Ladens des SDK wird vom JavaScript-Ausschnitt (v3 oder höher) erstellt und gemeldet, wenn festgestellt wird, dass das SDK-Skript nicht heruntergeladen oder initialisiert werden konnte. Vereinfacht ausgedrückt, konnte der Client (Browser) Ihres Endbenutzers das Application Insights SDK nicht herunterladen oder nicht über die identifizierte Hostingseite initialisieren, weshalb keine Telemetrie oder Ereignisse gemeldet werden.

Azure portal browser failure overview

Hinweis

Diese Ausnahme wird von allen gängigen Browsern unterstützt, die die fetch()-API oder XMLHttpRequest unterstützen. Dies schließt Internet Explorer 8 und niedriger aus, sodass Sie diese Browser diese Art von Ausnahmen nicht melden können (es sei denn, Ihre Umgebung enthält ein „fetch“-Polyfill).

browser exception detail

Die Stapelangaben enthalten die grundlegenden Informationen, einschließlich der vom Endbenutzer verwendeten URLs.

Name Beschreibung
<CDN-Endpunkt> Die URL, die zum (fehlgeschlagenen) Herunterladen des SDK verwendet wurde.
<Hilfelink> Eine URL, die auf Dokumentation zur Problembehandlung verweist (diese Seite).
<Host-URL> Die vollständige URL der Seite, die der Endbenutzer verwendet hat.
<Endpunkt-URL> Die URL, die zum Melden der Ausnahme verwendet wurde. Dieser Wert kann hilfreich sein, um festzustellen, ob auf die Hostingseite über das öffentliche Internet oder eine private Cloud zugegriffen wurde.

Es folgen die häufigsten Gründe für diese Ausnahme:

  • Zeitweiliger Verlust der Netzwerkverbindung
  • Ausfall des Application Insights CDN
  • Keine Initialisierung des SDK nach Laden des Skripts
  • Blockierung des JavaScript CDN von Application Insights

Zeitweiliger Verlust der Netzwerkverbindung ist der häufigste Grund für diese Ausnahme, vor allem in mobilen Roamingszenarien, in denen die Benutzer die Netzwerkverbindung zeitweilig verlieren.

In den folgenden Abschnitten wird beschrieben, wie Sie die einzelnen potenziellen Grundursachen dieses Fehlers beseitigen können.

Hinweis

Mehrere der Problembehandlungsschritte setzen voraus, dass Ihre Anwendung direkte Kontrolle über das Tag <script /> im Ausschnitt und dessen Konfiguration hat, die als Teil der HTML-Hostseite zurückgegeben werden. Wenn dies nicht der Fall ist, gelten die genannten Schritte für Ihr Szenario nicht.

Zeitweiliger Verlust der Netzwerkverbindung

Wenn es beim Benutzer zu zeitweiligen Ausfällen der Netzwerkverbindung kommt, gibt es nur wenige Lösungsmöglichkeiten. Diese Probleme beheben sich in der Regel innerhalb kurzer Zeit von selbst. Wenn der Benutzer beispielsweise Ihre Website neu lädt (die Seite aktualisiert), werden die Dateien (schließlich) heruntergeladen und lokal zwischengespeichert, bis eine aktualisierte Version veröffentlicht wird.

Hinweis

Wenn diese Ausnahme hartnäckig ist und bei vielen Ihrer Benutzer auftritt, was anhand einer raschen und kontinuierlichen Meldung dieser Ausnahme erkannt wird, und gleichzeitig ein Rückgang der normalen Clienttelemetrie zu verzeichnen ist, dürfte es unwahrscheinlich sein, dass zeitweilige Probleme mit der Netzwerkverbindung die wahre Ursache des Problems sind. Sie sollten daher die Diagnose mit den anderen bekannten möglichen Problemen fortsetzen.

In dieser Situation ist es unwahrscheinlich, dass das Hosten des SDK in Ihrem eigenen CDN das Auftreten dieser Ausnahme bewirkt oder verringert, da Ihr eigenes CDN vom selben Problem betroffen ist.

Dasselbe gilt auch für die Verwendung des SDK mit der auf NPM-Paketen basierenden Lösung. Aus Endbenutzersicht kann in diesem Fall jedoch Ihre gesamte Anwendung (statt nur das Telemetrie SDK, das sie nicht sehen) nicht geladen/initialisiert werden, sodass die Endbenutzer höchstwahrscheinlich Ihre Website aktualisieren werden, bis sie vollständig geladen ist.

Sie können auch versuchen, das Application Insights SDK mithilfe von NPM-Paketen einzubetten.

Um zeitweilige Ausfälle der Netzwerkverbindung zu minimieren, haben wir Cache-Control-Header für sämtliche CDN-Dateien implementiert. Sobald der Browser des Endbenutzers die aktuelle Version des SDK heruntergeladen hat, muss er es nicht erneut herunterladen, denn der Browser verwendet die zuvor abgerufene Kopie wieder (weitere Informationen finden Sie unter Funktionsweise der Zwischenspeicherung). Wenn die Zwischenspeicherprüfung fehlschlägt oder es eine neue Version gibt, muss der Browser Ihres Endbenutzers die aktualisierte Version herunterladen. So kann es sein, dass Sie einen Hintergrundpegel von Stördatenverkehr im Szenario der Ausfallprüfung oder eine vorübergehende Spitze erleben, wenn eine neue Version vorliegt und allgemein verfügbar gemacht (im CDN bereitgestellt) wird.

Ausfall des Application Insights CDN

Sie können bestätigen, ob ein Application Insights CDN-Ausfall vorliegt, indem Sie versuchen, direkt im Browser an einem anderen Standort als Ihre Endbenutzer, z. B. auf Ihrem eigenen Entwicklungscomputer, auf den CDN-Endpunkt (z. B. https://js.monitor.azure.com/scripts/b/ai.2.min.js) zuzugreifen (vorausgesetzt, Ihre Organisation hat diese Domäne nicht gesperrt).

Wenn Sie bestätigen, dass ein Ausfall vorliegt, können Sie ein neues Supportticket erstellen.

Keine Initialisierung des SDK nach Laden des Skripts

Wenn das SDK nicht initialisiert werden kann, wurde <script /> zwar erfolgreich aus dem CDN heruntergeladen, schlägt aber während der Initialisierung fehl. Ursache dafür können fehlende oder ungültige Abhängigkeiten oder eine bestimmte Form einer JavaScript-Ausnahme sein.

Zunächst ist zu prüfen, ob das SDK erfolgreich heruntergeladen wurde. Wenn das Skript NICHT heruntergeladen wurde, ist dieses Szenario nicht die Ursache für die Ausnahme aufgrund des fehlgeschlagenen Ladens des SDK.

Schnellprüfung: Überprüfen Sie mit einem Browser, der Entwicklertools (F12) unterstützt, auf der Registerkarte „Netzwerk“, dass das in der Konfiguration des Ausschnitts src definierte Skript mit dem Antwortcode 200 (erfolgreich) oder 304 (nicht geändert) heruntergeladen wurde. Sie könnten auch ein Tool wie Fiddler einsetzen, um den Netzwerkdatenverkehr zu überprüfen.

In den folgenden Abschnitten finden Sie verschiedene Möglichkeiten zur Berichterstellung. Es wird empfohlen, entweder ein Supportticket zu eröffnen oder auf GitHub ein Problem zu melden.

Grundlegende Berichterstellungsregeln:

  • Wenn das Problem nur eine kleine Anzahl von Benutzern und eine bestimmte oder Teilmenge von Browserversionen betrifft (prüfen Sie die Details der gemeldeten Ausnahme), handelt es sich wahrscheinlich um ein Problem, das nur den Endbenutzer oder nur die Umgebung betrifft, sodass Ihre Anwendung wahrscheinlich zusätzliche Implementierungen von polyfill bereitstellen muss. Melden Sie hierfür ein Problem auf GitHub.
  • Wenn dieses Problem Ihre gesamte Anwendung betrifft und alle Ihre Benutzer davon betroffen sind, handelt es sich wahrscheinlich um ein versionsbezogenes Problem. Daher sollten Sie ein neues Supportticket eröffnen.

JavaScript-Ausnahmen

Lassen Sie zunächst mit einem Browser, der Entwicklertools (F12) unterstützt, die Seite auf JavaScript-Ausnahmen prüfen, indem Sie die Seite laden und überprüfen, ob Ausnahmen aufgetreten sind.

Wenn im SDK-Skript Ausnahmen gemeldet werden (z. B. ai.2.min.js), kann dies ein Hinweis darauf sein, dass die an das SDK übergebene Konfiguration eine unerwartete oder fehlende erforderliche Konfiguration aufweist oder eine fehlerhafte Version im CDN bereitgestellt wurde.

Um auf fehlerhafte Konfiguration zu prüfen, ändern Sie die in den Ausschnitt übergebene Konfiguration (falls noch nicht geschehen) so, dass sie nur Ihren Instrumentierungsschlüssel als Zeichenfolgenwert enthält.

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.

src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
cfg: {
    instrumentationKey: "INSTRUMENTATION_KEY"
}});

Wenn bei dieser Minimalkonfiguration weiterhin eine JavaScript-Ausnahme im SDK-Skript auftritt, eröffnen Sie ein neues Supportticket. Dies erfordert ein Zurücksetzen des fehlerhaften Builds, da es sich wahrscheinlich um ein Problem mit einer neu bereitgestellten Version handelt.

Wenn die Ausnahme verschwindet, ist das Problem wahrscheinlich auf eine Diskrepanz zwischen Typen oder einen unerwarteten Wert zurückzuführen. Beginnen Sie, Ihre Konfigurationsoptionen eine nach der anderen wieder hinzuzufügen, und testen Sie solange, bis die Ausnahme erneut auftritt. Prüfen Sie dann die Dokumentation auf das Element, welches das Problem verursacht. Wenn die Dokumentation unklar ist oder Sie Unterstützung benötigen, melden Sie ein Problem auf GitHub.

Wenn Ihre Konfiguration bereits bereitgestellt wurde und funktioniert hat, aber gerade erst begonnen hat, diese Ausnahme zu melden, könnte es sich um Probleme mit einer neu bereitgestellten Version handeln. Prüfen Sie, ob nur ein kleiner Teil Ihrer Benutzer/Browser davon betroffen ist, und melden Sie entweder ein Problem auf GitHub oder eröffnen Sie ein neues Supportticket.

Aktivieren des Debuggens in der Konsole

Wenn keine Ausnahmen ausgelöst werden, ist der nächste Schritt, das Aktivieren des Debuggens in der Konsole durch Hinzufügen der Einstellung loggingLevelConsole zur Konfiguration. Dadurch werden alle Initialisierungsfehler und Warnungen an die Browserkonsole übermittelt (normalerweise über die Entwicklertools [F12] verfügbar). Alle gemeldeten Fehler sollten selbsterklärend sein. Wenn Sie weitere Hilfe benötigen, melden Sie ein Problem auf GitHub.

cfg: {
    instrumentationKey: "INSTRUMENTATION_KEY",
    loggingLevelConsole: 2
}});

Hinweis

Während der Initialisierung führt das SDK einige grundlegende Prüfungen auf bekannte Hauptabhängigkeiten durch. Wenn diese von der aktuellen Runtime nicht bereitgestellt werden, werden die Ausfälle als Warnmeldungen in der Konsole gemeldet, aber nur, wenn loggingLevelConsole größer als 0 ist.

Wenn die Initialisierung weiter fehlschlägt, versuchen Sie, die Konfigurationseinstellung enableDebug zu aktivieren. Dies führt dazu, dass bei allen internen Fehlern eine Ausnahme ausgelöst wird (wodurch Telemetrie verloren geht). Da es sich hierbei um eine reine Entwicklereinstellung handelt, wird es wahrscheinlich unübersichtlich werden, weil im Rahmen einiger interner Prüfungen Ausnahmen ausgelöst werden. Daher müssen Sie jede Ausnahme überprüfen, um festzustellen, welches Problem zum Fehlschlagen des SDK führt. Verwenden Sie die nicht minierte Version des Skripts (beachten Sie, dass die Erweiterung unten „.js“ und nicht „.min.js“ lautet), da sonst die Ausnahmen unlesbar sind.

Warnung

Dies ist eine reine Entwicklereinstellung, die NIEMALS in einer echten Produktionsumgebung aktiviert werden darf, da Sie sonst Telemetrie verlieren.

src: "https://js.monitor.azure.com/scripts/b/ai.2.js",
cfg:{
    instrumentationKey: "INSTRUMENTATION_KEY",
    enableDebug: true
}});

Wenn dies weiterhin keine Erkenntnisse liefert, melden Sieein Problem auf GitHub mit den Details und einer Beispielwebsite, sofern vorhanden. Geben Sie die Browserversion, das Betriebssystem und Details zum JS-Framework an, um das Problem zu ermitteln.

Blockierung des JavaScript CDN von Application Insights

Eine Blockierung des CDN ist möglich, wenn ein CDN-Endpunkt des JavaScript SDK von Application Insights als unsicher gemeldet und/oder identifiziert wurde. In diesem Fall wird der Endpunkt in einer öffentlichen Sperrliste eingetragen, und die Nutzer dieser Listen beginnen, jeglichen Zugriff zu unterbinden.

Zur Behebung des Problems muss der Besitzer des CDN-Endpunkts mit der für die Sperrliste zuständigen Stelle zusammenarbeiten, die den Endpunkt als unsicher markiert hat, damit er von der entsprechenden Liste entfernt werden kann.

Prüfen Sie, ob der CDN-Endpunkt als unsicher identifiziert wurde.

Je nach Häufigkeit, mit der die Anwendung, Firewall oder Umgebung ihre lokalen Kopien dieser Listen aktualisiert, kann es beträchtliche Zeit in Anspruch nehmen und/oder ein manuelles Eingreifen von Endbenutzern oder IT-Abteilungen des Unternehmens erfordern, um eine Aktualisierung zu erzwingen oder den CDN-Endpunkten ausdrücklich zu gestatten, das Problem zu lösen.

Wenn der CDN-Endpunkt als unsicher identifiziert wird, eröffnen Sie ein Supportticket, um sicherzustellen, dass das Problem so schnell wie möglich behoben wird.

CDN des JavaScript SDK für Application Insights ist blockiert (durch Endbenutzer: durch Browser blockiert; installierter Blocker; persönliche Firewall)

Prüfen Sie, ob Ihre Endbenutzer folgende Aufgaben ausgeführt haben:

  • Ein Browser-Plug-In installiert (typischerweise eine Form von Werbe-, Schadsoftware- oder Popupblocker).
  • Die CDN-Endpunkte von Application Insights in Ihrem Browser oder Proxy als blockiert (oder nicht zulässig) konfiguriert.
  • Eine Firewallregel konfiguriert, die bewirkt, dass die CDN-Domäne für das SDK blockiert wird (oder der DNS-Eintrag nicht aufgelöst wird).

Wenn sie eine dieser Optionen konfiguriert haben, müssen Sie mit ihnen zusammenarbeiten (oder Dokumentation bereitstellen), um die CDN-Endpunkte zuzulassen.

Möglicherweise verwendet das von ihnen installierte Plug-In die öffentliche Sperrliste. Wenn das nicht der Fall ist, handelt es sich höchstwahrscheinlich um eine andere manuell konfigurierte Lösung oder um die Verwendung einer privaten Sperrliste für Domänen.

Hinzufügen von Ausnahmen für CDN-Endpunkte

Arbeiten Sie mit Ihren Endbenutzern zusammen, oder stellen Sie Dokumentation zur Verfügung, die sie darüber informiert, dass sie das Herunterladen von Skripts von CDN-Endpunkten von Application Insights erlauben sollen, indem sie diese in die Ausnahmeliste der Plug-Ins oder Firewallregeln ihres Browsers aufnehmen (was von der Umgebung des Endbenutzers abhängt).

Hier ist ein Beispiel dafür, wie Sie Chrome so konfigurieren können, dass der Zugriff auf Websites zugelassen bzw. blockiert wird.

Das Application Insights CDN wird blockiert (von der Unternehmensfirewall)

Wenn sich Ihre Benutzer in einem Unternehmensnetzwerk befinden, liegt es höchstwahrscheinlich an ihrer Firewalllösung und daran, dass ihre IT-Abteilung eine Art Internetfiltersystem implementiert hat. In diesem Fall müssen Sie mit den Verantwortlichen zusammenarbeiten, um die für Ihre Benutzer notwendigen Regeln zuzulassen.

Hinzufügen von Ausnahmen für CDN-Endpunkte für Unternehmen

Dies ist vergleichbar mit dem Hinzufügen von Ausnahmen für Endbenutzer. Sie müssen jedoch mit der IT-Abteilung des Unternehmens zusammenarbeiten, damit diese die herunterzuladenden CDN-Endpunkte von Application Insights so konfiguriert, dass sie in alle Dienste für Zulassungs- und Sperrlisten für Domänen aufgenommen (oder daraus entfernt) werden.

Warnung

Wenn Ihr Unternehmensbenutzer eine private Cloud nutzt und er keine Form der Ausnahme aktivieren kann, um seinen internen Benutzern öffentlichen Zugriff auf die CDN-Endpunkte zu gewähren, müssen Sie die NPM-Pakete für Application Insights verwenden oder das Application Insights SDK in Ihrem eigenen CDN hosten.

Zusätzliche Problembehandlung für blockiertes CDN

Hinweis

Wenn Ihre Benutzer eine private Cloud nutzen und keinen Zugriff auf das öffentliche Internet haben, müssen Sie das SDK in Ihrem eigenen CDN hosten oder NPM-Pakete verwenden.

Hosten des SDK in Ihrem eigenen CDN

Anstatt dass Ihre Benutzer das Application Insights SDK aus dem öffentlichen CDN herunterladen, können Sie das Application Insights SDK über Ihren eigenen CDN-Endpunkt hosten. Es wird empfohlen, eine bestimmte Version (ai.2.#.#.min.js) zu verwenden, damit Sie die von Ihnen verwendete Version leichter erkennen können. Aktualisieren Sie sie außerdem regelmäßig auf die aktuelle Version (ai.2.min.js), damit Sie alle Fehlerkorrekturen und neuen Features, die verfügbar werden, nutzen können.

Einbetten des Application Insight SDK mithilfe von NPM-Paketen

Anstatt den Ausschnitt und die öffentlichen CDN-Endpunkte zu verwenden, können Sie die NPM-Pakete einsetzen, um das SDK in Ihre eigenen JavaScript-Dateien einzubinden. Das SDK wird dadurch lediglich ein weiteres Paket innerhalb Ihrer eigenen Skripts.

Hinweis

Es wird empfohlen, bei Verwendung von NPM-Paketen auch eine Form von JavaScript-Bundler einzusetzen, um die Codeaufteilung und Minifizierung zu unterstützen.

Wie beim Ausschnitt ist es auch hier möglich, dass Ihre eigenen Skripts (mit oder ohne Verwendung der NPM-Pakete des SDK) von den gleichen hier aufgeführten Blockierungsproblemen betroffen sein können. Abhängig von Ihrer Anwendung, Ihren Benutzern und Ihrem Framework sollten Sie also in Erwägung ziehen, etwas Ähnliches wie die Logik im Ausschnitt zu implementieren, um diese Probleme zu erkennen und zu melden.

Nächste Schritte