JS Browser

Le SDK Browser de ClickStack vous permet d’instrumenter votre application frontend afin d’envoyer des événements à ClickStack. Vous pouvez ainsi afficher les requêtes réseau et les exceptions aux côtés des événements du backend sur une même chronologie. De plus, il capture et corrèle automatiquement les données de relecture de session, afin que vous puissiez revoir visuellement, étape par étape, ce qu’un utilisateur voyait lorsqu’il utilisait votre application, pour faciliter le débogage. Ce guide intègre les éléments suivants :

Logs de console
Relectures de session
Requêtes XHR/Fetch/WebSocket
Exceptions

Prise en main

Import de paquet
Balise script

Installer via l’import de paquet (recommandé)Utilisez la commande suivante pour installer le paquet navigateur.

npm install @hyperdx/browser

Initialiser ClickStack

import HyperDX from '@hyperdx/browser';

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', //à omettre pour Managed ClickStack
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // Définir pour relier les traces des requêtes frontend au backend
    consoleCapture: true, // Capturer les logs de console (false par défaut)
    advancedNetworkCapture: true, // Capturer l’intégralité des en-têtes et corps des requêtes/réponses HTTP (false par défaut)
});

Installer via une balise script (alternative)Vous pouvez également inclure le script au moyen d’une balise script, au lieu de l’installer via NPM. Cela expose la variable globale HyperDX et permet de l’utiliser de la même manière que le paquet NPM.Cette option est recommandée si votre site n’est pas actuellement compilé à l’aide d’un bundler.

<script src="//www.unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
<script>
  window.HyperDX.init({
    url: 'http://localhost:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', //à omettre pour Managed ClickStack
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // Définir pour relier les traces des requêtes frontend au backend
  });
</script>

Options

apiKey - Votre clé API d’ingestion ClickStack.
service - Le nom du service tel qu’il apparaîtra dans l’UI HyperDX.
tracePropagationTargets - Une liste de motifs Regex à faire correspondre aux requêtes HTTP pour lier les traces du frontend et du backend ; cela ajoutera un en-tête traceparent supplémentaire à toutes les requêtes correspondant à l’un des motifs. Cette valeur doit être définie sur le domaine de votre API backend (par ex. api.yoursite.com).
consoleCapture - (Facultatif) Capturer tous les logs de console (par défaut false).
advancedNetworkCapture - (Facultatif) Capturer l’intégralité des en-têtes et des corps des requêtes/réponses (par défaut false).
url - (Facultatif) L’URL de l’OpenTelemetry Collector, nécessaire uniquement pour les instances auto-hébergées.
maskAllInputs - (Facultatif) Indique s’il faut masquer tous les champs de saisie dans la relecture de session (par défaut false).
maskAllText - (Facultatif) Indique s’il faut masquer tout le texte dans la relecture de session (par défaut false).
disableIntercom - (Facultatif) Indique s’il faut désactiver l’intégration Intercom (par défaut false)
disableReplay - (Facultatif) Indique s’il faut désactiver la relecture de session (par défaut false)

Configuration supplémentaire

Associer des informations utilisateur ou des métadonnées

L’association d’informations utilisateur vous permettra de rechercher/filtrer les sessions et les événements dans la UI HyperDX. Cette méthode peut être appelée à n’importe quel moment pendant la session client. La session client en cours et tous les événements envoyés après cet appel seront associés aux informations utilisateur. userEmail, userName et teamName renseigneront l’interface des sessions avec les valeurs correspondantes, mais peuvent être omis. Toute autre valeur supplémentaire peut être spécifiée et utilisée pour rechercher des événements.

HyperDX.setGlobalAttributes({
  userId: user.id,
  userEmail: user.email,
  userName: user.name,
  teamName: user.team.name,
  // Other custom properties...
});

Capturer automatiquement les erreurs des error boundaries React

Si vous utilisez React, vous pouvez capturer automatiquement les erreurs qui se produisent dans les error boundaries React en passant votre composant error boundary à la fonction attachToReactErrorBoundary.

// Import your ErrorBoundary (we're using react-error-boundary as an example)
import { ErrorBoundary } from 'react-error-boundary';

// This will hook into the ErrorBoundary component and capture any errors that occur
// within any instance of it.
HyperDX.attachToReactErrorBoundary(ErrorBoundary);

Envoyer des actions personnalisées

Pour suivre explicitement un événement précis de l’application (p. ex. inscription, envoi de formulaire, etc.), vous pouvez appeler la fonction addAction avec un nom d’événement et, éventuellement, des métadonnées associées à l’événement. Exemple :

HyperDX.addAction('Form-Completed', {
  formId: 'signup-form',
  formName: 'Signup Form',
  formType: 'signup',
});

Activer la capture réseau de manière dynamique

Pour activer ou désactiver la capture réseau de manière dynamique, il suffit d’appeler la fonction enableAdvancedNetworkCapture ou disableAdvancedNetworkCapture selon les besoins.

HyperDX.enableAdvancedNetworkCapture();

Activer la mesure du temps des ressources pour les requêtes CORS

Si votre application frontend effectue des requêtes API vers un autre domaine, vous pouvez éventuellement activer l’envoi de l’Timing-Allow-Originen-tête avec la requête. Cela permettra à ClickStack de capturer des informations détaillées sur le temps de chargement des ressources pour la requête, comme la résolution DNS, le téléchargement de la réponse, etc., via PerformanceResourceTiming. Si vous utilisez les paquets express et cors, vous pouvez utiliser l’extrait suivant pour activer cet en-tête :

var cors = require('cors');
var onHeaders = require('on-headers');

// ... all your stuff

app.use(function (req, res, next) {
  onHeaders(res, function () {
    var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
    if (allowOrigin) {
      res.setHeader('Timing-Allow-Origin', allowOrigin);
    }
  });
  next();
});
app.use(cors());

Fonctionnalités

Guides

Prise en main

Options

Configuration supplémentaire

Associer des informations utilisateur ou des métadonnées

Capturer automatiquement les erreurs des error boundaries React

Envoyer des actions personnalisées

Activer la capture réseau de manière dynamique

Activer la mesure du temps des ressources pour les requêtes CORS

​Prise en main

​Options

​Configuration supplémentaire

​Associer des informations utilisateur ou des métadonnées

​Capturer automatiquement les erreurs des error boundaries React

​Envoyer des actions personnalisées

​Activer la capture réseau de manière dynamique

​Activer la mesure du temps des ressources pour les requêtes CORS

Prise en main

Options

Configuration supplémentaire

Associer des informations utilisateur ou des métadonnées

Capturer automatiquement les erreurs des error boundaries React

Envoyer des actions personnalisées

Activer la capture réseau de manière dynamique

Activer la mesure du temps des ressources pour les requêtes CORS