Application Insights pour les pages web

Notes

Nous continuons d’évaluer la viabilité d’OpenTelemetry pour les scénarios de navigateur. Nous vous recommandons le Kit de développement logiciel (SDK) JavaScript Application Insights pour l’avenir proche. Il est entièrement compatible avec le suivi distribué OpenTelemetry.

Apprenez-en plus sur les performances et l’utilisation de votre page web ou de votre application. Si vous ajoutez Application Insights à votre script de page, vous obtenez le minutage des chargements de page et des appels AJAX, et le nombre et les détails des exceptions du navigateur et des échecs d’AJAX. Vous obtenez également le nombre d’utilisateurs et de sessions. Toutes ces données de télémétrie peuvent être segmentées par page, par version de système d’exploitation ou de navigateur client, par emplacement géographique et en fonction d’autres aspects. Vous pouvez définir des alertes en cas de dépassement d’un certain nombre d’échecs ou de ralentissement du chargement des pages. En insérant des suivis d’appel dans votre code JavaScript, vous pouvez suivre l’utilisation des différentes fonctionnalités de votre application de page web.

Application Insights peut être utilisé avec n’importe quelle page web en ajoutant un court extrait de code JavaScript. Node.js dispose d’un Kit de développement logiciel (SDK) autonome. Si votre service web est Java ou ASP.NET, vous pouvez utiliser les kits de développement logiciel (SDK) côté serveur conjointement au kit de développement logiciel (SDK) JavaScript côté client pour acquérir une compréhension de bout en bout des performances de votre application.

Ajouter le SDK JavaScript

  1. Tout d’abord, vous avez besoin d’une ressource Application Insights. Si vous ne disposez pas encore d’une ressource ni d’une chaîne de connexion, suivez les instructions pour créer une ressource.
  2. Copiez la chaîne de connexion de la ressource à laquelle vous souhaitez envoyer vos données de télémétrie JavaScript (de l’étape 1). Vous l’ajouterez au paramètre connectionString du kit de développement logiciel (SDK) JavaScript Application Insights.
  3. Ajoutez le kit SDK JavaScript Application Insights à votre page web ou à votre application via l’une des deux options suivantes :

Avertissement

@microsoft/applicationinsights-web-basic - AISKULight ne prend pas en charge l’utilisation de chaînes de connexion.

N’utilisez qu’une seule méthode pour ajouter le SDK JavaScript à votre application. Si vous utilisez l’installation npm, n’utilisez pas l’extrait de code, et inversement.

Notes

Le programme d’installation de npm installe le Kit de développement logiciel (SDK) JavaScript en tant que dépendance pour votre projet et active IntelliSense. L’extrait de code extrait le SDK au moment de l’exécution. Les deux prennent en charge les mêmes fonctionnalités. Les développeurs qui souhaitent des événements et une configuration plus personnalisés optent généralement pour le programme d’installation de npm. Les utilisateurs qui recherchent une activation rapide de l’analytique web prête à l’emploi optent pour l’extrait de code.

Configuration basée sur npm

Installez via NPM.

npm i --save @microsoft/applicationinsights-web

Notes

Les frappes sont incluses dans ce package. Vous n’avez donc pas besoin d’installer un package de types distinct.

import { ApplicationInsights } from '@microsoft/applicationinsights-web'

const appInsights = new ApplicationInsights({ config: {
  connectionString: 'Copy connection string from Application Insights Resource Overview'
  /* ...Other Configuration Options... */
} });
appInsights.loadAppInsights();
appInsights.trackPageView(); // Manually call trackPageView to establish the current user/session/pageview

Configuration basée sur un extrait de code

Si votre application n’utilise pas npm, vous pouvez directement instrumenter vos pages web avec Application Insights en collant cet extrait de code en haut de chacune de vos pages. Il est préférable que ce soit le premier script de votre section <head>. De cette façon, il peut surveiller les problèmes potentiels avec toutes vos dépendances et, éventuellement, toute erreur JavaScript. Si vous utilisez l’application Blazor Server, ajoutez l’extrait de code en haut du fichier _Host.cshtml, dans la section <head>.

À partir de la version 2.5.5, l’événement d’affichage de page inclura la nouvelle balise « ai.internal.snippet », qui contient la version d’extrait de code identifiée. Cette fonctionnalité permet de suivre la version de l’extrait de code que votre application utilise.

L’extrait de code actuel qui suit est la version « 5 ». La version est encodée dans l’extrait de code en tant que sv:"#". La version actuelle est également disponible sur GitHub.

<script type="text/javascript">
!function(T,l,y){var S=T.location,k="script",D="connectionString",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"}(),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: "Copy connection string from Application Insights Resource Overview"
    /* ...Other Configuration Options... */
}});
</script>

Notes

