API de l'agent JavaScript

Le tableau suivant répertorie les paramètres :

Les touches de surveillance peuvent être définies à l'aide de la commande key La clé de surveillance s'affiche lorsque vous configurez des sites Web dans l'interface utilisateur d' Instana.

ineum('key', trackingKey);
 

Les balises sont transmises à l' URL de rapport via HTTP GET et POST afin de transmettre les données de surveillance à Instana.

ineum('reportingUrl', reportingUrl);
 

Dans certains cas, il peut être souhaitable de générer un rapport d'agent JavaScript vers plusieurs systèmes de back-end. Dans ce cas, utilisez la commande reportingBackends pour que l'agent JavaScript génère un rapport sur plusieurs systèmes de back end.

ineum('reportingBackends', reportingBackends);
 

Instana peut segmenter les métriques de site Web par page logique. Pour ce faire, il a besoin d'une indication sur la page que l'utilisateur est en train de consulter. Ce nom de page peut être défini par la commande page Fixer le page le plus tôt possible. Vous pouvez changer le page pour présenter les modifications apportées au document (par exemple, pour les applications d'une seule page). Cela permet à Instana de suivre les transitions entre les pages, en plus du chargement de celles-ci.

ineum('page', pageName);
 

Les événements de transition de page sont enregistrés chaque fois que le nom de la page est modifié via l' API, à l'exception de la première invocation de cette API pendant la phase de chargement de la page.

Pour définir des pages, utilisez des noms logiques comme product detail page ou payment selection au lieu de window.title ou window.href. L'utilisation de product detail page ou payment selection permet de réduire le nombre de pages ayant une relation directe avec le code existant. En revanche, l'utilisation de window.title ou window.href donne lieu à de nombreuses pages suivies qui apportent une valeur ajoutée dans la plupart des cas, car window.title contient des noms de produits.

Instana propose des exemples de projets illustrant comment générer des noms de pages pertinents pour divers frameworks et bibliothèques. Déposer une demande d'extraction ou d'assistance pour le cadre ou la bibliothèque manquante.

Des informations spécifiques à l'utilisateur peuvent, le cas échéant, être envoyées avec les données transmises à Instana. Ces informations peuvent ensuite être utilisées pour débloquer d'autres capacités telles que :

• Calculer le nombre d'utilisateurs affectés par les erreurs
• Pour filtrer les données pour des utilisateurs spécifiques
• Pour savoir quel utilisateur a déclenché le chargement d'une page ou un appel Ajax.

Par défaut, Instana n'associe aucune information permettant d'identifier l'utilisateur aux balises. Soyez conscient des lois respectives sur la protection des données lorsque vous choisissez de le faire. Dans « Instana », l'identifiant utilisateur est un paramètre transparent string qui sert uniquement à calculer certains indicateurs. L'identification des utilisateurs se fait donc par le biais d'un identifiant. userName et userEmail peut également être utilisé pour accéder à davantage de filtres et bénéficier d'une présentation efficace des informations utilisateur.

Le fait d'appeler cette méthode ` API ` de manière synchrone lors du chargement de la page, par exemple en intégrant les informations dans le document HTML côté serveur, permet de s'assurer que toutes les balises contiennent les informations utilisateur, que les statistiques relatives aux utilisateurs uniques ou concernés sont correctes, et que les balises sont correctement filtrées et regroupées lors de l'analyse.

ineum('user', userId, userName, userEmail);
 

Le suivi de session peut être utilisé pour obtenir des informations sur l'activité des utilisateurs finaux lors du chargement des pages. Le suivi des sessions permet notamment à Instana d'évaluer l'impact sur les utilisateurs finaux en l'absence d 'informations définies sur les utilisateurs.

Pour suivre les sessions, l'agent JavaScript utilise l' API localStorage du navigateur après avoir effectué la connexion. trackSessions appel. Techniquement, une session est un identifiant aléatoire qui est stocké avec deux horodatages dans les navigateurs localStorage sous la clé in-session

L'appelant de cette API est en charge du respect des réglementations en matière de confidentialité.

Les métadonnées peuvent être utilisées pour annoter les chargements de page et les appels AJAX. Utilisez les métadonnées pour suivre les valeurs de configuration de l'interface utilisateur, les paramètres, les indicateurs de fonctionnalité ou tout autre élément contextuel susceptible d'être utile à l'analyse.

ineum('meta', key, value);
 

Lors du chargement de la page, il est possible de définir un identifiant de trace côté serveur afin de permettre la corrélation entre le front-end et le back-end. Pour plus d'informations, consultez la section « Corrélation backend ». Il est nécessaire de définir l'identifiant de trace du backend pour établir une corrélation entre le traitement backend et le traitement front-end lors du chargement des pages. Elle n'est pas nécessaire pour la corrélation entre les demandes XMLHttpRequest ou fetch. L'identifiant de la trace doit être une chaîne hexagonale de 16 ou 32 caractères.

ineum('traceId', traceId);
 

Vous pouvez définir plusieurs expressions régulières à l'aide de cet outil : API. Si au moins une correspondance est trouvée, cela n'entraîne pas de transmission de données vers Instana. Les expressions régulières sont évaluées dans les scénarios suivants :

• Vérification par rapport aux URL des documents (les URL visibles dans la barre d'adresse, c'est-à-dire window.location.href). Toute transmission de données vers Instana est désactivée lorsqu'une des expressions régulières correspond.
• Évaluation par rapport aux URL des ressources, par exemple les URL des fichiers JavaScript et CSS. Aucune information concernant les ressources correspondant à l'une des expressions régulières n'est transmise à Instana.
• Évaluation par rapport aux URL cibles des appels HTTP, par exemple via XMLHttpRequest et fetch. Aucune information concernant les appels « HTTP » correspondant à l'une des expressions régulières n'est transmise à Instana.

ineum('ignoreUrls', ignoreUrls);
 

Instana prend également en charge la suppression des informations confidentielles des URL des documents, c'est-à-dire l'adresse URL visible dans la barre d'adresse du navigateur (voir la page API ). Cependant, il faut savoir que les secrets stockés dans les URL des documents sont pratiquement divulgués à tous les tiers. Nous proposons une application de démonstration spécifique, accompagnée d'une description, qui explique pourquoi les secrets stockés dans les URL de documents risquent d'être divulgués à tous les tiers. Pour plus de détails, reportez-vous à l'exemple d'application et à la description. Vous pouvez toutefois choisir de désactiver la collecte de toutes les données de suivi pour ces URL via cette page : API.

Les paramètres de requête dans les URL collectés peuvent contenir des données sensibles. Par conséquent, l'agent JavaScript prend en charge la spécification de modèles pour les clés de paramètres de requête dont les valeurs sont expurgées. La rédaction se fait au sein de l'agent JavaScript, c'est-à-dire au sein du navigateur web. Par conséquent, les données confidentielles ne sont pas transmises aux serveurs d' Instana. pour y être traitées et ne peuvent donc pas être analysées dans l'interface utilisateur ni récupérées via API.

ineum('secrets', secrets);
 

Si un paramètre de requête correspond à une entrée de la liste, la valeur est masquée et n'est pas transmise au backend d' Instana. Si aucune règle ineum('secrets') n'est définie, Instana utilise par défaut [/key/i, /secret/i, /password/i] comme règle de correspondance.

Le fragment des URL collectées peut contenir des informations sensibles. Par conséquent, l'agent « JavaScript » prend en charge la définition de modèles pour les valeurs de fragment pouvant être masquées en fonction du chemin d'accès « URL ». Cette modification s'effectue au sein de l'agent JavaScript dans le navigateur Web. De ce fait, les informations sensibles ne parviennent pas aux serveurs d' Instana s pour y être traitées. Les informations sensibles restent inaccessibles pour toute analyse via l'interface utilisateur ou pour toute consultation via l' API.

ineum('fragment', fragment);
 

Si une partie de votre chemin d'accès URL correspond à une entrée de la liste, la valeur du fragment est masquée et n'est pas transmise au backend Instana. Par défaut, Instana ne masque pas les fragments de l'adresse URL.

Instana collecter automatiquement les marqueurs et les mesures générés via l' API User-Timing et les convertir en événements personnalisés. Cela signifie que l'API User-Timing peut être utilisée comme un moyen neutre du fournisseur pour rapporter des données temporelles pures à Instana.

En utilisant l' API User-Timing, vous pouvez définir plusieurs expressions régulières qui, dès lors qu'au moins l'une d'entre elles correspond, empêchent la collecte de certaines données de chronométrage utilisateur. Par défaut, les conditions suivantes sont ignorées :

• Les « user-timings » de React : les repères et mesures qui commencent par l'émoji ⚛️ ou ⛔
• Les « user-timings » de Angular : les repères et les mesures qui commencent par Zone
• Marques et mesures dont les noms commencent par start ou end

ineum('ignoreUserTimings', ignoreUserTimings);
 

Par défaut, l'agent « JavaScript » collecte l' URL complète, qui comprend tous ses paramètres. Vous pouvez configurer l'agent de manière à ce qu'il ne collecte les paramètres que pour les URL correspondant à une liste spécifiée d'expressions régulières. Les paramètres des URL exclues ne sont pas suivis.

À partir de la liste d'expressions régulières fournie, l'agent « JavaScript » suit les URL comme suit :

• Si l' URL e correspond à une entrée de la liste, l' URL e complète, y compris tous les paramètres, est récupérée.
• Si l'adresse URL ne correspond à aucune entrée de la liste, les paramètres de requête et les fragments de l'adresse URL ne sont pas transmis au backend Instana.
• Si la liste fournie est vide, le comportement par défaut est appliqué et l' URL e complète, avec ses paramètres, est enregistrée.

ineum('queryTrackedDomainList',queryTrackedDomainList);
 

Les scénarios suivants décrivent la situation dans laquelle l' URL contient un secret ou un fragment masqué à l'aide de ineum('secrets', secrets) ou ineum('fragment', fragment):

• Si l' URL e correspond à une entrée dans queryTrackedDomainList, l' URL e complet, avec le secret ou le fragment masqué, est envoyé au backend Instana.
• Si l' URL e ne correspond à aucune entrée dans queryTrackedDomainList, tous les paramètres sont exclus avant l'envoi de l' URL e au backend Instana.

Lorsqu'un navigateur envoie une requête à un serveur distant et que l'agent Instana surveille ce serveur, la réponse de ce dernier peut contenir l'en-tête HTTP Server-Timing afin de fournir les informations nécessaires. backendTraceId à l'agent Instana qui s'exécute dans le navigateur. Si l'authentification par nom d'utilisateur et mot de passe ( OpenTelemetry ) est activée sur le serveur distant, l'en-tête tracestateHTTP peut contenir le backendTraceId.

tracestate et traceparent sont des en-têtes « W3C-defined » utilisés pour mettre en correspondance les identifiants de trace distribués. Pour plus d'informations sur les en-têtes de trace d' W3C, consultez la section « Niveau de contexte de trace ».

Si vous pensez que le serveur distant prend en charge la directive « OpenTelemetry » et fournit la valeur backendTraceId dans tracestate l'en-tête, l'agent « Instana » du navigateur doit alors définir la variable enableW3CHeaders « API » sur « true » pour utiliser la backendTraceId valeur dans les en-têtes « W3C ».

Vous pouvez définir le paramètre backendTraceId à trois endroits différents : via Server-Timing l'en-tête, via tracestate l'en-tête, et manuellement en utilisant l' traceIdAPI dans le navigateur. L'ordre de ces étapes est le suivant :

• Si cette option enableW3CHeaders est activée, vous avez deux possibilités. Commencez par extraire la tracestate valeur des métadonnées de la traceparent page actuelle, puis utilisez-la. Si vous ne parvenez pas à récupérer tracestate, une chaîne de 16 caractères compatible avec le contexte de trace d' W3C est générée et utilisée.
• Si enableW3CHeaders est désactivé, vérifiez d'abord si la fonction traceId API est appelée. Si la traceId méthode ` API ` est appelée, utilisez l'ID comme backendTraceId. Si la traceId méthode ` API ` n'est pas appelée, analysez l'en-tête `Server-Timing` de la requête ` HTTP ` pour obtenir la valeur backendTraceId.
• Si aucune des valeurs ci-dessus n'est disponible, vous ne pouvez pas associer les balises aux traces du backend.

ineum('enableW3CHeaders',true);
 

Pour collecter des indicateurs supplémentaires, l'agent « JavaScript » attend que les conditions suivantes soient réunies. Par exemple, le délai de la première entrée et le décalage cumulatif de la disposition.

• Tous les indicateurs sont disponibles
• La page est déchargée (par exemple, l'onglet est fermé)
• Jusqu'à l'écoulement d'un temps d'attente maximum

Vous pouvez utiliser cette API pour reconfigurer le temps d'attente maximal. Par défaut, Instana attend jusqu'à une seconde après la fin du chargement de la page, c'est-à-dire après la fin de l'événement « onLoad ».

ineum('maxMaitForPageLoadMetricsMillis', durationMillis);
 

Il peut parfois être utile de récupérer manuellement l'identifiant de chargement de la page, par exemple lorsqu'on souhaite effectuer une corrélation personnalisée. Cette fonction renvoie undefined si l'agent JavaScript n'est pas chargé. Une fois l'agent JavaScript chargé, il renvoie toujours le même string

ineum('getPageLoadId');
 

Pour plus d'informations sur les événements personnalisés globaux, consultez la page Événements.

Les événements personnalisés permettent de signaler à Instana les activités atypiques, les interactions importantes et les délais personnalisés. Cela peut s'avérer particulièrement utile pour analyser les erreurs non interceptées (fil d'Ariane) et pour suivre davantage d'indicateurs de performance.

ineum('reportEvent', eventName, {
  duration: duration,
  timestamp: timestamp,
  backendTraceId: backendTraceId,
  error: error,
  componentStack: componentStack,
  meta: meta,
  customMetric: customMetric
});
 

La corrélation de back end d'Instana fonctionne via la définition d'en-têtes personnalisés dans les demandes XMLHttpRequest/fetch. L'agent « JavaScript » définit ces en-têtes, qui sont ensuite lues par le serveur. Dans le navigateur, la politique de même origine restreint la transmission des en-têtes personnalisés. Plus précisément, les en-têtes personnalisés ne peuvent être définis que pour les requêtes de même origine ou pour les requêtes vers d'autres origines qui autorisent la transmission d'en-têtes personnalisés. Par exemple, par défaut, un site web desservi par https://example.com:443 ne peut pas faire de XMLHttpRequestà https://shop.example.com:443 car il s'agit de deux origines différentes.

Pour contourner cette restriction de sécurité, le partage de ressources entre origines ( CORS ) est disponible. Avec CORS, des origines peuvent être autorisées pour l'accès aux ressources d'origine croisée. Si vous avez déjà accès à des ressources d'origine croisée dans votre application, vous utilisez probablement déjà des en-têtes CORS.

Pour activer la corrélation du backend d' Instana, procédez comme suit :

1. Autorisez les en-têtes de corrélation d'Instana pour les demandes d'origine croisée en répondant côté serveur avec les en-têtes ci-après.

   Remarque : votre serveur doit renvoyer ces en-têtes aussi bien pour les requêtes de pré-vérification que pour les requêtes standard. Les requêtes de pré-vérification (identifiables via la OPTIONS méthode ` HTTP `) sont exécutées par le navigateur afin de vérifier si des requêtes sont susceptibles d'être envoyées au serveur.

   Access-Control-Allow-Origin: https://your-origin.example.com
   Access-Control-Allow-Headers: X-INSTANA-T, X-INSTANA-S, X-INSTANA-L
   
    

2. Indiquez à l'agent d' JavaScript s que CORS est correctement configuré et qu'il doit définir les en-têtes de corrélation suivants :

   ineum('allowedOrigins', urls);
    

Les en-têtes de requête ou de réponse « HTTP » des requêtes XMLHttpRequestfetch ou peuvent être capturés par l'agent JavaScript. Vous pouvez définir les en-têtes HTTP que vous souhaitez que l'agent JavaScript capture à l'aide de la captureHeaders commande.

Dans le navigateur, la règle de même origine restreint l'accès aux en-têtes personnalisés. Sans configuration du partage de ressources entre origines ( CORS ), l'agent JavaScript risque de ne pas pouvoir capturer tous les en-têtes HTTP. Pour activer la fonctionnalité « CORS », consultez la section «Cross-Origin Request Backend Correlation ». Avec l'option « CORS », seuls les en-têtes de requête ou de réponse qui respectent la règle « CORS » et ceux définis dans « Access-Control-Expose-Headers » peuvent être collectés par l'agent « JavaScript ».