Résolution des problèmes liés au 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 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 chargement du Kit de développement logiciel (SDK) spécifique pour les applications web JavaScript.
Symptômes
Dans l’élément <head> 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 sdk n’a pas été téléchargé ou initialisé :
Échec de chargement du KIT de développement logiciel (SDK) : Échec du chargement du script du KIT de développement logiciel (SDK) Application Insights (Pour plus d’informations, consultez pile)
Ce message indique que le client (navigateur) de l’utilisateur ne peut pas télécharger le Kit de développement logiciel (SDK) Application Insights ou l’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.
Remarque
Cette exception est prise en charge sur tous les principaux navigateurs 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 qui a été utilisée (et qui a échoué) pour télécharger le Kit de développement logiciel (SDK). |
| <Lien d’aide> | URL qui établit un lien vers la documentation de résolution des problèmes (cette page). |
| <URL de l’hôte> | URL complète de la page que l’utilisateur utilisait. |
| <URL du point de terminaison> | 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 intermittent de la connectivité réseau
Panne du réseau de distribution de contenu (CDN) Application Insights
Échec d’initialisation du KIT de développement logiciel (SDK) après le chargement du script
Blocage du CDN JavaScript Application Insights
L’échec intermittent de la connectivité réseau 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.
Remarque
Certaines de ces étapes supposent que votre application a un contrôle direct du script/de la 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 échecs intermittents de connectivité réseau, il y a moins de solutions possibles que pour d’autres causes. Toutefois, cette défaillance se résout généralement d’elle-même rapidement. Par exemple, si l’utilisateur actualise la page pour recharger votre site, les fichiers sont finalement 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 SDK, il n’a plus besoin de la télécharger à nouveau, car il réutilise la copie obtenue précédemment. (Voir fonctionnement de la mise en cache.) Si la mise en cache case activée échoue ou si 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 de « bruit » en arrière-plan dans le scénario d’échec case activée. 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 chargement du SDK est-elle persistante et se produit-elle pour de nombreux utilisateurs avec une réduction des données de télémétrie client normales ? Dans ce cas, les problèmes de connectivité réseau intermittentes ne sont probablement pas la véritable cause du problème, et vous devez explorer d’autres causes possibles.
Remarque
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, il est peu probable que l’hébergement du KIT de développement logiciel (SDK) sur votre propre CDN fournisse ou réduise 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 analysé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 à se 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 supervisée dans un bundle unique. Bien qu’un échec d’intermittence puisse toujours se produire 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 y a une panne d’Application Insights CDN, 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’y 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 organization 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 SDK n’a pas été initialisé après le chargement du script
Si le Kit de développement logiciel (SDK) ne s’initialise pas, le <script /> est toujours téléchargé avec succès à partir du CDN, mais il échoue lors de l’initialisation. Cet échec se produit en raison de dépendances manquantes ou non valides, ou 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 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, case activée pour 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 sdk n’a pas été téléchargé avec succès, consultez le tableau suivant pour comprendre les différentes options de création de rapports.
| Scénario | Cause | Action |
|---|---|---|
| Le problème affecte seulement quelques utilisateurs et une version de navigateur spécifique 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 des 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 tous vos utilisateurs. | Il s’agit d’un problème lié à la mise en production. | Créez un ticket de support. |
Si le SDK a été téléchargé avec succès, consultez les sections suivantes pour vous aider à 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 case activée 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 passée au KIT de développement logiciel (SDK) contient une configuration inattendue.
La configuration transmise au KIT de développement logiciel (SDK) ne dispose pas d’une configuration requise.
Une version défectueuse a été déployée sur le CDN.
Pour case activée d’une configuration défectueuse, modifiez la configuration passée à l’extrait de code (si vous ne l’avez pas déjà fait) afin qu’elle inclue uniquement votre clé d’instrumentation sous forme de valeur de chaîne. Le code suivant montre un exemple de modification de configuration d’extrait de code.
Remarque
La prise en charge de l’ingestion des clés d’instrumentation prend fin le 31 mars 2025. L’ingestion des clés d’instrumentation continuera de fonctionner, mais nous ne fournirons plus de mises à jour ni de prise en charge de la fonctionnalité. Consultez Transition vers des chaînes 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 la résolution des problèmes en restaurant vos options de configuration une par une, puis testez après chaque modification jusqu’à ce que l’exception se reproduise. Ensuite, case activée la documentation de l’élément à l’origine du problème. Si la documentation n’est pas claire ou si vous avez besoin d’aide, créez un problème sur GitHub.
Votre configuration a-t-elle déjà été déployée et opérationnelle, mais signale maintenant 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 n’affecte qu’un petit ensemble d’utilisateurs ou de navigateurs. Créez 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 n’a été levée, vous devez activer le débogage de la console en ajoutant le paramètre loggingLevelConsole à la configuration, comme indiqué dans l’exemple de configuration d’extrait de code suivant. Cette modification envoie toutes les erreurs et avertissements d’initialisation à la console du navigateur. (Pour afficher la console du navigateur, sélectionnez F12 pour ouvrir les outils de développement, puis sélectionnez l’onglet Console .) Toutes les erreurs signalées doivent être explicites. Si vous avez besoin d’aide supplémentaire, créez 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>
Remarque
Lors de l’initialisation, le KIT de développement logiciel (SDK) effectue des vérifications de base pour les dépendances majeures 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 du loggingLevelConsole paramètre est supérieure à zéro).
Si le SDK ne s’initialise toujours pas, 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 télémétrie. Étant donné que ce paramètre est destiné uniquement aux développeurs, il entraîne probablement la levée d’exceptions supplémentaires en raison de vérifications internes. Passez en revue chaque exception pour déterminer le problème à l’origine de l’échec du SDK. Utilisez la version nonminifiée du script (en remplaçant l’extension de nom de fichier .min.js par juste.js). Sinon, les exceptions sont illisibles. Le code suivant montre l’exemple de modifications de configuration de l’extrait de code.
Avertissement
Ce paramètre développeur uniquement ne doit JAMAIs être activé dans un environnement de production complet, car cela vous fait 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 déposer un problème sur GitHub en fournissant les détails et un exemple de site, le cas échéant. Incluez les détails de la version du navigateur, du système d’exploitation et 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 du SDK 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 tous les accès.
Pour résoudre ce problème, le propriétaire du point de terminaison CDN doit travailler avec l’entité de liste de blocage 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.
Consultez les sites web de sécurité Internet suivants pour savoir s’ils identifient le point de terminaison CDN comme étant dangereux :
La résolution de ce problème peut prendre beaucoup de temps. Les utilisateurs ou les services informatiques de l’entreprise peuvent être amenés à 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 spécifiquement comment un blocage peut se produire et comment résoudre 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 interdiction des points de terminaison CDN Application Insights dans leur navigateur ou proxy
Configuration d’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 blocage 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 blocage 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 blocage de domaine privé.
Demandez à 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 plug-in ou de règle de pare-feu 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
Importante
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. Demander au service informatique de configurer les points de terminaison CDN Application Insights pour le téléchargement en les incluant (ou en les supprimant) dans n’importe quel service de liste verte ou de liste verte de domaine.
Solution 4b2 : Héberger le Kit de développement logiciel (SDK) sur votre propre CDN
Au lieu de faire en sorte que les utilisateurs téléchargent le Kit de développement logiciel (SDK) Application Insights à partir du CDN public, vous pouvez héberger le SDK Application Insights sur votre propre point de terminaison CDN. Nous vous recommandons d’utiliser une version spécifique (ai.2.#.#.min.js) du SDK pour faciliter l’identification de la version que vous utilisez. En outre, mettez régulièrement à jour le Kit de développement logiciel (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 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 Configuration basée sur npm de la page GitHub du Kit de développement logiciel (SDK) JavaScript Application Insights.
Remarque
Lorsque vous utilisez des packages npm, nous vous recommandons d’utiliser également une forme de bundler JavaScript pour vous aider à fractionner et à réduire le 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 l’utilisation des packages npm du SDK). En fonction de votre application, de vos utilisateurs et de votre infrastructure, vous pouvez envisager d’implémenter quelque chose de similaire à la logique dans 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 décrit certains problèmes qui impliquent la prise en charge de la carte source pour les applications JavaScript, et propose des stratégies pour aider à résoudre ces problèmes.
| Problème | Description |
|---|---|
| Paramètres de contrôle d’accès en fonction du rôle Azure (Azure RBAC) requis sur votre conteneur d’objets blob | Tout utilisateur du portail qui utilise cette fonctionnalité doit se voir attribuer au moins un rôle Lecteur de données Blob du 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éé, ce rôle n’a peut-être pas été automatiquement attribué à vous ou à votre équipe. |
| Carte 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 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 provoque le déclenchement de l’événement sur tous ses éléments parents.
Solution
Pour résoudre ce problème, ajoutez l’attribut data-parentid ou data-<customPrefix>-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">
Étapes suivantes
- Obtenir de l’aide supplémentaire en signalant 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.