Pour des raisons de lisibilité et pour réduire les éventuelles erreurs JavaScript, toutes les options de configuration possibles sont énumérées sur une nouvelle ligne dans le code de l’extrait précédent. Si vous ne souhaitez pas modifier la valeur d’une ligne commentée, elle peut être supprimée.

Signaler des échecs de chargement de script

Cette version de l’extrait de code détecte et signale les défaillances lorsque le SDK est chargé à partir du CDN comme exception au portail Azure Monitor (dans le navigateur défaillances > exceptions >). L’exception offre de la visibilité sur les défaillances de ce type, afin que vous soyez conscient que votre application ne fournit pas de données de télémétrie (ou d’autres exceptions) comme prévu. Ce signal est une mesure importante pour comprendre que vous avez perdu la télémétrie, car le kit de développement logiciel (SDK) n’a pas pu charger ou s’initialiser, ce qui peut entraîner les conséquences suivantes :

  • Sous-évaluation de la manière dont les utilisateurs utilisent ou essaient d'utiliser votre site.
  • Données de télémétrie manquantes sur la façon dont vos utilisateurs finaux utilisent votre site.
  • Erreurs JavaScript manquantes qui pourraient potentiellement empêcher vos utilisateurs d’utiliser correctement votre site.

Pour plus d’informations sur cette exception, consultez la page de résolution des problèmes Échec du chargement du kit de développement logiciel.

Le signalement de cet échec en tant qu’exception au portail n’utilise pas l’option de configuration disableExceptionTracking de la configuration Application Insights. Pour cette raison, si cet échec se produit, il est toujours signalé par l’extrait de code, même lorsque la prise en charge de window.onerror est désactivée.

La création de rapports sur les échecs de chargement du kit de développement logiciel (SDK) n’est pas prise en charge sur Internet Explorer 8 ou version antérieure. Ce comportement réduit la taille minimisée de l’extrait de code en supposant que la plupart des environnements ne sont pas exclusivement IE 8 ou moins. Si vous avez cette exigence et que vous souhaitez recevoir ces exceptions, vous devez inclure une version Fetch de poly Fill ou créer votre propre extrait de code qui utilise XDomainRequest au lieu de XMLHttpRequest. Utilisez le code source de l’extrait fourni comme point de départ.

Notes

Si vous utilisez une version précédente de l’extrait de code, effectuez la mise à jour vers la dernière version afin que vous receviez ces problèmes précédemment non signalés.

Options de configuration de l’extrait de code

Toutes les options de configuration ont été déplacées vers la fin du script. Cela évite d’introduire accidentellement des erreurs JavaScript qui entraîneraient non seulement l’échec du chargement du kit de développement logiciel (SDK),mais également la désactivation de signalement de la défaillance.

Chaque option de configuration est indiquée ci-dessus sur une nouvelle ligne. Si vous ne souhaitez pas remplacer la valeur par défaut d’un élément répertorié comme [facultatif], vous pouvez supprimer cette ligne afin de réduire la taille de la page renvoyée.

Les options de configuration disponibles sont répertoriées dans ce tableau.

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 sera donc une référence à l’instance initialisée. Si vous fournissez une valeur de nom ou qu’une instance précédente semble attribuée (via le nom global appInsightsSDK), alors cette valeur de nom sera aussi définie dans l’espace de nom global comme window.appInsightsSDK=<name value>. Le code d’initialisation du kit de développement logiciel (SDK) utilise cette référence pour garantir l’initialisation et la mise à jour du squelette d’extrait de code et des méthodes proxy corrects.
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 0ms. Toute valeur négative ajoute immédiatement une balise de script à la région <d’en-tête> de la page. L’événement de chargement de page est ensuite bloqué jusqu’à ce que le script soit chargé ou échoue.
useXhr booléen [facultatif] Ce paramètre est utilisé uniquement pour les échecs de chargement du kit de développement logiciel (SDK). Le reporting essaiera d’abord d’utiliser fetch(), si disponible, et retombera alors sur XHR. La définition de cette valeur sur true contourne simplement la vérification d’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 kit de développement logiciel (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 "anonymous". Pour toutes les valeurs valides, consultez la documentation Attribut HTML : crossorigin.
cfg Objet [obligatoire] La configuration est passée au Kit de développement logiciel (SDK) Application Insights pendant l’initialisation.

Configuration de la chaîne de connexion

Notes

Le support de l’ingestion de clé d’instrumentation prendra fin 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é. Passez aux chaînes de connexion pour tirer parti des nouvelles fonctionnalités.

import { ApplicationInsights } from '@microsoft/applicationinsights-web'

const appInsights = new ApplicationInsights({ config: {
  connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE'
  /* ...Other Configuration Options... */
} });
appInsights.loadAppInsights();
appInsights.trackPageView();

Envoyer des données de télémétrie au portail Azure

Par défaut, le kit de développement logiciel (SDK) JavaScript Application Insights collecte automatiquement de nombreux éléments de télémétrie qui sont utiles pour déterminer l’intégrité de votre application et l’expérience utilisateur sous-jacente.

Cette télémétrie inclut les éléments suivants :

  • 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.
    • Nombre de lignes et de colonnes 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, navigateur, système d’exploitation, version, langue, modèle)
  • Informations de session

