SDK JavaScript Application Insights Microsoft Azure Monitor

Le kit de développement logiciel (SDK) JavaScript Microsoft Azure Monitor Application Insights vous permet de surveiller et d’analyser les performances des applications web JavaScript.

Prérequis

• Un abonnement Azure : Créer un abonnement Azure gratuitement
• Ressource Application Insights : Créer une ressource Application Insights
• Une application qui utilise JavaScript

Bien démarrer

Le kit de développement logiciel (SDK) JavaScript Application Insights est implémenté avec un extrait de code d’exécution pour une analytique web prête à l’emploi.

Activer le SDK Application Insights pour JavaScript

L’activation du SDK Application Insights pour JavaScript se fait en seulement deux étapes.

Ajouter l’extrait de code

Ajoutez l’extrait de code suivant au début de chaque balise pour chaque page HTML que vous souhaitez surveiller.

<script type="text/javascript">
!function(T,l,y){var S=T.location,k="script",D="instrumentationKey",C="ingestionendpoint",I="disableExceptionTracking",E="ai.device.",b="toLowerCase",w="crossOrigin",N="POST",e="appInsightsSDK",t=y.name||"appInsights";(y.name||T[e])&&(T[e]=t);var n=T[t]||function(d){var g=!1,f=!1,m={initialize:!0,queue:[],sv:"5",version:2,config:d};function v(e,t){var n={},a="Browser";return n[E+"id"]=a[b](),n[E+"type"]=a,n["ai.operation.name"]=S&&S.pathname||"_unknown_",n["ai.internal.sdkVersion"]="javascript:snippet_"+(m.sv||m.version),{time:function(){var e=new Date;function t(e){var t=""+e;return 1===t.length&&(t="0"+t),t}return e.getUTCFullYear()+"-"+t(1+e.getUTCMonth())+"-"+t(e.getUTCDate())+"T"+t(e.getUTCHours())+":"+t(e.getUTCMinutes())+":"+t(e.getUTCSeconds())+"."+((e.getUTCMilliseconds()/1e3).toFixed(3)+"").slice(2,5)+"Z"}(),iKey:e,name:"Microsoft.ApplicationInsights."+e.replace(/-/g,"")+"."+t,sampleRate:100,tags:n,data:{baseData:{ver:2}}}}var h=d.url||y.src;if(h){function a(e){var t,n,a,i,r,o,s,c,u,p,l;g=!0,m.queue=[],f||(f=!0,t=h,s=function(){var e={},t=d.connectionString;if(t)for(var n=t.split(";"),a=0;a<n.length;a++){var i=n[a].split("=");2===i.length&&(e[i[0][b]()]=i[1])}if(!e[C]){var r=e.endpointsuffix,o=r?e.location:null;e[C]="https://"+(o?o+".":"")+"dc."+(r||"services.visualstudio.com")}return e}(),c=s[D]||d[D]||"",u=s[C],p=u?u+"/v2/track":d.endpointUrl,(l=[]).push((n="SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)",a=t,i=p,(o=(r=v(c,"Exception")).data).baseType="ExceptionData",o.baseData.exceptions=[{typeName:"SDKLoadFailed",message:n.replace(/\./g,"-"),hasFullStack:!1,stack:n+"\nSnippet failed to load ["+a+"] -- Telemetry is disabled\nHelp Link: https://go.microsoft.com/fwlink/?linkid=2128109\nHost: "+(S&&S.pathname||"_unknown_")+"\nEndpoint: "+i,parsedStack:[]}],r)),l.push(function(e,t,n,a){var i=v(c,"Message"),r=i.data;r.baseType="MessageData";var o=r.baseData;return o.message='AI (Internal): 99 message:"'+("SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details) ("+n+")").replace(/\"/g,"")+'"',o.properties={endpoint:a},i}(0,0,t,p)),function(e,t){if(JSON){var n=T.fetch;if(n&&!y.useXhr)n(t,{method:N,body:JSON.stringify(e),mode:"cors"});else if(XMLHttpRequest){var a=new XMLHttpRequest;a.open(N,t),a.setRequestHeader("Content-type","application/json"),a.send(JSON.stringify(e))}}}(l,p))}function i(e,t){f||setTimeout(function(){!t&&m.core||a()},500)}var e=function(){var n=l.createElement(k);n.src=h;var e=y[w];return!e&&""!==e||"undefined"==n[w]||(n[w]=e),n.onload=i,n.onerror=a,n.onreadystatechange=function(e,t){"loaded"!==n.readyState&&"complete"!==n.readyState||i(0,t)},n}();y.ld<0?l.getElementsByTagName("head")[0].appendChild(e):setTimeout(function(){l.getElementsByTagName(k)[0].parentNode.appendChild(e)},y.ld||0)}try{m.cookie=l.cookie}catch(p){}function t(e){for(;e.length;)!function(t){m[t]=function(){var e=arguments;g||m.queue.push(function(){m[t].apply(m,e)})}}(e.pop())}var n="track",r="TrackPage",o="TrackEvent";t([n+"Event",n+"PageView",n+"Exception",n+"Trace",n+"DependencyData",n+"Metric",n+"PageViewPerformance","start"+r,"stop"+r,"start"+o,"stop"+o,"addTelemetryInitializer","setAuthenticatedUserContext","clearAuthenticatedUserContext","flush"]),m.SeverityLevel={Verbose:0,Information:1,Warning:2,Error:3,Critical:4};var s=(d.extensionConfig||{}).ApplicationInsightsAnalytics||{};if(!0!==d[I]&&!0!==s[I]){var c="onerror";t(["_"+c]);var u=T[c];T[c]=function(e,t,n,a,i){var r=u&&u(e,t,n,a,i);return!0!==r&&m["_"+c]({message:e,url:t,lineNumber:n,columnNumber:a,error:i}),r},d.autoExceptionInstrumented=!0}return m}(y.cfg);function a(){y.onInit&&y.onInit(n)}(T[t]=n).queue&&0===n.queue.length?(n.queue.push(a),n.trackPageView({})):a()}(window,document,{
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js", // The SDK URL Source
// name: "appInsights", // Global SDK Instance name defaults to "appInsights" when not supplied
// ld: 0, // Defines the load delay (in ms) before attempting to load the sdk. -1 = block page load and add to head. (default) = 0ms load after timeout,
// useXhr: 1, // Use XHR instead of fetch to report failures (if available),
crossOrigin: "anonymous", // When supplied this will add the provided value as the cross origin attribute on the script tag
// onInit: null, // Once the application insights instance has loaded and initialized this callback function will be called with 1 argument -- the sdk instance (DO NOT ADD anything to the sdk.queue -- As they won't get called)
cfg: { // Application Insights Configuration
    connectionString: "CONNECTION_STRING"
}});
</script>

Définir la chaîne de connexion

Une chaîne de connexion Application Insights contient des informations permettant de se connecter au cloud Azure et d’associer des données de télémétrie à une ressource Application Insights spécifique. La chaîne de connexion inclut la clé d’instrumentation (un identificateur unique), le suffixe de point de terminaison (pour spécifier le cloud Azure) et des points de terminaison explicites facultatifs pour les services individuels. La chaîne de connexion n’est pas considérée comme un jeton de sécurité ou une clé.

Dans l’extrait de code, remplacez l’espace réservé "CONNECTION_STRING" par votre chaîne de connexion réelle trouvée dans le Portail Azure.

1. Accédez au panneau Vue d’ensemble de votre ressource Application Insights.
2. Trouvez la chaîne de connexion.
3. Sélectionnez le bouton pour copier la chaîne de connexion dans le presse-papiers.

Configuration de l'extrait de code

Toute autre configuration d’extrait de code est facultative.

Nom	Type	Description
src	chaîne [obligatoire]	URL complète de l’emplacement à partir duquel charger le kit de développement logiciel (SDK). Cette valeur est utilisée pour l’attribut « src » d’une balise <script/> ajoutée dynamiquement. Vous pouvez utiliser l’emplacement de CDN public ou votre propre hébergement privé.
name	chaîne [facultatif]	Le nom global du kit de développement logiciel (SDK) initialisé est par défaut appInsights. window.appInsights est donc une référence à l’instance initialisée. Remarque : si vous affectez une valeur de nom ou si une instance précédente a été affectée au nom global appInsightsSDK, le code d’initialisation du kit de développement logiciel (SDK) veut que cette valeur se trouve dans l’espace de noms global en tant que window.appInsightsSDK=<name value> pour garantir un squelette d’extrait de code correct et que les méthodes de proxy sont initialisées et à jour.
ld	nombre en ms [facultatif]	Définit le délai de chargement avant de tenter de charger le kit de développement logiciel (SDK). La valeur par défaut est de 0 ms. Si vous utilisez une valeur négative, la balise de script est immédiatement ajoutée à la région de la page et bloque l’événement de chargement de page jusqu’à ce que le script soit chargé ou qu’il échoue.
useXhr	booléen [facultatif]	Ce paramètre est utilisé uniquement pour les échecs de chargement du kit de développement logiciel (SDK). La création de rapports tente d’abord d’utiliser la récupération fetch() si elle est disponible, puis de revenir à XHR, en définissant cette valeur sur « true » pour simplement ignorer la vérification de l’extraction. L’utilisation de cette valeur est requise uniquement si votre application est utilisée dans un environnement où la récupération (fetch) ne parviendrait pas à envoyer les événements d’échec.
crossOrigin	chaîne [facultatif]	Si vous incluez ce paramètre, la balise de script ajoutée pour télécharger le SDK inclut l’attribut crossOrigin avec cette valeur de chaîne. Lorsqu’il n’est pas défini (valeur par défaut), aucun attribut crossOrigin n’est ajouté. Les valeurs recommandées ne sont pas définies (valeur par défaut), "", ou "anonyme". (Pour toutes les valeurs valides, consultez la documentation Attribut HTML)
onInit	function(aiSdk) { ... } [facultatif]	Cette fonction de rappel est appelée après le chargement et l’initialisation du script SDK principal à partir du CDN (en fonction de la valeur SRC). Il a passé une référence à l’instance du SDK pour laquelle il est appelé et est également appelé avant la vue de page initiale. Si le SDK a déjà été chargé et initialisé, ce rappel est tout de même appelé. REMARQUE : pendant le traitement du tableau sdk.queue, ce rappel est appelé. Il vous est impossible d’ajouter d’autres éléments à la file d’attente, car ils sont ignorés et supprimés. (Ajouté dans le cadre de la version 5 de l’extrait de code – valeur sv : « 5 » dans le script d’extrait de code)
cfg	Objet [obligatoire]	La configuration est passée au Kit de développement logiciel (SDK) Application Insights pendant l’initialisation.

Exemple utilisant l’extrait de code sur le rappel onInit

<script type="text/javascript">
!function(T,l,y){<!-- Removed the Snippet code for brevity -->}(window,document,{
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
crossOrigin: "anonymous",
onInit: function (sdk) {
  sdk.addTelemetryInitializer(function (envelope) {
    envelope.data = envelope.data || {};
    envelope.data.someField = 'This item passed through my telemetry initializer';
  });
}, // Once the application insights instance has loaded and initialized this method will be called
cfg: { // Application Insights Configuration
    connectionString: "YOUR_CONNECTION_STRING"
}});
</script>

Qu’est-ce qui est automatiquement collecté ?

Lorsque vous activez le kit de développement logiciel (SDK) JavaScript App Insights, les classes de données suivantes sont automatiquement collectées :

• Exceptions non interceptées dans votre application, y compris des informations sur
  • Arborescence des appels de procédure
  • Détails de l’exception et message accompagnant l’erreur
  • Numéros de ligne et de colonne de l’erreur
  • URL où l’erreur a été générée
• Demandes de dépendance réseau effectuées par vos demandes XHR et Fetch d’application (la collection de recherches est désactivée par défaut), y compris des informations sur
  • URL de la source de dépendance
  • Commande et méthode utilisées pour demander la dépendance
  • Durée de la demande
  • Code de résultat et état de réussite de la demande
  • ID (le cas échéant) de l’utilisateur qui effectue la demande
  • Contexte de corrélation (le cas échéant) dans lequel la demande est effectuée
• Informations utilisateur (par exemple, emplacement, réseau, adresse IP)
• Informations sur l’appareil (par exemple, le navigateur, le système d’exploitation, la version, la langue ou le modèle)
• Informations de session

Notes

Pour certaines applications, telles que les applications monopage (SPA), la durée peut ne pas être enregistrée et sera définie par défaut sur 0.

Pour plus d’informations, consultez le lien suivant : https://github.com/MicrosoftDocs/azure-docs/blob/main/articles/azure-monitor/app/data-retention-privacy.md

Confirmer le déplacement des données

Vérifiez le flux de données en accédant au portail Azure puis à la ressource Application Insights pour laquelle vous avez activé le SDK. À partir de là, vous pouvez afficher les données dans les sections « Flux de métriques en direct » ou « Métriques ».

En outre, vous pouvez utiliser la méthode trackPageView() du SDK pour envoyer manuellement un événement d’affichage de page et vérifier qu’il apparaît dans le portail.

Si vous n’êtes pas en mesure d’exécuter l’application ou si vous n’obtenez pas les données prévues, consultez l’article de résolution des problèmes.

Analytics

Pour interroger vos données de télémétrie collectées par le kit SDK JavaScript, sélectionnez le bouton Voir dans les journaux (analytique) . En ajoutant une instruction where de client_Type == "Browser", vous verrez uniquement des données du SDK JavaScript. Toutes les données de télémétrie côté serveur collectées par d’autres SDK sont exclues.

// average pageView duration by name
let timeGrain=5m;
let dataset=pageViews
// additional filters can be applied here
| where timestamp > ago(1d)
| where client_Type == "Browser" ;
// calculate average pageView duration for all pageViews
dataset
| summarize avg(duration) by bin(timestamp, timeGrain)
| extend pageView='Overall'
// render result in a chart
| render timechart

Configuration avancée du SDK

Des informations supplémentaires sont disponibles pour les scénarios avancés suivants :

• SDK JavaScript npm setup
• Plug-in React
• Plug-in React natif
• Plug-in Angular
• Cliquez sur le plug-in Analytics

Forum aux questions

Quelle est la surcharge du SDK ou quelles sont ses performances ?

Le SDK JavaScript Application Insights présente une surcharge minimale sur votre site web. Avec seulement 36 Ko compressés avec gzip et mettant environ 15 ms seulement pour s’initialiser, le SDK ajoute un temps de chargement négligeable à votre site web. Les composants minimaux de la bibliothèque sont rapidement chargés lorsque vous utilisez le SDK, et le script complet est téléchargé en arrière-plan.

En outre, pendant le téléchargement du script à partir du CDN, tout le suivi de votre page est mis en file d’attente, de sorte que vous ne perdez aucune télémétrie pendant tout le cycle de vie de votre page. Ce processus de configuration fournit à votre page un système d’analyse transparent, invisible à vos utilisateurs.

Quels sont les navigateurs pris en charge ?

Chrome version la plus récente ✔	Firefox version la plus récente ✔	IE 9+ & Microsoft Edge ✔ Compatible à IE 8	Opera version la plus récente ✔	Safari version la plus récente ✔

Où puis-je trouver des exemples de code ?

Pour obtenir des exemples exécutables, consultez Exemples du SDK JavaScript Application Insights.

Comment puis-je mettre à niveau à partir de l’ancienne version d’Application Insights ?

Pour plus d’informations, consultez Mise à jour à partir d’anciennes versions du kit de développement logiciel (SDK) JavaScript Application Insights.

Quelle est la compatibilité ES3/Internet Explorer 8 ?

Nous devons prendre les mesures nécessaires pour s’assurer que ce SDK continue à « fonctionner » et n’interrompt pas l’exécution de JavaScript lorsqu’il est chargé par un navigateur plus ancien. Il serait idéal de ne pas prendre en charge les navigateurs plus anciens, mais de nombreux clients importants ne peuvent pas contrôler le navigateur que leurs utilisateurs choisissent d’utiliser.

Cela ne signifie pas que nous ne prenons en charge que l’ensemble commun de fonctionnalités les plus faibles. Nous devons maintenir la compatibilité du code ES3. De nouvelles fonctionnalités doivent être ajoutées de manière à ce qu’elles n’empêchent pas l’analyse JavaScript ES3 et n’aient pas été ajoutées en tant que fonctionnalité facultative.

Pour plus d’informations sur la prise en charge d’Internet Explorer 8, consultez GitHub.

Le SDK Application Insights est-il en open source ?

Oui, le SDK JavaScript Application Insights est en open source. Pour voir le code source ou contribuer au projet, consultez le référentiel officiel GitHub.

Comment mettre à jour ma configuration de serveur tiers ?

Le côté serveur doit être en mesure d’accepter les connexions avec ces en-têtes présents. Selon la configuration de Access-Control-Allow-Headers côté serveur, il est souvent nécessaire d’étendre la liste côté serveur en ajoutant manuellement Request-Id, Request-Context et traceparent (en-tête distribué W3C).

Access-Control-Allow-Headers : Request-Id, traceparent, Request-Context, <your header>

Comment désactiver le suivi distribué ?

Le suivi distribué peut être désactivé dans la configuration.

Résolution des problèmes

Consultez l’article sur la résolution des problèmes dédié.

Notes de publication

Des notes de publication détaillées concernant les mises à jour et les correctifs de bogues sont disponibles sur GitHub

Étapes suivantes

• Suivi de l'utilisation
• Mesures et événements personnalisés
• Développer-mesurer-apprendre
• Rubriques avancées du SDK JavaScript