Risoluzione dei problemi di Application Insights JavaScript SDK
Questo articolo illustra come risolvere vari problemi che coinvolgono Application Insights JavaScript SDK. Gli argomenti di questo articolo includono l'errore di caricamento dell'SDK per le app Web JavaScript e il supporto della mappa di origine per le app JavaScript.
Risolvere gli errori di caricamento dell'SDK per le app Web JavaScript
Le sezioni seguenti illustrano i sintomi, le cause e le soluzioni per uno scenario specifico di errore di caricamento dell'SDK per le app Web JavaScript.
Sintomi
Nell'elemento <head> della pagina Web monitorata, il frammento javaScript (versione 3 o successiva) crea e segnala l'eccezione seguente quando rileva che lo script SDK non è stato scaricato o inizializzato:
Errore di caricamento dell'SDK: non è stato possibile caricare lo script di Application Insights SDK (vedere stack per informazioni dettagliate)
Questo messaggio indica che il client dell'utente (browser) non può scaricare Application Insights SDK o inizializzare dalla pagina di hosting identificata. Di conseguenza, non vengono visualizzati dati di telemetria o eventi.
Note
Questa eccezione è supportata in tutti i browser principali che supportano l'API fetch() o XMLHttpRequest. Queste versioni del browser escludono Microsoft Internet Explorer 8 e versioni precedenti. Pertanto, tali browser non indicherà questo tipo di eccezione a meno che l'ambiente non includa un polyfill di recupero.
I dettagli dello stack includono le informazioni di base sugli URL usati dall'utente.
| Nome | Descrizione |
|---|---|
| <CDN Endpoint> | URL usato (e non riuscito) per scaricare l'SDK. |
| <Collegamento alla Guida> | URL collegato alla documentazione per la risoluzione dei problemi (questa pagina). |
| <Host URL> | URL completo della pagina usata dall'utente. |
| <URL endpoint> | URL utilizzato per segnalare l'eccezione. Questo valore può aiutare a identificare se la rete Internet pubblica o un cloud privato ha eseguito l'accesso alla pagina di hosting. |
L'elenco seguente contiene i motivi più comuni per cui si verifica questa eccezione:
Errore di connettività di rete intermittente
Interruzione di Application Insights rete per la distribuzione di contenuti (rete CDN)
Errore di inizializzazione dell'SDK dopo il caricamento dello script
Blocco della rete CDN JavaScript di Application Insights
L'errore di connettività di rete intermittente è il motivo più comune per questa eccezione, in particolare negli scenari di roaming per dispositivi mobili.
Le sezioni seguenti illustrano come risolvere ogni potenziale causa radice di questo errore.
Note
Alcuni di questi passaggi presuppongono che l'applicazione abbia il controllo diretto dello script/>tag snippet <e della relativa configurazione restituita come parte della pagina HTML di hosting. Se queste condizioni non si applicano allo scenario, questi passaggi non si applicano.
Causa 1: Errore di connettività di rete intermittente
Se l'utente riscontra errori intermittenti di connettività di rete, esistono meno soluzioni possibili rispetto ad altre cause. Tuttavia, questo errore si risolve in genere rapidamente. Ad esempio, se l'utente aggiorna la pagina per ricaricare il sito, i file alla fine vengono scaricati e memorizzati nella cache in locale fino al rilascio di una versione aggiornata.
Soluzione 1a: Scaricare una versione aggiornata dell'SDK
Per ridurre al minimo gli errori di connettività di rete intermittenti, sono state implementate Cache-Control intestazioni in tutti i file della rete CDN. Dopo che il browser dell'utente scarica la versione corrente dell'SDK, non è necessario scaricarla di nuovo perché riutilizza la copia ottenuta in precedenza. Vedere come funziona la memorizzazione nella cache. Se il controllo di memorizzazione nella cache ha esito negativo o è disponibile una nuova versione, il browser dell'utente deve scaricare la versione aggiornata. Pertanto, è possibile che venga visualizzato un livello di sfondo " rumore" nello scenario di errore di controllo. In alternativa, è possibile che venga visualizzato un picco temporaneo quando si verifica una nuova versione e diventa disponibile a livello generale (distribuito nella rete CDN).
Soluzione 1b: usare pacchetti npm per incorporare l'SDK insieme all'applicazione in un singolo bundle
L'eccezione di errore di caricamento dell'SDK è persistente e si verifica per molti utenti insieme a una riduzione dei normali dati di telemetria del client? In questo caso, i problemi di connettività di rete intermittenti probabilmente non sono la vera causa del problema ed è consigliabile esplorare altre possibili cause.
Note
Un'indicazione comune che questo errore si verifica per più utenti è che l'eccezione viene segnalata a un livello rapido e sostenuto.
In questo caso, l'hosting dell'SDK nella rete CDN non è probabile che fornisca o riduca le occorrenze di questa eccezione. Lo stesso problema riguarda la rete CDN personalizzata e si verifica anche se si usa l'SDK tramite una soluzione di pacchetto npm. L'errore di quest'ultimo scenario si verifica soprattutto se Application Insights è incluso in un bundle diverso da quello dell'applicazione monitorata, perché l'errore è garantito in almeno uno di questi bundle. Dal punto di vista dell'utente, quando si verifica questa eccezione, l'intera applicazione non viene caricata o inizializzata, non solo l'SDK di telemetria (che gli utenti non vedono). Pertanto, gli utenti continueranno probabilmente ad aggiornare il sito fino a quando non carica completamente.
È possibile provare a usare pacchetti npm per incorporare Application Insights SDK insieme all'applicazione monitorata in un singolo bundle. Anche se in questo scenario potrebbe verificarsi un errore di intermittenza, un bundle combinato offre una reale possibilità di risolvere il problema.
Causa 2: Interruzione della rete CDN di Application Insights
Per verificare che sia presente un'interruzione della rete CDN di Application Insights, provare ad accedere all'endpoint della rete CDN direttamente dal browser da una posizione diversa da quella degli utenti. Ad esempio, è possibile provare ad accedere https://js.monitor.azure.com/scripts/b/ai.2.min.js dal proprio computer di sviluppo. Si presuppone che l'organizzazione non abbia bloccato questo dominio.
Soluzione 2: Creare un ticket di supporto
Se si verifica che esista un'interruzione, è possibile creare un nuovo ticket di supporto.
Causa 3: SDK non inizializzato dopo il caricamento dello script
Se l'SDK non viene inizializzato, lo <script/> viene ancora scaricato correttamente dalla rete CDN, ma non riesce durante l'inizializzazione. Questo errore si verifica a causa di dipendenze mancanti o non valide o a causa di una qualche forma di eccezione JavaScript.
Soluzione 3: Verificare la corretta esecuzione del download dell'SDK o delle eccezioni JavaScript oppure abilitare il debug del browser
Passaggio 1: Verificare la corretta esecuzione del download dell'SDK
Controllare se l'SDK è stato scaricato correttamente. Se non si è verificato alcun download di script, questo scenario non è la causa dell'eccezione di caricamento dell'SDK. Usare un browser che supporta gli strumenti di sviluppo. Selezionare F12 per visualizzare gli strumenti di sviluppo e quindi selezionare la scheda Rete. Verificare che lo script definito nella configurazione del frammento di codice src sia stato scaricato. A tale scopo, verificare la presenza di codice 200 di risposta (esito positivo) o 304 (non modificato). Per esaminare il traffico di rete, è anche possibile usare uno strumento di debug Web, ad esempio Fiddler.
Se l'SDK non è stato scaricato correttamente, esaminare la tabella seguente per comprendere le diverse opzioni di creazione di report.
| Scenario | Causa | Azione |
|---|---|---|
| Il problema riguarda solo alcuni utenti e una versione specifica del browser o un subset di versioni del browser. Controllare i dettagli sull'eccezione segnalata. | Il problema è probabilmente solo se utenti o ambienti specifici richiedono che l'applicazione fornisca implementazioni aggiuntive polyfill . |
Segnalare un problema in GitHub. |
| Il problema interessa l'intera applicazione e tutti gli utenti. | Si tratta di un problema correlato al rilascio. | Creare un nuovo ticket di supporto. |
Se l'SDK è stato scaricato correttamente, esaminare le sezioni seguenti per risolvere il problema di inizializzazione dell'SDK.
Passaggio 2: Verificare la presenza di eccezioni JavaScript
Verificare la presenza di eccezioni JavaScript. Usare un browser che supporta gli strumenti di sviluppo. Selezionare F12 per visualizzare gli strumenti di sviluppo, caricare la pagina e quindi verificare se si sono verificate eccezioni. Lo script SDK (ad esempio, in ai.2.min.js) causa eccezioni? In questo caso, si è verificato uno degli scenari seguenti:
La configurazione passata all'SDK contiene una configurazione imprevista.
La configurazione passata all'SDK manca una configurazione necessaria.
Una versione non riuscita è stata distribuita nella rete CDN.
Per verificare la presenza di una configurazione errata, modificare la configurazione passata al frammento di codice (se non è già stato fatto) in modo che includa solo la chiave di strumentazione come valore stringa. Il codice seguente mostra una modifica della configurazione del frammento di codice di esempio.
Note
Il supporto per l'inserimento delle chiavi di strumentazione termina il 31 marzo 2025. L'inserimento delle chiavi di strumentazione continuerà a funzionare, ma non saranno più garantiti aggiornamenti o supporto per la funzionalità. Vedere Transizione alle stringa di connessione per sfruttare le nuove funzionalità.
<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
cfg: {
instrumentationKey: "<instrumentation-key-guid>"
}});
</script>
Quando si usa questa configurazione minima, se viene comunque visualizzata un'eccezione JavaScript nello script SDK, creare un nuovo ticket di supporto. Per risolvere il problema, è necessario eseguire il rollback della compilazione difettosa. Ciò è dovuto al fatto che una versione appena distribuita è probabilmente la causa del problema.
Se l'eccezione scompare, è probabile che un tipo non corrisponde o un valore imprevisto causi il problema. Iniziare la risoluzione dei problemi ripristinando le opzioni di configurazione una alla volta e testando dopo ogni modifica fino a quando l'eccezione non si verifica nuovamente. Controllare quindi la documentazione relativa all'elemento che causa il problema. Se la documentazione non è chiara o se è necessaria assistenza, segnalare un problema in GitHub.
La configurazione è stata distribuita e funzionante in precedenza, ma ora segnala questa eccezione? In questo caso, potrebbe verificarsi un problema che interessa una versione appena distribuita. Controllare se l'eccezione influisce solo su un piccolo set di utenti o browser. Segnalare un problema in GitHub o creare un nuovo ticket di supporto.
Passaggio 3: Abilitare il debug della console del browser
Se non si sono verificate eccezioni generate, è necessario abilitare il debug della console aggiungendo l'impostazione loggingLevelConsole alla configurazione, come illustrato nell'esempio di configurazione del frammento di codice seguente. Questa modifica invia tutti gli errori di inizializzazione e gli avvisi alla console del browser. Per visualizzare la console del browser, selezionare F12 per aprire gli strumenti di sviluppo e quindi selezionare il Scheda Console . Eventuali errori segnalati devono essere autoesplicativi. Se è necessaria ulteriore assistenza, inviare un problema in GitHub.
<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
cfg: {
instrumentationKey: "<instrumentation-key-guid>",
loggingLevelConsole: 2
}});
</script>
Note
Durante l'inizializzazione, l'SDK esegue alcuni controlli di base per le dipendenze principali note. Se il runtime corrente non fornisce questi controlli, il runtime segnala gli errori come messaggi di avviso alla console (ma solo se il valore dell'impostazione loggingLevelConsole è maggiore di zero).
Se l'SDK non viene ancora inizializzato, provare ad abilitare l'impostazione di configurazione enableDebug. Dopo aver apportato questa modifica, tutti gli errori interni vengono generati come eccezioni. Ciò causa una perdita di dati di telemetria. Poiché questa impostazione è destinata solo agli sviluppatori, è probabile che vengano generate più eccezioni a causa di controlli interni. Esaminare ogni eccezione per determinare il problema che causa l'esito negativo dell'SDK. Usare la versione nonminificata dello script (modificando l'estensione del nome file da .min.js a .js). In caso contrario, le eccezioni sono illeggibili. Il codice seguente mostra le modifiche alla configurazione del frammento di codice di esempio.
Avviso
Questa impostazione di sola sviluppatore non deve mai essere abilitata in un ambiente di produzione completo, perché questa operazione causa la perdita dei dati di telemetria.
<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.js",
cfg:{
instrumentationKey: "<instrumentation-key-guid>",
enableDebug: true
}});
</script>
Se questa azione non fornisce ancora informazioni dettagliate, è consigliabile segnalare un problema in GitHub fornendo i dettagli e un sito di esempio, se ne usi uno. Includere la versione del browser, il sistema operativo e i dettagli del framework JavaScript per identificare il problema.
Causa 4: Blocco della rete CDN JavaScript di Application Insights
Un blocco della rete CDN è possibile se un endpoint della rete CDN javaScript SDK di Application Insights viene segnalato o identificato come non sicuro. In questo caso, l'endpoint è elencato pubblicamente e i consumer di questi elenchi iniziano a bloccare tutti gli accessi.
Per risolvere questo problema, il proprietario dell'endpoint della rete CDN deve funzionare con l'entità blocklist che ha contrassegnato l'endpoint come non sicuro. L'entità di blocco può quindi rimuovere l'endpoint dall'elenco pertinente.
Controllare i seguenti siti Web di sicurezza Internet per sapere se identificano l'endpoint della rete CDN come non sicuro:
La risoluzione di questo problema potrebbe richiedere molto tempo. Gli utenti o i reparti IT aziendali potrebbero dover forzare un aggiornamento o consentire in modo esplicito gli endpoint della rete CDN. Il tempo totale necessario per risolvere questo problema dipende dalla frequenza richiesta dall'applicazione, dal firewall o dall'ambiente per aggiornare le copie locali degli elenchi.
Se l'endpoint della rete CDN viene identificato come non sicuro, creare un ticket di supporto per risolvere il problema il prima possibile.
Le sezioni seguenti illustrano in modo più specifico il modo in cui può verificarsi un blocco e come correggere il blocco.
Causa 4a: Blocco utente (browser, blocco installato o firewall personale)
Verificare se gli utenti hanno eseguito una delle azioni di configurazione seguenti:
Installato un plug-in del browser (in genere sotto forma di annuncio, malware o blocco popup)
Bloccato o non consentito gli endpoint della rete CDN di Application Insights nel browser o nel proxy
Configurazione di una regola del firewall che causa un blocco del dominio della rete CDN per l'SDK (o un errore di risoluzione della voce DNS)
Soluzione 4a: Aggiungere eccezioni blocklist per gli endpoint della rete CDN
Se gli utenti hanno preso una delle azioni di configurazione elencate, usarle (o fornire la documentazione) per consentire gli endpoint della rete CDN.
Gli utenti potrebbero aver installato plug-in che usano l'elenco di blocchi pubblici. In caso contrario, è probabile che usino un'altra soluzione configurata manualmente o che i plug-in usino un elenco di blocchi di dominio privato.
Indicare agli utenti di consentire il download di script dagli endpoint della rete CDN di Application Insights includendo gli endpoint nell'elenco di eccezioni delle regole del firewall o del plug-in del browser. Questi elenchi variano in base all'ambiente utente.
Ecco un esempio di questa situazione che mostra come configurare Google Chrome per consentire o bloccare l'accesso ai siti Web.
Causa 4b: Blocco del firewall aziendale
Se gli utenti si trovano in una rete aziendale, è probabile che il firewall aziendale sia l'origine del blocco della rete CDN. Il reparto IT aziendale ha probabilmente implementato una forma di sistema di filtro Internet.
Soluzione 4b1: Aggiungere eccezioni per gli endpoint della rete CDN per le aziende
Importante
Gli utenti usano un cloud privato e non hanno accesso a Internet pubblico? In questo caso, è necessario usare i pacchetti npm di Application Insights per incorporare l'SDK o ospitare Application Insights SDK nella propria rete CDN.
Collaborare con il reparto IT dell'azienda per consentire le regole necessarie per gli utenti. Questa soluzione è simile all'aggiunta di eccezioni per gli utenti. Chiedere al reparto IT di configurare gli endpoint della rete CDN di Application Insights per il download includendo (o rimuovendoli) in qualsiasi elenco di domini bloccati o consenti servizi di elenco.
Soluzione 4b2: Ospitare l'SDK nella rete CDN personalizzata
Anziché fare in modo che gli utenti scarichino Application Insights SDK dalla rete CDN pubblica, è possibile ospitare Application Insights SDK nel proprio endpoint della rete CDN. È consigliabile usare una versione specifica (ai.2.#.#.min.js) dell'SDK per semplificare l'identificazione della versione in uso. Aggiornare regolarmente l'SDK alla versione corrente (ai.2.min.js) in modo da poter usare eventuali correzioni di bug e nuove funzionalità che diventano disponibili.
Soluzione 4b3: Usare pacchetti npm per incorporare Application Insights SDK
Anziché usare il frammento di codice e aggiungere endpoint della rete CDN pubblica, è possibile usare i pacchetti npm per includere l'SDK come parte dei propri file JavaScript. L'SDK diventa solo un altro pacchetto all'interno dei propri script. Per altre informazioni, vedere la sezione relativa alla configurazione basata su npm della pagina GitHub di Application Insights JavaScript SDK.
Note
Quando si usano pacchetti npm, è consigliabile usare anche una forma di bundler JavaScript per semplificare la suddivisione e la minimizzazione del codice.
Come per il frammento di codice, gli stessi problemi di blocco visualizzati qui potrebbero influire sui propri script (con o senza usare i pacchetti npm dell'SDK). A seconda dell'applicazione, degli utenti e del framework, è possibile prendere in considerazione l'implementazione di un codice simile alla logica nel frammento di codice per rilevare e segnalare questi problemi.
Risolvere i problemi relativi al supporto delle mappe di origine per le applicazioni JavaScript
La tabella seguente illustra alcuni problemi che coinvolgono il supporto della mappa di origine per le applicazioni JavaScript e offre strategie per risolvere questi problemi.
| Problema | Descrizione |
|---|---|
| Impostazioni necessarie per il controllo degli accessi in base al ruolo di Azure nel contenitore BLOB | A qualsiasi utente del portale che usa questa funzionalità deve essere assegnato almeno un ruolo lettore di dati BLOB di archiviazione per il contenitore BLOB. È necessario assegnare questo ruolo a chiunque voglia usare le mappe di origine tramite questa funzionalità. A seconda della modalità di creazione del contenitore, questo ruolo potrebbe non essere stato assegnato automaticamente all'utente o al team. |
| Mappa di origine non trovata | Per risolvere questo problema, eseguire le azioni seguenti:
|
Correggere l'avviso "Click Event rows with no parentId value" (Fare clic su righe evento senza valore parentId).
Quando si usa Application Insights e il plug-in Click Analytics Auto-Collection nell'applicazione, nella cartella di lavoro di Application Insights potrebbe essere visualizzato l'avviso di telemetria seguente: "Fare clic su Righe evento senza valore parentId".
Causa
Questo problema può verificarsi se l'ID padre non è specificato nell'elemento HTML padre. Questa condizione fa sì che l'evento venga attivato su tutti gli elementi padre.
Soluzione
Per risolvere questo problema, aggiungere l'attributo data-parentid o data-<customPrefix>-parentid all'elemento HTML padre. Ecco un esempio del codice HTML:
<div data-heart-id="demo Header" data-heart-parentid="demo.Header" data-heart-parent-group="demo.Header.Group">
Passaggi successivi
Dichiarazione di non responsabilità sulle informazioni di terze parti
I prodotti di terzi citati in questo articolo sono prodotti da società indipendenti da Microsoft. Microsoft non rilascia alcuna garanzia implicita o esplicita relativa alle prestazioni o all'affidabilità di tali prodotti
Contattaci per ricevere assistenza
In caso di domande o bisogno di assistenza, creare una richiesta di supporto tecnico oppure formula una domanda nel Supporto della community di Azure. È possibile anche inviare un feedback sul prodotto al feedback della community di Azure.