Initialiseurs de télémétrie

Les initialiseurs de télémétrie permettent de modifier le contenu des données de télémétrie collectées avant leur envoi à partir du navigateur de l’utilisateur. Ils peuvent également être utilisés pour empêcher l’envoi de certaines données de télémétrie, en retournant false. Plusieurs initialiseurs de télémétrie peuvent être ajoutés à votre instance d’Application Insights. Ils sont exécutés dans l’ordre d’ajout.

L’argument d’entrée pour addTelemetryInitializer est un rappel qui prend un ITelemetryItem comme argument et retourne boolean ou void. Si false est retourné, l’élément de télémétrie n’est pas envoyé, sinon il passe à l’initialiseur de télémétrie suivant, le cas échéant, ou il est envoyé au point de terminaison de collecte de données de télémétrie.

Voici un exemple d’utilisation des initialiseurs de télémétrie :

var telemetryInitializer = (envelope) => {
  envelope.data.someField = 'This item passed through my telemetry initializer';
};
appInsights.addTelemetryInitializer(telemetryInitializer);
appInsights.trackTrace({message: 'This message will use a telemetry initializer'});

appInsights.addTelemetryInitializer(() => false); // Nothing is sent after this is executed
appInsights.trackTrace({message: 'this message will not be sent'}); // Not sent

Configuration

La plupart des champs de configuration sont nommés de façon à pouvoir avoir la valeur false par défaut. Tous les champs sont facultatifs à l’exception de connectionString.

