Rozwiązywanie problemów z niepowodzeniem ładowania zestawu SDK dla aplikacji internetowych JavaScript

Wyjątek niepowodzenia ładowania zestawu SDK jest tworzony i zgłaszany przez fragment kodu JavaScript (w wersji 3 lub nowszej), gdy wykryje, że nie można pobrać lub zainicjować skryptu zestawu SDK. W sposób uproszczony klient (przeglądarka) użytkowników końcowych nie mógł pobrać zestawu SDK Szczegółowe informacje aplikacji lub zainicjować ze zidentyfikowanej strony hostingu, dlatego nie będą zgłaszane żadne dane telemetryczne ani zdarzenia.

Azure portal browser failure overview

Uwaga

Ten wyjątek jest obsługiwany we wszystkich głównych przeglądarkach, które obsługują interfejs API pobierania() lub XMLHttpRequest. Wyklucza to program IE 8 i poniżej, więc nie otrzymasz tego typu wyjątku zgłoszonego w tych przeglądarkach (chyba że środowisko zawiera poliwypełnianie pobierania).

browser exception detail

Szczegóły stosu zawierają podstawowe informacje o adresach URL używanych przez użytkownika końcowego.

Nazwa Opis
<punkt końcowy CDN> Adres URL, który został użyty (i nie można go pobrać).
<Link pomocy> Adres URL, który łączy się z dokumentacją rozwiązywania problemów (ta strona).
<Adres URL hosta> Pełny adres URL strony, z którego korzysta użytkownik końcowy.
<Adres URL punktu końcowego> Adres URL, który został użyty do zgłoszenia wyjątku, ta wartość może być przydatna do identyfikowania, czy strona hostingu była uzyskiwana z publicznego Internetu, czy z chmury prywatnej.

Najczęstsze przyczyny wystąpienia tego wyjątku:

  • Sporadyczne błędy łączności sieciowej.
  • Awaria Szczegółowe informacje CDN aplikacji.
  • Nie można zainicjować zestawu SDK po załadowaniu skryptu.
  • Aplikacja Szczegółowe informacje CDN JavaScript została zablokowana.

Sporadyczne błędy łączności sieciowej są najczęstszą przyczyną tego wyjątku, szczególnie w scenariuszach roamingu mobilnego, w których użytkownicy sporadycznie tracą łączność sieciową.

W poniższych sekcjach opisano sposób rozwiązywania problemów z każdą potencjalną główną przyczyną tego błędu.

Uwaga

W kilku krokach rozwiązywania problemów założono, że aplikacja ma bezpośrednią kontrolę nad skryptem/>tagiem fragmentu kodu <i jego konfiguracją zwracaną w ramach strony hostingu HTML. Jeśli tego nie zrobisz, te zidentyfikowane kroki nie będą miały zastosowania do danego scenariusza.

Sporadyczne błędy łączności sieciowej

Jeśli użytkownik napotyka sporadyczne błędy łączności sieciowej, istnieje mniej możliwych rozwiązań i zazwyczaj rozwiąże problemy w krótkim czasie. Jeśli na przykład użytkownik ponownie załaduje witrynę (odświeża stronę), pliki zostaną pobrane i zapisane w pamięci podręcznej lokalnie do momentu wydania zaktualizowanej wersji.

Uwaga

Jeśli ten wyjątek jest trwały i występuje u wielu użytkowników (zdiagnozowano szybki i trwały poziom zgłaszanego wyjątku) wraz z zmniejszeniem normalnych danych telemetrycznych klienta, sporadyczne problemy z łącznością sieciową prawdopodobnie nie będą prawdziwą przyczyną problemu i należy kontynuować diagnozowanie innych znanych możliwych problemów.

W takiej sytuacji hostowanie zestawu SDK na własnym CDN jest mało prawdopodobne, aby zapewnić lub zmniejszyć wystąpienia tego wyjątku, ponieważ na Twój własny CDN będzie mieć wpływ ten sam problem.

To samo dotyczy również używania zestawu SDK za pośrednictwem rozwiązania pakietów NPM. Jednak z perspektywy użytkowników końcowych, gdy wystąpi to, że cała aplikacja nie może załadować/zainicjować (a nie tylko zestaw SDK telemetrii — którego nie widzą wizualnie), więc najprawdopodobniej odświeży witrynę, dopóki nie zostanie załadowana całkowicie.

Możesz również spróbować użyć pakietów NPM do osadzenia zestawu SDK Szczegółowe informacje aplikacji.

