Skip to main content
Skip to main content
Edit this page

Session Replay

Session replay in ClickStack captures and reconstructs user interactions in your web application, allowing you to visually replay exactly what a user saw and did during their session. Rather than video recording, the SDK records DOM changes, mouse movements, clicks, scrolls, keyboard inputs, console logs, network requests (XHR, Fetch, WebSocket), and JavaScript exceptions — then reconstructs the experience in the browser.

Because session replays are stored in ClickHouse alongside your logs, traces, and metrics, you can go from watching a user's experience to inspecting the backend traces and database queries that powered it — all in a few clicks. This makes session replay useful for debugging production issues, understanding user behavior, identifying UX friction points, and visually confirming issues reported to support.

Instrumenting your application​

ClickStack is fully compatible with OpenTelemetry, so you can send browser telemetry (traces, exceptions) using the standard OpenTelemetry JavaScript SDK or any of the ClickStack language SDKs. However, session replay requires the ClickStack Browser SDK (@hyperdx/browser), which extends the OpenTelemetry SDK with session recording, console capture, and network request capture. If you only need traces without session replay, any OTel-compatible browser SDK will work with ClickStack.

The examples below use the ClickStack Browser SDK. Adding session replay to your application takes just three steps: install the package, initialize the SDK, and all user interactions are captured automatically — no further code changes required.

Tip

Initialize the SDK in a place that's guaranteed to load when your app starts. For example, in a Next.js application, this could be your root layout.js. This ensures session recording begins immediately and captures the full user experience.

npm install @hyperdx/browser

import HyperDX from '@hyperdx/browser';

HyperDX.init({
  url: 'http://your-otel-collector:4318',
  apiKey: 'YOUR_INGESTION_API_KEY', // omit for Managed ClickStack
  service: 'my-frontend-app',
  tracePropagationTargets: [/api.myapp.domain/i],
  consoleCapture: true,
  advancedNetworkCapture: true,
});
Note

The tracePropagationTargets option is key to connecting session replays with backend traces — set it to your API domain to enable full frontend-to-backend distributed tracing. For a complete list of SDK options including privacy controls, custom actions, React error boundaries, and source maps, see the Browser SDK reference.

The Browser SDK also supports masking inputs and text for privacy-sensitive applications, and attaching user information so you can search and filter sessions by user in the ClickStack UI.

Viewing session replays​

Navigate to Client Sessions from the left sidebar in the ClickStack UI (HyperDX). This view lists all captured browser sessions with their duration and event count.

Click the play button on any session to replay it. The replay view shows the reconstructed user experience on the right, with a timeline of browser events — network requests, console logs, and errors — on the left.

Switch between Highlighted and All Events modes to adjust the level of detail shown on the timeline. Errors are annotated in red, and clicking on any event navigates the replay to that point in the session.

From session to trace​

When you select a network request or error in the session timeline, you can click through to the Trace tab to follow the request through your backend services — seeing the associated logs, spans, and database queries that were triggered by that user interaction.

This works because the tracePropagationTargets configuration links browser spans to server spans via the traceparent header, creating a connected distributed trace from the user's click all the way to the database. For a detailed walkthrough of this in practice, including instrumenting both frontend and backend, see Instrumenting your NextJS application with OpenTelemetry and ClickStack.

Drilling from a session replay into backend traces in ClickStack

From trace to session​

The correlation works in the other direction too. When viewing a trace in the Search view, click on it to open the trace detail, then select the Session Replay tab to see exactly what the user was experiencing at the time of that trace. This is especially useful when investigating errors or slow requests — you can start from the backend issue and immediately see the user's perspective.

How session data is stored​

Session replay data is stored in a dedicated hyperdx_sessions table in ClickHouse, separate from logs and traces. Each session event is a row with a Body field containing the event payload and a LogAttributes map storing the event metadata. The Body and LogAttributes columns together hold the details of the actual session events that are used to reconstruct the replay.

For the full table schema information, see Tables and schemas used by ClickStack.

Try it out​

There are two ways to see session replay in action:

Learn more​

  • Session Replay Demo — interactive local demo application with step-by-step instructions
  • Browser SDK Reference — full SDK options, source maps, custom actions, and advanced configuration
  • Search — search syntax for filtering sessions and events
  • Dashboards — build visualizations and dashboards from session and trace data
  • Alerts — set up alerts on errors, latency, and other signals
  • ClickStack Architecture — how ClickHouse, HyperDX, and the OTel collector fit together