Nom Description Default
connectionString Obligatoire
chaîne de connexion que vous avez obtenue à partir du portail Azure.
string
null
accountId ID de compte facultatif, si votre application regroupe les utilisateurs dans des comptes. Aucun espace, virgule, point-virgule, signe d’égalité ni barre verticale. string
null
sessionRenewalMs Une session est consignée si l’utilisateur est inactif pendant ce laps de temps en millisecondes. numeric
1800000
(30 min)
sessionExpirationMs Une session est consignée si elle s’est poursuivie pendant ce laps de temps en millisecondes. numeric
86400000
(24 heures)
maxBatchSizeInBytes Taille maximale du lot de données de télémétrie. Si un lot dépasse cette limite, il est immédiatement envoyé et un nouveau lot est démarré. numeric
10000
maxBatchInterval Durée de mise en lot des données de télémétrie avant l’envoi (en millisecondes). numeric
15000
disable​ExceptionTracking Si la valeur est true, les exceptions ne sont pas collectées automatiquement. boolean
false
disableTelemetry Si la valeur est true, les données de télémétrie ne sont pas collectées ni envoyées. boolean
false
enableDebug Si la valeur est true, les données de débogage internes sont levées en tant qu’exception au lieu d’être consignées, quels que soient les paramètres de journalisation du kit SDK. La valeur par défaut est false.
Remarque : L’activation de ce paramètre entraîne la suppression de données de télémétrie chaque fois qu’une erreur interne se produit. Ce paramètre peut être utile pour identifier rapidement les problèmes liés à votre configuration ou utilisation du kit de développement logiciel (SDK). Pour ne pas perdre de données de télémétrie pendant le débogage, utilisez loggingLevelConsole ou loggingLevelTelemetry à la place de enableDebug.
boolean
false
loggingLevelConsole Consigne les erreurs internes d’Application Insights dans la console.
0 : désactivé,
1 : Erreurs critiques uniquement,
2 : Tout (erreurs et avertissements)
numeric
0
loggingLevelTelemetry Envoie les erreurs internes d’Application Insights en tant que données de télémétrie.
0 : désactivé,
1 : Erreurs critiques uniquement,
2 : Tout (erreurs et avertissements)
numeric
1
diagnosticLogInterval (interne) Intervalle d’interrogation (en ms) pour la file d’attente de journalisation interne. numeric
10000
samplingPercentage Pourcentage d’événements qui seront envoyés. La valeur par défaut est 100, ce qui signifie que tous les événements sont envoyés. Définissez cette option si vous souhaitez conserver votre plafond de données pour les applications à grande échelle. numeric
100
autoTrackPageVisitTime Si la valeur est true, sur une consultation de page, la durée d’affichage de la page instrumentée précédente fait l’objet d’un suivi et est envoyée en tant que données de télémétrie, et un nouveau minuteur est démarré pour la consultation de page en cours. Elle est envoyée sous la forme d’une mesure personnalisée nommée PageVisitTime dans milliseconds et est calculée via la fonction Date now() (si elle est disponible) et se replie sur (new Date()).getTime() si now() n’est pas disponible (Internet Explorer 8 ou moins). La valeur par défaut est false. boolean
false
disableAjaxTracking Si la valeur est true, les appels Ajax ne sont pas collectés automatiquement. boolean
false
disableFetchTracking Si la valeur est true, les requêtes Fetch ne sont pas collectées automatiquement. boolean
false
overridePageViewDuration Si la valeur est true, le comportement par défaut de trackPageView est modifié pour enregistrer la fin de l’intervalle de durée de consultation de page lorsque trackPageView est appelé. Si la valeur est false et qu’aucune durée personnalisée n’est fournie à trackPageView, les performances d’affichage de la page sont calculées à l’aide de l’API de minutage de la navigation. boolean
maxAjaxCallsPerView Valeur par défaut 500 contrôle le nombre d’appels Ajax qui seront supervisés par affichage de page. Affectez la valeur -1 pour superviser tous les appels Ajax (illimités) dans la page. numeric
500
disableDataLossAnalysis Si la valeur est false, les mémoires tampons d’expéditeur de données de télémétrie internes sont vérifiées au démarrage à la recherche d’éléments qui n’ont pas encore été envoyés. boolean
true
disable​CorrelationHeaders Si la valeur est false, le kit SDK ajoute deux en-têtes (Request-Id et Request-Context) à toutes les demandes de dépendance pour les mettre en corrélation avec les demandes correspondantes côté serveur. boolean
false
correlationHeader​ExcludedDomains Désactiver les en-têtes de corrélation pour des domaines spécifiques. string[]
non défini
correlationHeader​ExcludePatterns Désactiver les en-têtes de corrélation à l’aide d’expressions régulières. regex[]
non défini
correlationHeader​Domains Activer les en-têtes de corrélation pour des domaines spécifiques. string[]
non défini
disableFlush​OnBeforeUnload Si la valeur est true, la méthode Flush n’est pas appelée lorsque l’événement onBeforeUnload est déclenché. boolean
false
enableSessionStorageBuffer Si la valeur est true, la mémoire tampon contenant toutes les données de télémétrie non envoyées est stockée dans le stockage de session. La mémoire tampon est restaurée lors du chargement de la page. boolean
true
cookieCfg Par défaut, l’utilisation des cookies est activée. Pour obtenir les valeurs par défaut complètes, consultez les paramètres ICookieCfgConfig. ICookieCfgConfig
(Depuis 2.6.0)
non défini
isCookieUseDisabled
disableCookiesUsage
Si la valeur est true, le kit de développement logiciel (SDK) ne stocke pas ou ne lit pas les données des cookies. Désactive les cookies d’utilisateur et de session et rend les panneaux et les expériences d’utilisation inutiles. isCookieUseDisable est déprécié en faveur de disableCookiesUsage. Quand les deux sont fournis, disableCookiesUsage a la priorité.
(Depuis v2.6.0) Et si cookieCfg.enabled est également défini, il est prioritaire sur ces valeurs. L’utilisation des cookies peut être réactivé après l’initialisation via core.getCookieMgr().setEnabled(true).
Alias pour cookieCfg.enabled.
false
cookieDomain Domaine de cookie personnalisé. Cette option est utile si vous souhaitez partager des cookies Application Insights entre les sous-domaines.
(Depuis v2.6.0) Si cookieCfg.domain est défini, il est prioritaire sur cette valeur.
Alias pour cookieCfg.domain.
null
cookiePath Personnalisez le chemin d’accès du cookie. Cette option est utile si vous souhaitez partager des cookies Application Insights derrière une passerelle d’application.
Si cookieCfg.path est défini, il est prioritaire sur cette valeur.
Alias pour cookieCfg.path.
(Depuis 2.6.0)
null
isRetryDisabled Si la valeur est false, réessayez avec 206 (succès partiel), 408 (délai d’expiration), 429 (trop de requêtes), 500 (erreur de serveur interne), 503 (service non disponible) et 0 (hors connexion, uniquement si détecté). boolean
false
isStorageUseDisabled Si la valeur est true, le kit de développement logiciel (SDK) ne stocke pas ou ne lit pas les données à partir du stockage local et de session. boolean
false
isBeaconApiDisabled Si la valeur est false, le kit SDK envoie toutes les données de télémétrie à l’aide de l’API Beacon. boolean
true
onunloadDisableBeacon Quand l’onglet est fermé, le kit SDK envoie toutes les données de télémétrie restantes à l’aide de l’API Beacon. boolean
false
sdkExtension Définit le nom de l’extension du kit SDK. Seuls les caractères alphabétiques sont autorisés. Le nom de l’extension est ajouté comme préfixe à la balise ai.internal.sdkVersion (par exemple, ext_javascript:2.0.0). string
null
isBrowserLink​TrackingEnabled Si la valeur est true, le kit SDK effectue le suivi de toutes les demandes de lien de navigateur. boolean
false
appId AppId est utilisé pour la corrélation entre les dépendances AJAX qui se produisent côté client avec les demandes côté serveur. Lorsque l’API Beacon est activée, elle ne peut pas être utilisée automatiquement, mais peut être définie manuellement dans la configuration. string
null
enable​CorsCorrelation Si la valeur est true, le kit SDK ajoute deux en-têtes (Request-Id et Request-Context) à toutes les demandes CORS pour mettre en corrélation les dépendances AJAX sortantes avec les demandes correspondantes côté serveur. boolean
false
namePrefix Valeur facultative qui sera utilisée comme suffixe de nom pour localStorage et le nom du cookie. string
non défini
enable​AutoRoute​Tracking Effectuer le suivi automatique des modifications de route dans les applications monopages. Si la valeur est true, chaque modification de route envoie un nouvelle consultation de page à Application Insights. Les modifications des routes de hachage (example.com/foo#bar) sont également enregistrées en tant que nouveaux affichages de page. boolean
false
enableRequest​HeaderTracking Si la valeur est true, les en-têtes de requête AJAX et Fetch sont suivis. boolean
false
enableResponse​HeaderTracking Si la valeur est true, les en-têtes de réponse de requête AJAX et Fetch sont suivis. boolean
false
distributedTracingMode Définit le mode de traçage distribué. Si le mode AI_AND_W3C ou le mode W3C sont définis, les en-têtes de contexte de trace W3C (traceparent/tracestate) sont générés et inclus dans toutes les demandes sortantes. AI_AND_W3C est fourni à des fins de compatibilité descendante avec tous les services instrumentés Application Insights hérités. Consultez des exemples sur ce site web. DistributedTracingModesou
numeric
(Depuis v2.6.0) DistributedTracingModes.AI_AND_W3C
(v2.5.11 ou version antérieure) DistributedTracingModes.AI
enable​AjaxErrorStatusText Si la valeur est true, inclure le texte des données d’erreur de réponse dans l’événement de dépendance sur les demandes AJAX ayant échoué. boolean
false
enable​AjaxPerfTracking Indicateur pour activer la recherche et l’inclusion de minutages supplémentaires de window.performance du navigateur dans les métriques ajax (XHR et fetch) signalées. boolean
false
maxAjaxPerf​LookupAttempts Nombre maximal de fois où rechercher les minutages window.performance, si disponibles. Cette option est parfois nécessaire, car tous les navigateurs ne remplissent pas la fenêtre de performances avant de signaler la fin de la requête XHR. Pour les requêtes d’extraction, cette opération est ajoutée une fois terminée. numeric
3
ajaxPerfLookupDelay Délai d’attente avant la nouvelle tentative de recherche de minutages de window.performance pour une requête ajax. La durée est en millisecondes et est transmise directement à setTimeout(). numeric
25 ms
enableUnhandled​PromiseRejection​Tracking Si la valeur est true, les rejets de promesse non gérés sont collectés et signalés comme une erreur JavaScript. Quand disableExceptionTracking a la valeur true (ne pas suivre les exceptions), la valeur de configuration est ignorée et les rejets de promesse non gérés ne sont pas signalés. boolean
false
enablePerfMgr Quand cette option est activée (true), elle crée des perfEvents locaux pour le code qui a été instrumenté pour émettre perfEvents (via l’assistance doPerf ()). Elle peut être utilisée pour identifier les problèmes de performances dans le kit de développement logiciel (SDK) en fonction de votre utilisation ou éventuellement dans votre propre code instrumenté. Pour plus d’informations, consultez la documentation de base. Depuis v2.5.7 boolean
false
perfEvtsSendAll Quand enablePerfMgr est activé et que IPerfManager déclenche un INotificationManager.perfEvent (), cet indicateur détermine si un événement est déclenché (et envoyé à tous les écouteurs) pour tous les événements (true) ou uniquement pour les événements parents (false <par défaut>).
Un IPerfEvent parent est un événement où aucun autre IPerfEvent n’est encore en cours d’exécution au moment de la création de cet événement et sa propriété parente n’a pas la valeur null ou n’est pas définie. Depuis v2.5.7
boolean
false
idLength La longueur par défaut utilisée pour générer de nouvelles valeurs d’ID d’utilisateur et de session aléatoires. La valeur par défaut est 22. La valeur par défaut précédente était 5 (v2.5.8 ou moins). Sivous avez besoin de conserver la longueur maximale précédente, vous devez définir cette valeur sur 5. numeric
22

Depuis la version 2.6.0, la gestion des cookies est désormais disponible directement à partir de l’instance et peut être désactivée et réactivée après l’initialisation.

Si elle est désactivée pendant l’initialisation via les configurations disableCookiesUsage ou cookieCfg.enabled, vous pouvez maintenant la réactiver via la fonction ICookieMgrsetEnabled.

La gestion des cookies basée sur une instance remplace également les fonctions globales CoreUtils précédentes de disableCookies(), setCookie(...)getCookie(...) et deleteCookie(...). Pour bénéficier des améliorations apportées à l’arborescence, également introduites dans le cadre de la version 2.6.0, vous ne devez plus utiliser les fonctions globales.

ICookieMgrConfig

Configuration de cookie pour la gestion des cookies basée sur une instance ajoutée dans la version 2.6.0.

Nom Description Type et valeur par défaut
enabled Une valeur booléenne indique si l’utilisation de cookies par le Kit de développement logiciel (SDK) est activée par l’instance actuelle. Si la valeur est false, l’instance du kit de développement logiciel (SDK) initialisée par cette configuration ne stocke pas ou ne lit pas les données des cookies. boolean
true
domaine Domaine de cookies personnalisé, qui est utile si vous souhaitez partager des cookies Application Insights entre les sous-domaines. S’il n’est pas fourni, utilise la valeur de la valeur racine cookieDomain. string
null
path Spécifie le chemin d’accès à utiliser pour le cookie. S’il n’est pas fourni, il utilisera n’importe quelle valeur de la valeur racine cookiePath. string
/
getCookie Fonction permettant d’extraire la valeur de cookie nommée. Si elle n’est pas fournie, elle utilise l’analyse/la mise en cache du cookie interne. (name: string) => string
null
setCookie Fonction pour définir le cookie nommé avec la valeur spécifiée. Appelée uniquement lors de l’ajout ou de la mise à jour d’un cookie. (name: string, value: string) => void
null
delCookie Fonction permettant de supprimer le cookie nommé avec la valeur spécifiée, séparé de setCookie pour éviter d’avoir à analyser la valeur pour déterminer si le cookie est ajouté ou supprimé. Si elle n’est pas fournie, elle utilise l’analyse/la mise en cache du cookie interne. (name: string, value: string) => void
null

Activer le suivi du temps sur une page

En définissant autoTrackPageVisitTime: true, le temps en millisecondes que passe chaque utilisateur sur chaque page est suivi. Pour chaque nouvelle consultation de page, le temps passé par l’utilisateur sur la page précédente est envoyé en tant que métrique personnalisée appelée PageVisitTime. Cette métrique personnalisée est affichable dans Metrics Explorer en tant que métrique basée sur le journal.

Activer le suivi distribué

La corrélation génère et envoie des données qui activent le suivi distribué et alimente la cartographie d’application, la vue de transaction de bout en bout et d’autres outils de diagnostic.

En JavaScript, la corrélation est désactivée par défaut pour réduire le volume de données de télémétrie que nous envoyons par défaut. Les exemples suivants illustrent les options de configuration standard permettant d’activer la corrélation.

L’exemple de code suivant montre les configurations nécessaires pour activer la corrélation.

// excerpt of the config section of the JavaScript SDK snippet with correlation
// between client-side AJAX and server requests enabled.
cfg: { // Application Insights Configuration
    instrumentationKey: "YOUR_INSTRUMENTATION_KEY_GOES_HERE"
    connectionString: "Copy connection string from Application Insights Resource Overview"
    enableCorsCorrelation: true,
    enableRequestHeaderTracking: true,
    enableResponseHeaderTracking: true,
    correlationHeaderExcludedDomains: ['*.queue.core.windows.net']
    /* ...Other Configuration Options... */
}});
</script>

