Relecture de session | ClickHouse Docs

La relecture de session dans ClickStack capture et reconstitue les interactions des utilisateurs dans votre application web, ce qui vous permet de rejouer visuellement exactement ce qu’un utilisateur a vu et fait pendant sa session. Plutôt qu’un enregistrement vidéo, le SDK enregistre les modifications du DOM, les mouvements de souris, les clics, les défilements, les saisies au clavier, les console logs, les requêtes réseau (XHR, Fetch, WebSocket) et les exceptions JavaScript — puis reconstitue l’expérience dans le navigateur.

Comme les relectures de session sont stockés dans ClickHouse aux côtés de vos logs, traces et métriques, vous pouvez passer du visionnage de l’expérience d’un utilisateur à l’inspection des traces backend et des requêtes de base de données qui l’ont alimentée — le tout en quelques clics. La relecture de session est donc utile pour le debugging des problèmes de production, comprendre le comportement des utilisateurs, identifier les points de friction UX et confirmer visuellement les problèmes signalés au support.

Instrumenter votre application

ClickStack est entièrement compatible avec OpenTelemetry. Vous pouvez donc envoyer de la télémétrie navigateur (traces, exceptions) à l’aide du SDK JavaScript OpenTelemetry standard ou de l’un des SDKs ClickStack pour différents langages. Cependant, la relecture de session nécessite le Browser SDK de ClickStack (@hyperdx/browser), qui étend le SDK OpenTelemetry avec l’enregistrement de session, la capture de la console et la capture des requêtes réseau. Si vous avez seulement besoin de traces, sans relecture de session, n’importe quel SDK navigateur compatible OTel fonctionnera avec ClickStack.

Les exemples ci-dessous utilisent le Browser SDK de ClickStack. Ajouter la relecture de session à votre application ne prend que trois étapes : installer le paquet, initialiser le SDK, puis toutes les interactions utilisateur sont capturées automatiquement — aucune autre modification du code n’est nécessaire.

npm install @hyperdx/browser

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],
  consoleCapture: true,
  advancedNetworkCapture: true,
});

yarn add @hyperdx/browser

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],
  consoleCapture: true,
  advancedNetworkCapture: true,
});

Pour les applications qui n’utilisent pas de bundler, incluez directement le SDK via une balise de script. La variable globale HyperDX est alors exposée et peut être utilisée de la même manière que le paquet NPM.

<script src="https://unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
<script>
  window.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],
    consoleCapture: true,
    advancedNetworkCapture: true,
  });
</script>

Le Browser SDK prend également en charge le masquage des champs de saisie et du texte pour les applications sensibles à la confidentialité, ainsi que l’ajout d’informations ou de métadonnées utilisateur, afin de pouvoir rechercher et filtrer les sessions par utilisateur dans l’UI ClickStack.

Visualisation des relectures de session

Accédez à Client Sessions depuis la barre latérale gauche dans l’UI ClickStack (HyperDX). Cette vue répertorie toutes les sessions de navigateur capturées, avec leur durée et leur nombre d'événements.

Vue de recherche des relectures de session

Cliquez sur le bouton de lecture d'une session pour la rejouer. La vue de relecture de session affiche l'expérience utilisateur reconstituée à droite, avec à gauche une chronologie des événements du navigateur — requêtes réseau, console logs et erreurs.

Basculez entre les modes Highlighted et All Events pour ajuster le niveau de détail affiché dans la chronologie. Les erreurs sont annotées en rouge, et cliquer sur un événement positionne la relecture de session à cet instant de la session.

De la session à la trace

Lorsque vous sélectionnez une requête réseau ou une erreur dans la chronologie de la session, vous pouvez accéder à l’onglet Trace pour suivre cette requête dans vos services backend et voir les logs, spans et requêtes de base de données associés, déclenchés par cette interaction utilisateur.

Cela fonctionne parce que la configuration tracePropagationTargets relie les spans du navigateur aux spans du server via l’en-tête traceparent, créant ainsi une trace distribuée continue depuis le clic de l’utilisateur jusqu’à la base de données. Pour une présentation détaillée de sa mise en œuvre, y compris l’instrumentation du frontend et du backend, consultez Instrumenter votre application NextJS avec OpenTelemetry et ClickStack.

Explorer les traces backend dans ClickStack à partir d’une relecture de session

De la trace à la session

La corrélation fonctionne aussi dans l'autre sens. Lorsque vous consultez une trace dans la vue Search, cliquez dessus pour ouvrir son détail, puis sélectionnez l'onglet Relecture de session pour voir exactement ce que l'utilisateur faisait au moment de cette trace. C'est particulièrement utile pour analyser des erreurs ou des requêtes lentes : vous pouvez partir d'un problème backend et voir immédiatement le point de vue de l'utilisateur.

Comment les données de session sont stockées

Les données de relecture de session sont stockées dans une table dédiée hyperdx_sessions dans ClickHouse, distincte des logs et des traces. Chaque événement de session correspond à une ligne, avec un champ Body contenant la charge utile de l’événement et une map LogAttributes qui stocke les métadonnées de l’événement. Les colonnes Body et LogAttributes contiennent ensemble les détails des événements de session utilisés pour reconstituer la relecture.

Pour des informations complètes sur le schéma de la table, consultez Tables et schémas utilisés par ClickStack.

Essayez

Il existe deux façons de voir la relecture de session en action :

Exemple en direct — rendez-vous sur clickpy.clickhouse.com, interagissez avec l’application, puis consultez le replay de votre session sur play-clickstack.clickhouse.com, dans la source ClickPy Sessions. Pour savoir comment ClickPy a été instrumentée, consultez l’article de blog Instrumenting your NextJS application with OpenTelemetry and ClickStack.
Démo locale — la relecture de session demo explique pas à pas comment instrumenter une application de démonstration, y compris l’exécution de ClickStack en local et la consultation de vos replays.

En savoir plus

Relecture de session demo — application de démonstration locale interactive avec des instructions pas à pas
Browser SDK Reference — options complètes du SDK, source maps, actions personnalisées et configuration avancée
Search — syntaxe de recherche pour filtrer les sessions et les événements
Dashboards — créez des visualisations et des tableaux de bord à partir des données de session et de trace
Alertes — configurez des alertes sur les erreurs, la latence et d'autres signaux
Architecture de ClickStack — comment ClickHouse, HyperDX et l'OTel collector s'articulent