Aby zminimalizować sporadyczne błędy łączności sieciowej, zaimplementowaliśmy nagłówki Cache-Control na wszystkich plikach CDN, tak aby po pobraniu przez przeglądarkę użytkownika końcowego bieżącej wersji zestawu SDK nie trzeba było pobierać ponownie, a przeglądarka ponownie użyje wcześniej uzyskanej kopii (zobacz, jak działa buforowanie). Jeśli sprawdzanie buforowania nie powiedzie się lub została wydana nowa wersja, przeglądarka użytkownika końcowego będzie musiała pobrać zaktualizowaną wersję. W scenariuszu niepowodzenia sprawdzania może być widoczny poziom "szumu" w tle lub tymczasowy wzrost, gdy wystąpi nowe wydanie i zostanie udostępniony ogólnie (wdrożony w CDN).

Awaria Szczegółowe informacje CDN aplikacji

Możesz sprawdzić, czy wystąpiła awaria aplikacji Szczegółowe informacje CDN, próbując uzyskać dostęp do punktu końcowego CDN bezpośrednio z przeglądarki (na przykład https://js.monitor.azure.com/scripts/b/ai.2.min.js) z innej lokalizacji niż prawdopodobnie z twojej własnej maszyny dewelopera (przy założeniu, że organizacja nie zablokowała tej domeny).

Jeśli potwierdzisz, że wystąpiła awaria, możesz utworzyć nowy bilet pomocy technicznej.

Nie można zainicjować zestawu SDK po załadowaniu skryptu

Gdy nie można zainicjować zestawu SDK, <skrypt />został pomyślnie pobrany z CDN, ale kończy się niepowodzeniem podczas inicjowania. Może to być spowodowane brakującymi lub nieprawidłowymi zależnościami lub jakąś formą wyjątku języka JavaScript.

Pierwszą rzeczą, która należy sprawdzić, czy zestaw SDK został pomyślnie pobrany, jeśli skrypt nie został pobrany, ten scenariusz nie jest przyczyną wyjątku niepowodzenia ładowania zestawu SDK.

Szybkie sprawdzanie: użycie przeglądarki obsługującej narzędzia deweloperskie (F12) umożliwia sprawdzenie na karcie sieciowej, czy skrypt zdefiniowany w src konfiguracji fragmentu kodu został pobrany z kodem odpowiedzi 200 (powodzenie) lub 304 (nie zmieniono). Do przeglądania ruchu sieciowego można również użyć narzędzia takiego jak fiddler.

Poniższe sekcje zawierają różne opcje raportowania. Zalecamy utworzenie biletu pomocy technicznej lub zgłoszenie problemu w GitHub.

Podstawowe reguły raportowania:

  • Jeśli problem dotyczy tylko niewielkiej liczby użytkowników i określonej lub podzbioru wersji przeglądarki (sprawdź szczegóły zgłoszonego wyjątku), prawdopodobnie jest to problem tylko dla użytkownika końcowego lub środowiska, co prawdopodobnie będzie wymagać od aplikacji zapewnienia dodatkowych polyfill implementacji. W tym celu zgłoś problem dotyczący GitHub.
  • Jeśli ten problem dotyczy całej aplikacji i dotyczy to wszystkich użytkowników, prawdopodobnie jest to problem związany z wydaniem i dlatego należy utworzyć nowy bilet pomocy technicznej.

Wyjątki języka JavaScript

Najpierw umożliwia sprawdzenie wyjątków języka JavaScript przy użyciu przeglądarki obsługującej narzędzia deweloperskie (F12) załadowanie strony i sprawdzenie, czy wystąpiły jakiekolwiek wyjątki.

Jeśli w skry skryscie zestawu SDK są zgłaszane wyjątki (na przykład ai.2.min.js), może to oznaczać, że konfiguracja przekazana do zestawu SDK zawiera nieoczekiwaną lub brakującą wymaganą konfigurację lub wadliwe wydanie zostało wdrożone w CDN.

Aby sprawdzić, czy konfiguracja jest uszkodzona, zmień konfigurację przekazaną do fragmentu kodu (jeśli jeszcze tego nie zrobiono), aby zawierała tylko klucz instrumentacji jako wartość ciągu.

Uwaga

31 marca 2025 r. zostanie zakończone świadczenie pomocy technicznej dla pozyskiwania klucza instrumentacji. Pozyskiwanie klucza instrumentacji będzie nadal działać, ale nie będziemy już zapewniać aktualizacji ani obsługi funkcji. Przejście do parametrów połączenia w celu skorzystania z nowych możliwości.

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

Jeśli w przypadku korzystania z tej minimalnej konfiguracji nadal występuje wyjątek języka JavaScript w skrypcie zestawu SDK, utwórz nowy bilet pomocy technicznej , ponieważ będzie to wymagało wycofywania uszkodzonej kompilacji, ponieważ prawdopodobnie jest to problem z nowo wdrożoną wersją.

Jeśli wyjątek zniknie, problem prawdopodobnie jest spowodowany niezgodnością typu lub nieoczekiwaną wartością. Rozpocznij dodawanie opcji konfiguracji z powrotem jeden po drugim i przetestuj, dopóki wyjątek nie wystąpi ponownie. Następnie sprawdź dokumentację elementu powodującego problem. Jeśli dokumentacja jest niejasna lub potrzebujesz pomocy, zgłoś problem w GitHub.

Jeśli konfiguracja została wcześniej wdrożona i działa, ale po prostu zaczęła zgłaszać ten wyjątek, może to być problem z nowo wdrożoną wersją, sprawdź, czy ma to wpływ tylko na niewielki zestaw użytkowników/przeglądarki, a następnie zgłoś problem w GitHub lub utwórz nowy bilet pomocy technicznej.

Włączanie debugowania konsoli

Zakładając, że nie ma wyjątków zgłaszanych w następnym kroku, jest włączenie debugowania konsoli przez dodanie loggingLevelConsole ustawienia do konfiguracji, spowoduje to wysłanie wszystkich błędów inicjowania i ostrzeżeń do konsoli przeglądarek (zwykle dostępnych za pośrednictwem narzędzi deweloperskich (F12)). Wszelkie zgłoszone błędy powinny być objaśniające i jeśli potrzebujesz dalszej pomocy, zgłoś problem w GitHub.

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

Uwaga

Podczas inicjowania zestaw SDK przeprowadza pewne podstawowe testy pod kątem znanych głównych zależności. Jeśli nie zostaną one dostarczone przez bieżące środowisko uruchomieniowe, zgłosi błędy jako komunikaty ostrzegawcze do konsoli, ale tylko wtedy, gdy loggingLevelConsole wartość jest większa niż zero.

Jeśli nadal nie można zainicjować, spróbuj włączyć enableDebug ustawienie konfiguracji. Spowoduje to zgłoszenie wszystkich błędów wewnętrznych jako wyjątku (co spowoduje utratę danych telemetrycznych). Ponieważ jest to ustawienie tylko dla deweloperów, prawdopodobnie otrzyma hałaśliwy z wyjątkami zgłaszanymi w ramach niektórych wewnętrznych kontroli, więc należy przejrzeć każdy wyjątek, aby ustalić, który problem powoduje niepowodzenie zestawu SDK. Użyj nieokreślonej wersji skryptu (zwróć uwagę, że poniższe rozszerzenie to ".js", a nie ".min.js"), w przeciwnym razie wyjątki będą nieczytelne.

Ostrzeżenie

Jest to ustawienie tylko dla deweloperów i nigdy nie powinno być włączone w pełnym środowisku produkcyjnym, ponieważ utracisz dane telemetryczne.

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

Jeśli nadal nie zapewnia to żadnych szczegółowych informacji, należy zgłosić problem na GitHub ze szczegółami i przykładową witryną, jeśli masz. Uwzględnij wersję przeglądarki, system operacyjny i szczegóły struktury JS, aby ułatwić identyfikację problemu.

CDN JavaScript Szczegółowe informacje aplikacji została zablokowana

Blokowany CDN jest możliwy, gdy zgłoszono punkt końcowy CDN zestawu SDK Szczegółowe informacje JavaScript aplikacji Szczegółowe informacje lub zidentyfikowano go jako niebezpieczny. W takim przypadku punkt końcowy zostanie publicznie zablokowany, a odbiorcy tych list zaczną blokować cały dostęp.

Aby rozwiązać ten problem, właściciel punktu końcowego CDN musi pracować z jednostką listy zablokowanych, która oznaczyła punkt końcowy jako niebezpieczny, aby można było go usunąć z odpowiedniej listy.

Sprawdź, czy punkt końcowy CDN został zidentyfikowany jako niebezpieczny.

W zależności od częstotliwości aktualizowania lokalnych kopii tych list przez aplikację, zaporę lub środowisko może zająć dużo czasu i/lub wymagać ręcznej interwencji użytkowników końcowych lub firmowych działów IT, aby wymusić aktualizację lub jawnie zezwolić CDN punktom końcowym na rozwiązanie problemu.

Jeśli punkt końcowy CDN zostanie zidentyfikowany jako niebezpieczny, utwórz bilet pomocy technicznej, aby upewnić się, że problem zostanie rozwiązany tak szybko, jak to możliwe.

Aplikacja Szczegółowe informacje CDN JavaScript jest blokowana (przez użytkownika końcowego — zablokowana przez przeglądarkę; zainstalowana blokada; zapora osobista)

Sprawdź, czy użytkownicy końcowi mają:

  • Zainstalowano wtyczkę przeglądarki (zazwyczaj jakąś formę reklamy, złośliwego oprogramowania lub blokowanie wyskakujących okienek).
  • Zablokowane (lub niedozwolone) punkty końcowe aplikacji Szczegółowe informacje CDN w przeglądarce lub serwerze proxy.
  • Skonfigurowano regułę zapory, która powoduje zablokowanie domeny CDN dla zestawu SDK (lub nie można rozpoznać wpisu DNS).

Jeśli skonfigurowano dowolną z tych opcji, należy pracować z nimi (lub podać dokumentację), aby zezwolić na CDN punktów końcowych.

Możliwe, że zainstalowana wtyczka korzysta z publicznej listy zablokowanych. Jeśli tak nie jest, najprawdopodobniej jest to inne ręcznie skonfigurowane rozwiązanie lub korzysta z listy bloków domeny prywatnej.

Dodawanie wyjątków dla CDN punktów końcowych

Skontaktuj się z użytkownikami końcowymi lub podaj dokumentację informującą ich, że powinni zezwolić na pobieranie skryptów z punktów końcowych usługi Application Szczegółowe informacje CDN przez uwzględnienie ich na liście wyjątków wtyczki przeglądarki lub reguły zapory (będzie się różnić w zależności od środowiska użytkownika końcowego).

Oto przykład sposobu konfigurowania przeglądarki Chrome w celu zezwolenia na dostęp do witryn internetowych lub blokowania go.

Szczegółowe informacje CDN aplikacji jest blokowana (przez zaporę firmową)

Jeśli użytkownicy końcowi znajdują się w sieci firmowej, najprawdopodobniej jest to ich rozwiązanie zapory i że ich dział IT zaimplementował jakąś formę systemu filtrowania w Internecie. W takim przypadku należy pracować z nimi, aby zezwolić na niezbędne reguły dla użytkowników końcowych.

Dodawanie wyjątków dla punktów końcowych CDN dla korporacji

Jest to podobne do dodawania wyjątków dla użytkowników końcowych, ale należy pracować z działem IT firmy, aby skonfigurować punkty końcowe usługi Application Szczegółowe informacje CDN do pobrania, włączając (lub usuwając) je w dowolnych usługach blokowania lub listy dozwolonych domen.

Ostrzeżenie

Jeśli użytkownik firmowy korzysta z chmury prywatnej i nie może włączyć żadnej formy wyjątku w celu zapewnienia użytkownikom wewnętrznym dostępu publicznego do punktów końcowych CDN, należy użyć pakietów NpM aplikacji Szczegółowe informacje lub hostować zestaw SDK usługi Application Szczegółowe informacje na własną CDN.

Dodatkowe rozwiązywanie problemów z zablokowanym CDN

Uwaga

Jeśli użytkownicy korzystają z chmury prywatnej i nie mają dostępu do publicznego Internetu, musisz hostować zestaw SDK na własną CDN lub używać pakietów NPM.

Hostowanie zestawu SDK na własną CDN

Zamiast użytkowników końcowych pobierających zestaw SDK usługi Application Szczegółowe informacje z publicznej CDN możesz hostować zestaw SDK Szczegółowe informacje aplikacji z poziomu własnego punktu końcowego CDN. Zaleca się użycie określonej wersji (ai.2.#.#.min.js), aby ułatwić określenie używanej wersji. Ponadto należy ją regularnie aktualizować do bieżącej wersji (ai.2.min.js), aby można było korzystać z wszelkich poprawek usterek i nowych funkcji, które stają się dostępne.

Osadzanie zestawu SDK usługi Application Insights za pomocą pakietów NPM

Zamiast używać fragmentu kodu i publicznych punktów końcowych CDN, można użyć pakietów NPM do uwzględnienia zestawu SDK jako części własnych plików JavaScript. Zestaw SDK stanie się kolejnym pakietem w ramach własnych skryptów.

Uwaga

Zaleca się, aby w przypadku korzystania z pakietów NPM używać również jakiejś formy pakietu JavaScript , aby ułatwić dzielenie i minimalizowanie kodu.

Podobnie jak w przypadku fragmentu kodu, istnieje również możliwość, że na twoje własne skrypty (z pakietami NPM zestawu SDK lub bez nich) mogą mieć wpływ te same problemy blokujące wymienione tutaj, więc w zależności od aplikacji, użytkowników i struktury warto rozważyć zaimplementowanie czegoś podobnego do logiki we fragmencie kodu, aby wykryć i zgłosić te problemy.

Następne kroki