Remarque

Il existe deux modes/protocoles de suivi distribué : IA (classique) et W3C TraceContext (nouveau). Dans la version 2.6.0 et les versions ultérieures, les deux modes sont activés par défaut. Pour les versions antérieures, les utilisateurs doivent accepter explicitement le mode W3C.

Suivi des routes

Par défaut, ce kit SDK ne gère pas les modifications de route basées sur l’état qui se produisent dans les applications monopages. Pour activer le suivi automatique des modifications de route pour votre application monopage, vous pouvez ajouter enableAutoRouteTracking: true à la configuration de votre installation.

Applications monopages

Pour les applications monopages, référencez la documentation du plug-in pour obtenir des conseils spécifiques sur les plug-ins.

Plug-ins
React
React Native
Angular
Click Analytics Auto-collection

Corrélation avancée

Quand une page est chargée pour la première fois alors que le kit de développement logiciel (SDK) n’a pas été entièrement initialisé, nous ne pouvons pas générer l’ID de l’opération pour la première requête. Par conséquent, le suivi distribué est incomplet tant que le SDK n’est pas entièrement initialisé. Pour résoudre ce problème, vous pouvez inclure du contenu JavaScript dynamique sur la page HTML retournée. Le kit de développement logiciel (SDK) utilise une fonction de rappel lors de l’initialisation pour extraire de manière rétroactive l’ID d’opération à partir de serverside et le remplit avec clientside.

