Risoluzione dei problemi di Application Insights JavaScript SDK
Questo articolo illustra come risolvere i vari problemi che coinvolgono Application Insights JavaScript SDK. Gli argomenti di questo articolo includono errori di caricamento dell'SDK per le app Web JavaScript e supporto della mappa di origine per le app JavaScript.
Risolvere i problemi di caricamento dell'SDK per le app Web JavaScript
Le sezioni seguenti illustrano i sintomi, le cause e le soluzioni per uno specifico scenario di errore di carico SDK per le app Web JavaScript.
Sintomi
Nell'elemento <head> della pagina Web che si sta monitorando, il frammento di codice 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. Pertanto, non vengono visualizzati dati di telemetria o eventi.
Nota
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 segnaleranno questo tipo di eccezione a meno che l'ambiente non includa un polifill 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 sulla risoluzione dei problemi (questa pagina). |
| <Host URL> | URL completo della pagina usata dall'utente. |
| <Endpoint URL> | URL usato per segnalare l'eccezione. Questo valore può essere utile per identificare se internet pubblico 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 Content Delivery Network (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 di questa eccezione, soprattutto negli scenari di roaming mobile.
Le sezioni seguenti illustrano come risolvere ogni potenziale causa radice di questo errore.
Nota
Alcuni di questi passaggi presuppongono che l'applicazione abbia il controllo diretto dello script/>tag del frammento di codice < e della relativa configurazione restituita come parte della pagina HTML di hosting. Se queste condizioni non si applicano allo scenario, anche questi passaggi non si applicano.
Causa 1: Errore di connettività di rete intermittente
Se l'utente riscontra errori di connettività di rete intermittenti, esistono meno soluzioni possibili rispetto ad altre cause. Tuttavia, questo errore in genere si risolve rapidamente. Ad esempio, se l'utente aggiorna la pagina per ricaricare il sito, i file 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 ha scaricato la versione corrente dell'SDK, non è necessario scaricarla di nuovo perché riutilizza la copia ottenuta in precedenza. Vedere il funzionamento della 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, potrebbe verificarsi 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 unico bundle
L'eccezione di errore di carico dell'SDK è persistente e si verifica per molti utenti insieme a una riduzione dei normali dati di telemetria client? In questo caso, i problemi di connettività di rete intermittente probabilmente non sono la vera causa del problema ed è consigliabile esplorare altre possibili cause.
Nota
Un'indicazione comune che questo errore si verifica per più utenti è che l'eccezione viene segnalata a un livello rapido e prolungato.
In questo caso, è improbabile che l'hosting dell'SDK nella propria rete CDN fornisca o riduca le occorrenze di questa eccezione. Lo stesso problema interessa la rete CDN 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 si verifica sicuramente in almeno uno di questi bundle. Dal punto di vista dell'utente, quando si verifica questa eccezione, l'intera applicazione non riesce a caricare o inizializzare, non solo l'SDK di telemetria (che gli utenti non vedono). Pertanto, gli utenti probabilmente continueranno ad aggiornare il sito fino a quando non viene caricato completamente.
È possibile provare a usare pacchetti npm per incorporare Application Insights SDK insieme all'applicazione monitorata in un unico bundle. Anche se in questo scenario potrebbe ancora 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 si verifichi 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 l'esistenza di un'interruzione, è possibile creare un nuovo ticket di supporto.
Causa 3: L'SDK non è stato inizializzato dopo il caricamento dello script
Se l'SDK non viene inizializzato, lo <script /> viene comunque 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 se il download dell'SDK o le eccezioni JavaScript sono riuscite oppure abilitare il debug del browser
Passaggio 1: Verificare che il download dell'SDK sia riuscito
Verificare se l'SDK è stato scaricato correttamente. Se non si è verificato alcun download di script, questo scenario non è la causa dell'eccezione di errore 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 interessa solo alcuni utenti e una versione specifica del browser o un subset di versioni del browser. Controllare i dettagli sull'eccezione segnalata. | Il problema è probabile solo se utenti o ambienti specifici richiedono che l'applicazione fornisca implementazioni aggiuntive polyfill . |
Registrare un problema in GitHub. |
| Il problema interessa l'intera applicazione e tutti gli utenti. | Si tratta di un problema correlato alla versione. | 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.
Alla configurazione passata all'SDK manca una configurazione obbligatoria.
È stata distribuita una versione difettosa nella rete CDN.
Per verificare la presenza di una configurazione difettosa, 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. Nel codice seguente viene illustrata una modifica di configurazione del frammento di codice di esempio.
Nota
Il supporto per l'inserimento di chiavi di strumentazione termina il 31 marzo 2025. L'inserimento della chiave di strumentazione continuerà a funzionare, ma non verranno più forniti aggiornamenti o supporto per la funzionalità. Vedere Transizione alle stringhe 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 ancora 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, il problema è probabilmente causato da un tipo non corrispondente o da un valore imprevisto. Avviare 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 di nuovo. Controllare quindi la documentazione per l'elemento che causa il problema. Se la documentazione non è chiara o se è necessaria assistenza, inviare un problema in GitHub.
La configurazione è stata distribuita e funzionante in precedenza, ma ora segnala questa eccezione? In questo caso, potrebbe esserci un problema che interessa una versione appena distribuita. Controllare se l'eccezione interessa solo un piccolo set di utenti o browser. Registrare 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, è consigliabile 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 la scheda Console . Eventuali errori segnalati devono essere autoesplicativi. Se è necessaria ulteriore assistenza, creare 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>
Nota
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 di loggingLevelConsole impostazione è maggiore di zero).
Se l'SDK non viene ancora inizializzato, provare ad abilitare l'impostazione di configurazione enableDebug. Dopo aver effettuato 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'errore dell'SDK. Usare la versione non ricordata 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 di configurazione del frammento di codice di esempio.
Avviso
Questa impostazione di solo sviluppatore non deve mai essere abilitata in un ambiente di produzione completo perché in questo modo si perde la 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 presentare un problema in GitHub fornendo i dettagli e un sito di esempio, se ne si usa uno. Includere i dettagli della versione del browser, del sistema operativo e 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 viene bloccato pubblicamente e i consumer di questi elenchi iniziano a bloccare tutto l'accesso.
Per risolvere questo problema, il proprietario dell'endpoint della rete CDN deve usare l'entità blocklisting che ha contrassegnato l'endpoint come non sicuro. L'entità blocklisting può quindi rimuovere l'endpoint dall'elenco pertinente.
Controllare i siti Web di sicurezza Internet seguenti 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. La quantità totale di tempo necessaria 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 è identificato come non sicuro, creare un ticket di supporto per risolvere il problema il prima possibile.
Le sezioni seguenti illustrano in modo più specifico come 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
Configurato 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 intrapreso una delle azioni di configurazione elencate, collaborare con loro (o fornire la documentazione) per consentire gli endpoint della rete CDN.
È possibile che gli utenti abbiano installato plug-in che usano l'elenco di blocchi pubblici. In caso contrario, probabilmente usano un'altra soluzione configurata manualmente oppure i plug-in usano 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 delle eccezioni del plug-in o del firewall 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, il firewall aziendale è probabilmente l'origine del blocco della rete CDN. Il reparto IT aziendale ha probabilmente implementato una qualche 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 includendoli (o rimuovendoli) in qualsiasi servizio di blocco o elenco di autorizzazioni del dominio.
Soluzione 4b2: ospitare l'SDK nella propria rete CDN
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à 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 all'installazione basata su npm della pagina GitHub di Application Insights JavaScript SDK.
Nota
Quando si usano pacchetti npm, è consigliabile usare anche una forma di bundler JavaScript per semplificare la suddivisione e la minificazione 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 implementare qualcosa di simile alla logica nel frammento per rilevare e segnalare questi problemi.
Risolvere i problemi relativi al supporto della mappa di origine per le applicazioni JavaScript
La tabella seguente illustra alcuni problemi che riguardano 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 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 "Fare clic sulle righe dell'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 il seguente avviso di telemetria: "Fare clic su Righe di evento senza valore parentId".
Causa
Questo problema può verificarsi se l'ID padre non è specificato nell'elemento HTML padre. Questa condizione causa l'attivazione dell'evento 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.
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per