Session Replay Demo

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/observability/clickstack/example-datasets/session-replay.md)

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[​](#overview "Direct link to Overview")

The [session replay demo application](https://github.com/ClickHouse/clickstack-session-replay-demo) 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](/docs/use-cases/observability/clickstack/session-replay) feature page.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

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

## Running the demo[​](#running-the-demo "Direct link to Running the demo")

Clone the repository

### Clone the repository[​](#clone-repository "Direct link to Clone the repository")

```
git clone https://github.com/ClickHouse/clickstack-session-replay-demo
cd clickstack-session-replay-demo
```

Start ClickStack

### Start ClickStack[​](#start-clickstack "Direct link to Start ClickStack")

```
docker-compose up -d clickstack
```

Get your API key

### Get your API key[​](#get-api-key "Direct link to 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'
```

Start the demo application

### Start the demo application[​](#start-demo-app "Direct link to Start the demo application")

```
docker-compose --profile demo up demo-app
```

Note

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.

View your session replay

### View your session replay[​](#view-session-replay "Direct link to 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[​](#instrumentation "Direct link to 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/[email protected]/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[​](#try-it-yourself "Direct link to 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[​](#troubleshooting "Direct link to Troubleshooting")

### Sessions not appearing in HyperDX[​](#sessions-not-appearing "Direct link to 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[​](#401-errors "Direct link to 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[​](#cleanup "Direct link to Cleanup")

Stop the services:

```
docker-compose down
```

Remove all data:

```
docker-compose down -v
```

## Learn more[​](#learn-more "Direct link to Learn more")

- [Session Replay](/docs/use-cases/observability/clickstack/session-replay) — feature overview, SDK options, and privacy controls
- [Browser SDK Reference](/docs/use-cases/observability/clickstack/sdks/browser) — full SDK options and advanced configuration
- [ClickStack Getting Started](/docs/use-cases/observability/clickstack/getting-started) — deploy ClickStack and ingest your first data
- [All Sample Datasets](/docs/use-cases/observability/clickstack/sample-datasets) — other example datasets and guides

- [Overview](#overview)- [Prerequisites](#prerequisites)- [Running the demo](#running-the-demo)
      - [Clone the repository](#clone-repository)- [Start ClickStack](#start-clickstack)- [Get your API key](#get-api-key)- [Start the demo application](#start-demo-app)- [View your session replay](#view-session-replay)- [The instrumentation](#instrumentation)
        - [Try it yourself](#try-it-yourself)- [Troubleshooting](#troubleshooting)
          - [Sessions not appearing in HyperDX](#sessions-not-appearing)- [401 Unauthorized errors](#401-errors)- [Cleanup](#cleanup)- [Learn more](#learn-more)

Was this page helpful?