Voici un exemple de création d’un JavaScript dynamique à l’aide de Razor.

<script>
!function(T,l,y){<removed snippet code>,{
    src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js", // The SDK URL Source
    onInit: function(appInsights) {
        var serverId = "@this.Context.GetRequestTelemetry().Context.Operation.Id";
        appInsights.context.telemetryTrace.parentID = serverId;
    },
    cfg: { // Application Insights Configuration
        instrumentationKey: "YOUR_INSTRUMENTATION_KEY_GOES_HERE"
    }});
</script>

Attention

L’expérience utilisateur de l’application n’est pas encore optimisée pour présenter ces scénarios de suivi distribué avancés de type « premier tronçon ». Les données seront disponibles dans la table des requêtes pour les requêtes et les diagnostics.

Extensions

Extensions
React
React Native
Angular
Click Analytics Auto-collection

Explorer les données côté navigateur/client

Vous pouvez afficher les données côté navigateur/client en accédant à Métriques et en ajoutant les métriques individuelles qui vous intéressent.

Capture d’écran de la page Métriques dans Application Insights montrant des affichages graphiques de données métriques pour une application web.

Vous pouvez également afficher vos données à partir du kit SDK JavaScript via l’expérience du navigateur dans le portail.

Sélectionnez Navigateur, puis choisissez Échecs ou Performances.

