Session replay demo

Interactive demo application showing how to instrument a web app for ClickStack session replay

TL;DR

This guide walks through instrumenting a web application for session replay using the ClickStack Browser SDK. Unlike other sample datasets that load pre-generated data, this demo provides an interactive application where you generate session data through your own interactions.

Time required: 10-15 minutes

Overview

The session replay demo application is a documentation explorer built with vanilla JavaScript. It demonstrates how minimal session replay instrumentation can be — one script tag and one initialization call captures all user interactions automatically.

The repository includes two branches:

• main — fully instrumented and ready to use immediately
• pre-instrumented — a clean version without instrumentation, with code comments indicating where to add it

This guide uses the main branch first to see session replay in action, then walks through the instrumentation code so you can apply the same pattern to your own application.

For background on what session replay is and how it fits into ClickStack, see the Session Replay feature page.

Prerequisites

• Docker and Docker Compose installed
• Ports 3000, 4317, 4318, and 8080 available

Running the demo

1. Clone the repository

   git clone https://github.com/ClickHouse/clickstack-session-replay-demo
   cd clickstack-session-replay-demo
   
2. Start ClickStack

   docker-compose up -d clickstack
   
3. Get your API key

   1. Open HyperDX at http://localhost:8080
   2. Create an account or log in if needed
   3. Navigate to Team Settings → API Keys
   4. Copy your Ingestion API Key

   5. Set it as an environment variable:

   export CLICKSTACK_API_KEY='your-api-key-here'
   
4. Start the demo application

   docker-compose --profile demo up demo-app
   

   Ensure you run this command in the same terminal where you exported the CLICKSTACK_API_KEY variable.

   Open http://localhost:3000 in your browser and interact with the app — search for topics, filter by category, view code examples, and bookmark items.

   All interactions are automatically captured by the ClickStack Browser SDK.

5. View your session replay

   Return to HyperDX at http://localhost:8080 and navigate to Client Sessions from the left sidebar.

   You should see your session listed with its duration and event count. Click the ▶️ button to replay it.

   Switch between Highlighted and All Events modes to adjust the level of detail on the timeline.

The instrumentation

The demo application shows how little code is needed to enable session replay. Two additions to the application are all it takes:

1. Include the SDK (app/public/index.html):

<script src="https://unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>

2. Initialize ClickStack (app/public/js/app.js):

window.HyperDX.init({
  url: 'http://localhost:4318',
  apiKey: window.CLICKSTACK_API_KEY,
  service: 'clickhouse-session-replay-demo',
  consoleCapture: true,
  advancedNetworkCapture: true,
});

Everything else is standard application code. The SDK automatically captures all user interactions, console logs, network requests, and errors — no additional instrumentation is needed.

Try it yourself

To instrument the app from scratch, switch to the pre-instrumented branch:

git checkout pre-instrumented

This branch contains the same application without any ClickStack instrumentation. Code comments in app/public/index.html and app/public/js/app.js indicate exactly where to add the two code snippets above. Once added, restart the demo app and your interactions will begin appearing in ClickStack.

Troubleshooting

Sessions not appearing in HyperDX

1. Check the browser console for errors
2. Verify ClickStack is running: docker-compose ps
3. Confirm the API key is set: echo $CLICKSTACK_API_KEY
4. Adjust the time range in the Client Sessions view (try Last 15 minutes)
5. Hard refresh the browser: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows/Linux)

401 Unauthorized errors

The API key isn’t set correctly. Make sure you:

1. Exported it in your terminal: export CLICKSTACK_API_KEY='your-key'
2. Started the demo app in the same terminal where you exported it
3. Got the key from the HyperDX UI (not a randomly generated string)

Cleanup

Stop the services:

docker-compose down

Remove all data:

docker-compose down -v

Learn more

• Session Replay — feature overview, SDK options, and privacy controls
• Browser SDK Reference — full SDK options and advanced configuration
• ClickStack Getting Started — deploy ClickStack and ingest your first data
• All Sample Datasets — other example datasets and guides