Résolution des problèmes du Kit de développement logiciel (SDK) JavaScript Application Insights
Cet article explique comment résoudre différents problèmes qui impliquent le Kit de développement logiciel (SDK) JavaScript Application Insights. Les sujets de cet article incluent l’échec de chargement du Kit de développement logiciel (SDK) pour les applications web JavaScript et la prise en charge de la carte source pour les applications JavaScript.
Résoudre les problèmes de chargement du Kit de développement logiciel (SDK) pour les applications web JavaScript
Les sections suivantes décrivent les symptômes, les causes et les solutions d’un scénario d’échec de charge spécifique pour les applications web JavaScript.
Symptômes
Dans l’élément <principal> de la page web que vous surveillez, l’extrait de code JavaScript (version 3 ou ultérieure) crée et signale l’exception suivante lorsqu’il détecte que le script du Kit de développement logiciel (SDK) n’a pas téléchargé ou initialisé :
Échec de chargement du KIT SDK : échec du chargement du script sdk Application Insights (consultez la pile pour plus d’informations)
Ce message indique que le client de l’utilisateur (navigateur) ne peut pas télécharger le Kit de développement logiciel (SDK) Application Insights ni initialiser à partir de la page d’hébergement identifiée. Par conséquent, vous ne voyez pas de données de télémétrie ou d’événements.
Note
Cette exception est prise en charge sur tous les navigateurs principaux qui prennent en charge l’API fetch() ou XMLHttpRequest. Ces versions de navigateur excluent Microsoft Internet Explorer 8 et versions antérieures. Par conséquent, ces navigateurs ne signalent pas ce type d’exception, sauf si votre environnement inclut un polyfill d’extraction.
Les détails de la pile incluent les informations de base sur les URL utilisées par l’utilisateur.
| Nom | Description |
|---|---|
| <Point de terminaison CDN> | URL utilisée (et qui a échoué) pour télécharger le Kit de développement logiciel (SDK). |
| <Lien d’aide> | URL qui renvoie à la documentation de résolution des problèmes (la présente page). |
| <URL de l’hôte> | URL complète de la page utilisée par l’utilisateur. |
| <URL du point de terminaison URL> | URL utilisée pour signaler l’exception. Cette valeur peut aider à déterminer si l’Internet public ou un cloud privé a accédé à la page d’hébergement. |
La liste suivante contient les raisons les plus courantes pour lesquelles cette exception se produit :
Échec de connectivité réseau intermittente
Panne de réseau de distribution de contenu Application Insights (CDN)
Échec d’initialisation du Kit de développement logiciel (SDK) après le chargement du script
Blocage du CDN JavaScript Application Insights
L’échec de connectivité réseau intermittente est la raison la plus courante de cette exception, en particulier dans les scénarios d’itinérance mobile.
Les sections suivantes expliquent comment résoudre chaque cause racine potentielle de cette erreur.
Note
Certaines de ces étapes supposent que votre application a un contrôle direct du script/>balise d’extrait <de code et de sa configuration retournée dans le cadre de la page HTML d’hébergement. Si ces conditions ne s’appliquent pas à votre scénario, ces étapes ne s’appliquent pas non plus.
Cause 1 : Échec de connectivité réseau intermittente
Si l’utilisateur rencontre des défaillances de connectivité réseau intermittente, il existe moins de solutions possibles que pour d’autres causes. Toutefois, cette défaillance se résout généralement rapidement. Par exemple, si l’utilisateur actualise la page pour recharger votre site, les fichiers sont éventuellement téléchargés et mis en cache localement jusqu’à la publication d’une version mise à jour.
Solution 1a : Télécharger une version mise à jour du Kit de développement logiciel (SDK)
Pour réduire l’échec de connectivité réseau intermittente, nous avons implémenté Cache-Control des en-têtes sur tous les fichiers CDN. Une fois que le navigateur de l’utilisateur a téléchargé la version actuelle du Kit de développement logiciel (SDK), il n’est pas obligé de le télécharger à nouveau, car il réutilise la copie obtenue précédemment. (Découvrez comment fonctionne la mise en cache.) Si la vérification de la mise en cache échoue ou qu’une nouvelle version est disponible, le navigateur de l’utilisateur doit télécharger la version mise à jour. Par conséquent, vous pouvez voir un niveau d’arrière-plan de « bruit » dans le scénario d’échec de vérification. Vous pouvez également voir un pic temporaire lorsqu’une nouvelle version se produit et devient en disponibilité générale (déployée sur le CDN).
Solution 1b : Utiliser des packages npm pour incorporer le Kit de développement logiciel (SDK) avec l’application dans un seul bundle
L’exception d’échec de charge du SDK persiste-t-elle et se produit-elle pour de nombreux utilisateurs avec une réduction de la télémétrie normale du client ? Dans ce cas, les problèmes de connectivité réseau intermittente ne sont probablement pas la véritable cause du problème, et vous devez explorer d’autres causes possibles.
Note
Une indication courante que cette défaillance se produit pour plusieurs utilisateurs est que l’exception est signalée à un niveau rapide et soutenu.
Dans ce cas, l’hébergement du Kit de développement logiciel (SDK) sur votre propre CDN est peu probable pour fournir ou réduire les occurrences de cette exception. Le même problème affecte votre propre CDN et il se produit également si vous utilisez le Kit de développement logiciel (SDK) via une solution de package npm. L’échec de ce dernier scénario se produit en particulier si Application Insights est inclus dans un bundle différent de celui de l’application surveillée, car l’échec est garanti dans au moins l’un de ces bundles. Du point de vue de l’utilisateur, lorsque cette exception se produit, l’ensemble de votre application ne parvient pas à charger ou à initialiser, pas seulement le SDK de télémétrie (que les utilisateurs ne voient pas). Par conséquent, les utilisateurs continueront probablement à actualiser votre site jusqu’à ce qu’il se charge complètement.
Vous pouvez essayer d’utiliser des packages npm pour incorporer le Kit de développement logiciel (SDK) Application Insights avec l’application surveillée dans un seul ensemble. Bien qu’un échec d’intermitence se produise toujours dans ce scénario, un bundle combiné offre une réelle chance de résoudre le problème.
Cause 2 : Panne du CDN Application Insights
Pour vérifier qu’il existe une panne CDN Application Insights, essayez d’accéder au point de terminaison CDN directement à partir du navigateur à partir d’un emplacement différent de celui de vos utilisateurs. Par exemple, vous pouvez essayer d’accéder à https://js.monitor.azure.com/scripts/b/ai.2.min.js partir de votre propre ordinateur de développement. (Cela suppose que votre organisation n’a pas bloqué ce domaine.)
Solution 2 : Créer un ticket de support
Si vous vérifiez qu’une panne existe, vous pouvez créer un ticket de support.
Cause 3 : Le Kit de développement logiciel (SDK) n’a pas été initialisé après le chargement du script
Si le Kit de développement logiciel (SDK) n’est pas initialisé, le <script /> est toujours téléchargé à partir du CDN, mais il échoue lors de l’initialisation. Cette défaillance se produit en raison de dépendances manquantes ou non valides, ou en raison d’une forme d’exception JavaScript.
Solution 3 : Rechercher un téléchargement réussi du KIT de développement logiciel (SDK) ou des exceptions JavaScript, ou activer le débogage du navigateur
Étape 1 : Rechercher un téléchargement réussi du Kit de développement logiciel (SDK)
Vérifiez si le Kit de développement logiciel (SDK) a été téléchargé avec succès. Si aucun téléchargement de script n’a eu lieu, ce scénario n’est pas la cause de l’exception d’échec de chargement du SDK. Utilisez un navigateur qui prend en charge les outils de développement. Sélectionnez F12 pour afficher les outils de développement, puis sélectionnez l’onglet Réseau. Vérifiez que le script défini dans la configuration de l’extrait de code src a été téléchargé. Pour ce faire, recherchez le code 200 de réponse (réussite) ou 304 (non modifié). Pour passer en revue le trafic réseau, vous pouvez également utiliser un outil de débogage web tel que Fiddler.
Si le Kit de développement logiciel (SDK) n’a pas été téléchargé avec succès, passez en revue le tableau suivant pour comprendre les différentes options de création de rapports.
| Scénario | Cause | Action |
|---|---|---|
| Le problème affecte uniquement quelques utilisateurs et une version spécifique du navigateur ou un sous-ensemble de versions de navigateur. (Vérifiez les détails de l’exception signalée.) | Le problème est probablement uniquement si des utilisateurs ou environnements spécifiques nécessitent que votre application fournisse des implémentations supplémentaires polyfill . |
Déposez un problème sur GitHub. |
| Le problème affecte l’ensemble de votre application et de tous vos utilisateurs. | Il s’agit d’un problème lié à la mise en production. | Créez un ticket de support. |
Si le Kit de développement logiciel (SDK) a été téléchargé avec succès, passez en revue les sections suivantes pour résoudre le problème d’initialisation du SDK.
Étape 2 : Rechercher les exceptions JavaScript
Recherchez les exceptions JavaScript. Utilisez un navigateur qui prend en charge les outils de développement. Sélectionnez F12 pour afficher les outils de développement, charger la page, puis vérifier si des exceptions se sont produites. Le script sdk (par exemple, dans ai.2.min.js) provoque-t-il des exceptions ? Dans ce cas, l’un des scénarios suivants s’est produit :
La configuration transmise au Kit de développement logiciel (SDK) contient une configuration inattendue.
La configuration transmise au Kit de développement logiciel (SDK) est manquante.
Une version défectueuse a été déployée sur le CDN.
Pour rechercher une configuration défectueuse, modifiez la configuration transmise à l’extrait de code (si vous ne l’avez pas déjà fait) afin qu’elle inclut uniquement votre clé d’instrumentation en tant que valeur de chaîne. Le code suivant montre un exemple de modification de configuration d’extrait de code.
Note
La prise en charge de l’ingestion de clé d’instrumentation se termine le 31 mars 2025. L’ingestion de clé d’instrumentation continuera de fonctionner, mais nous ne fournirons plus de mises à jour ni de support pour la fonctionnalité. Consultez Transition vers les chaîne de connexion pour tirer parti des nouvelles fonctionnalités.
<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
cfg: {
instrumentationKey: "<instrumentation-key-guid>"
}});
</script>
Lorsque vous utilisez cette configuration minimale, si vous voyez toujours une exception JavaScript dans le script sdk, créez un ticket de support. Pour résoudre le problème, vous devez restaurer la build défectueuse. Cela est dû au fait qu’une version nouvellement déployée est probablement la cause du problème.
Si l’exception disparaît, une incompatibilité de type ou une valeur inattendue est probablement à l’origine du problème. Commencez à résoudre les problèmes en restaurant vos options de configuration une par une, puis testez après chaque modification jusqu’à ce que l’exception se produise à nouveau. Ensuite, consultez la documentation de l’élément qui provoque le problème. Si la documentation n’est pas claire ou si vous avez besoin d’aide, déposez un problème sur GitHub.
Votre configuration a-t-elle déjà été déployée et fonctionne-t-elle, mais signale-t-elle cette exception ? Dans ce cas, il peut y avoir un problème qui affecte une version nouvellement déployée. Vérifiez si l’exception affecte uniquement un petit ensemble de vos utilisateurs ou navigateurs. Déposez un problème sur GitHub ou créez un ticket de support.
Étape 3 : Activer le débogage de la console du navigateur
Si aucune exception levée n’a eu lieu, vous devez activer le débogage de la console en ajoutant le paramètre loggingLevelConsole à la configuration, comme illustré dans l’exemple de configuration d’extrait de code suivant. Cette modification envoie toutes les erreurs d’initialisation et avertissements à la console du navigateur. (Pour afficher la console du navigateur, sélectionnez F12 pour ouvrir les outils de développement, puis sélectionnez le Onglet console .) Toutes les erreurs signalées doivent être explicites. Si vous avez besoin d’aide supplémentaire, déposez un problème sur 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
Lors de l’initialisation, le Kit de développement logiciel (SDK) effectue des vérifications de base pour les dépendances principales connues. Si le runtime actuel ne fournit pas ces vérifications, le runtime signale les échecs en tant que messages d’avertissement à la console (mais uniquement si la valeur de loggingLevelConsole paramètre est supérieure à zéro).
Si le Kit de développement logiciel (SDK) n’est toujours pas initialisé, essayez d’activer le paramètre de configuration enableDebug. Une fois cette modification effectuée, toutes les erreurs internes sont levées en tant qu’exceptions. Cela entraîne une perte de données de télémétrie. Étant donné que ce paramètre est destiné uniquement aux développeurs, il provoque probablement la levée d’autres exceptions en raison de vérifications internes. Passez en revue chaque exception pour déterminer quel problème provoque l’échec du Kit de développement logiciel (SDK). Utilisez la version nonminifiée du script (en modifiant l’extension de nom de fichier de .min.js en .js uniquement). Sinon, les exceptions ne sont pas lisibles. Le code suivant montre l’exemple de modification de la configuration de l’extrait de code.
Avertissement
Ce paramètre de développement uniquement ne doit JAMAIs être activé dans un environnement de production complet, car cela vous amène à perdre la télémétrie.
<script type="text/javascript">
...
src: "https://js.monitor.azure.com/scripts/b/ai.2.js",
cfg:{
instrumentationKey: "<instrumentation-key-guid>",
enableDebug: true
}});
</script>
Si cette action ne fournit toujours pas d’insights, vous devez émettre un problème sur GitHub en fournissant les détails et un exemple de site, si vous en utilisez un. Incluez la version du navigateur, le système d’exploitation et les détails de l’infrastructure JavaScript pour vous aider à identifier le problème.
Cause 4 : Blocage du CDN JavaScript Application Insights
Un blocage CDN est possible si un point de terminaison CDN JavaScript Application Insights est signalé ou identifié comme non sécurisé. Dans ce cas, le point de terminaison est publiquement bloqué et les consommateurs de ces listes commencent à bloquer tout accès.
Pour résoudre ce problème, le propriétaire du point de terminaison CDN doit travailler avec l’entité de mise en liste de blocs qui a marqué le point de terminaison comme non sécurisé. Ensuite, l’entité de liste de blocage peut supprimer le point de terminaison de la liste appropriée.
Vérifiez les sites web de sécurité Internet suivants pour savoir s’ils identifient le point de terminaison CDN comme non sécurisé :
La résolution de ce problème peut prendre beaucoup de temps. Les utilisateurs ou les services informatiques d’entreprise peuvent devoir forcer une mise à jour ou autoriser explicitement les points de terminaison CDN. La durée totale nécessaire pour résoudre ce problème dépend de la fréquence requise par l’application, le pare-feu ou l’environnement pour mettre à jour leurs copies locales des listes.
Si le point de terminaison CDN est identifié comme non sécurisé, créez un ticket de support pour résoudre le problème dès que possible.
Les sections suivantes décrivent plus précisément comment un blocage peut se produire et comment corriger le blocage.
Cause 4a : Blocage de l’utilisateur (navigateur, bloqueur installé ou pare-feu personnel)
Vérifiez si vos utilisateurs ont effectué l’une des actions de configuration suivantes :
Installé un plug-in de navigateur (généralement sous la forme d’une publicité, d’un programme malveillant ou d’un bloqueur de fenêtres contextuelles)
Blocage ou non autorisé des points de terminaison CDN Application Insights dans leur navigateur ou proxy
Configuré une règle de pare-feu qui provoque un blocage du domaine CDN pour le Kit de développement logiciel (SDK) (ou un échec de résolution de l’entrée DNS)
Solution 4a : Ajouter des exceptions de liste de blocs pour les points de terminaison CDN
Si vos utilisateurs ont effectué l’une des actions de configuration répertoriées, collaborez avec eux (ou fournissez de la documentation) pour autoriser les points de terminaison CDN.
Les utilisateurs peuvent avoir installé des plug-ins qui utilisent la liste de blocs publique. Si ce n’est pas le cas, ils utilisent probablement une autre solution configurée manuellement, ou les plug-ins utilisent une liste de blocs de domaine privé.
Indiquez à vos utilisateurs d’autoriser le téléchargement de scripts à partir des points de terminaison CDN Application Insights en incluant les points de terminaison dans la liste des exceptions de règle de pare-feu ou de plug-in de leur navigateur. Ces listes varient en fonction de l’environnement utilisateur.
Voici un exemple de cette situation qui montre comment configurer Google Chrome pour autoriser ou bloquer l’accès aux sites web.
Cause 4b : Blocage du pare-feu d’entreprise
Si vos utilisateurs se trouvent sur un réseau d’entreprise, le pare-feu d’entreprise est probablement la source du blocage CDN. Le service informatique de l’entreprise a probablement implémenté une forme de système de filtrage Internet.
Solution 4b1 : Ajouter des exceptions pour les points de terminaison CDN pour les entreprises
Important
Vos utilisateurs utilisent-ils un cloud privé et n’ont-ils pas accès à l’Internet public ? Dans ce cas, vous devez utiliser les packages npm Application Insights pour incorporer le Kit de développement logiciel (SDK) ou héberger le Kit de développement logiciel (SDK) Application Insights sur votre propre CDN.
Collaborez avec le service informatique de votre entreprise pour autoriser les règles nécessaires pour vos utilisateurs. Cette solution est similaire à l’ajout d’exceptions pour les utilisateurs. Le service informatique a configuré les points de terminaison CDN Application Insights à télécharger en les incluant (ou en supprimant) dans n’importe quel service de blocage de domaine ou de liste verte.
Solution 4b2 : Héberger le Kit de développement logiciel (SDK) sur votre propre CDN
Au lieu d’avoir des utilisateurs téléchargent le Kit de développement logiciel (SDK) Application Insights à partir du CDN public, vous pouvez héberger le Kit de développement logiciel (SDK) Application Insights sur votre propre point de terminaison CDN. Nous vous recommandons d’utiliser une version spécifique (ai.2.#.#.min.js) du Kit de développement logiciel (SDK) pour faciliter l’identification de la version que vous utilisez. Mettez également régulièrement à jour le SDK vers la version actuelle (ai.2.min.js) afin de pouvoir utiliser les correctifs de bogues et les nouvelles fonctionnalités qui deviennent disponibles.
Solution 4b3 : Utiliser des packages npm pour incorporer le Kit de développement logiciel (SDK) Application Insights
Au lieu d’utiliser l’extrait de code et d’ajouter des points de terminaison CDN publics, vous pouvez utiliser les packages npm pour inclure le Kit de développement logiciel (SDK) dans le cadre de vos propres fichiers JavaScript. Le Kit de développement logiciel (SDK) devient un autre package au sein de vos propres scripts. Pour plus d’informations, consultez la section de configuration basée sur npm de la page GitHub du Kit de développement logiciel (SDK) JavaScript Application Insights.
Note
Nous vous recommandons que lorsque vous utilisez des packages npm, vous devez également utiliser une forme d’bundler JavaScript pour vous aider à effectuer le fractionnement et la minification du code.
Comme avec l’extrait de code, les mêmes problèmes de blocage qui apparaissent ici peuvent affecter vos propres scripts (avec ou sans utiliser les packages npm du SDK). En fonction de votre application, de vos utilisateurs et de votre infrastructure, vous pouvez envisager d’implémenter quelque chose similaire à la logique de l’extrait de code pour détecter et signaler ces problèmes.
Résoudre les problèmes de prise en charge de la carte source pour les applications JavaScript
Le tableau suivant explique certains problèmes qui impliquent la prise en charge de la carte source pour les applications JavaScript et propose des stratégies pour résoudre ces problèmes.
| Problème | Description |
|---|---|
| Paramètres de contrôle d’accès en fonction du rôle Azure requis (Azure RBAC) sur votre conteneur d’objets blob | Tout utilisateur sur le portail qui utilise cette fonctionnalité doit être affecté au moins à un rôle lecteur de données blob de stockage pour votre conteneur d’objets blob. Vous devez attribuer ce rôle à toute personne qui souhaite utiliser les mappages sources via cette fonctionnalité. Selon la façon dont le conteneur a été créé, il est possible que ce rôle ne vous ait pas été attribué automatiquement, à vous ou à votre équipe. |
| Mappage de source introuvable | Pour résoudre ce problème, effectuez les actions suivantes :
|
Correction de l’avertissement « Click Event rows with no parentId value »
Lorsque vous utilisez Application Insights et le plug-in Click Analytics Auto Collection dans l’application, l’avertissement de télémétrie suivant peut apparaître dans le classeur Application Insights : « Cliquez sur les lignes d’événement sans valeur parentId ».
Cause
Ce problème peut se produire si l’ID parent n’est pas spécifié dans l’élément HTML parent. Cette condition entraîne le déclenchement de l’événement sur tous ses éléments parents.
Solution
Pour résoudre ce problème, ajoutez l’attribut ou data-<customPrefix>-parentid l’attribut data-parentid à l’élément HTML parent. Voici un exemple de code HTML :
<div data-heart-id="demo Header" data-heart-parentid="demo.Header" data-heart-parent-group="demo.Header.Group">
Prochaines étapes
- Obtenir de l’aide supplémentaire en plaçant un problème sur GitHub
- Surveiller l’utilisation des pages web
Exclusion de responsabilité de tiers
Les produits tiers mentionnés dans le présent article sont fabriqués par des sociétés indépendantes de Microsoft. Microsoft exclut toute garantie, implicite ou autre, concernant les performances ou la fiabilité de ces produits.
Contactez-nous pour obtenir de l’aide
Pour toute demande ou assistance, créez une demande de support ou posez une question au support de la communauté Azure. Vous pouvez également soumettre des commentaires sur les produits à la communauté de commentaires Azure.