Capture d’écran de la page Navigateur dans Application Insights montrant comment ajouter Échecs du navigateur ou Performances du navigateur aux métriques que vous pouvez afficher pour votre application web.

Performances

Capture d’écran de la page Performances dans Application Insights montrant des affichages graphiques des métriques Opérations pour une application web.

Les dépendances

Capture d’écran de la page Performances dans Application Insights montrant des affichages graphiques des métriques Dépendances pour une application web.

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 seront 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

Prise en charge du mappage de source

La pile d’appels minimisée de vos données de télémétrie d’exception peut être déminimisée dans le portail Azure. Toutes les intégrations existantes dans le panneau Détails des exceptions fonctionnent avec la pile d’appels nouvellement déminimisée.

Vous pouvez lier votre ressource Application Insights à votre propre conteneur de stockage blob Azure pour réduire automatiquement les piles d’appels. Pour commencer, consultez la prise en charge automatique du mappage de source.

Glisser-déplacer

  1. Sélectionnez un élément Télémétrie des exceptions dans le portail Azure pour afficher ses « détails de transaction de bout en bout ».

  2. Identifiez les mappages de source qui correspondent à cette pile d’appels. Le mappage de source doit correspondre au fichier source d’un frame de pile, mais avec le suffixe .map.

  3. Faites glisser les mappages de source sur la pile des appels dans le portail Azure.

    Une image animée montrant comment faire glisser des fichiers de mappage de source d’un dossier de compilation à une fenêtre de pile d’appel dans le portail Azure.

Version web de base d’Application Insights

Pour bénéficier d’une expérience plus simple, vous pouvez installer à la place la version de base d’Application Insights :

npm i --save @microsoft/applicationinsights-web-basic

Cette version fournit un strict minimum de fonctionnalités et vous laisse la compléter à votre guise. Par exemple, elle n’effectue pas de collecte automatique, comme des exceptions non interceptées et AJAX. Les API pour envoyer certains types de données de télémétrie comme trackTrace et trackException ne sont pas incluses dans cette version. Pour cette raison, vous devez fournir votre propre wrapper. La seule API disponible est track. Vous trouverez un exemple ici.

Exemples

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

Mettre à niveau à partir de l’ancienne version d’Application Insights

Dernières modifications dans la version V2 du kit SDK :

  • Pour permettre de meilleures signatures d’API, certains appels d’API, tels que trackPageView et trackException, ont été mis à jour. L’exécution dans Internet Explorer 8 ou des versions antérieures du navigateur n’est pas prise en charge.

  • L’enveloppe de télémétrie présente des modifications de structure et de nom des champs en raison de mises à jour du schéma de données.

  • context.operation a été déplacé vers context.telemetryTrace. Certains champs ont également été modifiés (operation.id -->telemetryTrace.traceID).

    Pour actualiser manuellement l’ID de consultation de page actuel (par exemple, dans les applications monopages), utilisez appInsights.properties.context.telemetryTrace.traceID = Microsoft.ApplicationInsights.Telemetry.Util.generateW3CId().

    Notes

    Pour conserver l’ID de trace unique, dans lequel vous avez déjà utilisé Util.newId(), utilisez maintenant Util.generateW3CId(). Tous deux finissent par être l’ID d’opération.

Si vous utilisez le kit SDK de PRODUCTION d’Application Insights actuel (1.0.20) et que vous souhaitez voir si le nouveau kit SDK fonctionne dans le runtime, mettez à jour l’URL en fonction de votre scénario de chargement de kit SDK actuel.

  • Scénario de téléchargement via CDN : Mettez à jour l’extrait de code que vous utilisez actuellement pour pointer vers l’URL suivante :

    "https://js.monitor.azure.com/scripts/b/ai.2.min.js"
    
  • Scénario npm : Appelez downloadAndSetup pour télécharger le script ApplicationInsights complet à partir de CDN et l’initialiser avec une chaîne de connexion :

    appInsights.downloadAndSetup({
       connectionString: "Copy connection string from Application Insights Resource Overview",
       url: "https://js.monitor.azure.com/scripts/b/ai.2.min.jss"
       });
    

Effectuez un test dans un environnement interne pour vérifier que la télémétrie de surveillance fonctionne comme prévu. Si tout fonctionne, mettez à jour vos signatures d’API conformément à la version v2 du kit SDK et procédez au déploiement dans vos environnements de production.

Surcharge/performances du kit SDK

Avec seulement 36 Ko compressés avec gzip et en mettant seulement ~15 ms pour s’initialiser, Application Insights ajoute un temps de chargement négligeable à votre site web. Les composants minimaux de la bibliothèque sont rapidement chargés lors de l’utilisation de cet extrait de code. En attendant, le script complet est téléchargé en arrière-plan.

Pendant le téléchargement du script à partir de CDN, tout le suivi de votre page est mis en file d’attente. Après que le script téléchargé a fini de s’initialiser de manière asynchrone, tous les événements qui ont été mis en file d’attente font l’objet d’un suivi. Par conséquent, vous ne perdrez aucune donnée de télémétrie au cours du cycle de vie complet de votre page. Ce processus de configuration fournit à votre page un système d’analyse transparent, invisible à vos utilisateurs.

Résumé :

  • version npm
  • taille compressée de gzip
  • Durée d’initialisation globale de 15 ms
  • Aucun suivi manqué pendant le cycle de vie de la page

Prise en charge des navigateurs

Chrome Firefox IE Opera Safari
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 ✔

Compatibilité ES3/Internet Explorer 8

Nous devons nous 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 devront ê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.

Kit de développement logiciel (SDK) open source

Le Kit de développement logiciel (SDK) JavaScript Application Insights est open source. Pour voir le code source ou contribuer au projet, consultez le référentiel officiel GitHub.

Pour obtenir les mises à jour et correctifs de bogues les plus récents, consultez les notes de publication.

Dépannage

Cette section vous aide à résoudre les problèmes courants.

Je reçois un message d’erreur qui indique un échec d’obtention de l’en-tête de corrélation Request-Context, car il n’est peut-être pas inclus dans la réponse ou non accessible

La propriété de configuration correlationHeaderExcludedDomains est une liste d’exclusion qui désactive les en-têtes de corrélation pour des domaines spécifiques. Cette option est utile lorsque le fait d’inclure ces en-têtes provoqueraient l’échec de la requête ou empêcheraient son envoi en raison de la configuration d’un serveur tiers. Cette propriété prend en charge les caractères génériques. Un exemple serait *.queue.core.windows.net, comme illustré dans l’exemple de code précédent. L’ajout du domaine d’application à cette propriété doit être évité, car il empêche le SDK d’inclure les en-têtes Request-Id, Request-Context et traceparent de suivi distribué nécessaires dans le cadre de la requête.

Je ne sais pas 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>

Je reçois des données de télémétrie dupliquées en provenance du kit de développement logiciel (SDK) Application Insights JavaScript

Si le kit de développement logiciel (SDK) signale la corrélation de façon récursive, activez le paramètre de configuration excludeRequestFromAutoTrackingPatterns pour exclure les données dupliquées. Ce scénario peut se produire lorsque vous utilisez des chaînes de connexion. La syntaxe du paramètre de configuration est excludeRequestFromAutoTrackingPatterns: [<endpointUrl>].

Tester la connectivité entre votre hôte d’application et le service d’ingestion

Les SDK et les agents Application Insights envoient de la télémétrie à ingérer en tant qu’appels REST à nos points de terminaison d’ingestion. Vous pouvez tester la connectivité de votre serveur web ou de votre machine hôte d’application vers les points de terminaison de service d’ingestion en utilisant des clients REST bruts à partir de commandes PowerShell ou curl. Consultez Résoudre les problèmes de télémétrie d’application manquante dans Azure Monitor Application Insights.

Étapes suivantes