Session replay demo

The instrumentation examples below use @clickhouse/clickstack-browser. The demo repository still bundles the legacy browser SDK; its SDK migration is pending. The clone-and-run workflow uses that bundled SDK until the repository is updated.

TL;DRThis guide walks through instrumenting a web application for session replay using the browser SDK and either fully managed or self-managed ClickHouse Observability. 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 capture 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 installed and running, with Docker Compose available
Port 3000 available for the demo app
An existing fully managed or self-managed ClickHouse Observability service
Network access from your browser to the telemetry endpoint configured below

Running the demo

Clone the repository

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

Configure the connection

Choose your deployment mode:

Fully managed
Self-managed

You need an existing fully managed service. ClickHouse provides the ingestion collector.In your ClickHouse Observability service, open Team Settings → Data → Managed Telemetry and copy the OTLP HTTP endpoint and API key.Set CLICKSTACK_UI_URL to your managed service’s UI URL. To open replays directly, copy the browser URL from Client Sessions. Replace the placeholders below with your connection details, then run these commands in your terminal:

export CLICKSTACK_OTEL_ENDPOINT='https://YOUR_OTEL_ENDPOINT:4318'
export CLICKSTACK_API_KEY='Bearer YOUR_API_KEY'
export CLICKSTACK_UI_URL='YOUR_OBSERVABILITY_UI_URL'

Keep the https:// prefix and omit signal paths such as /v1/traces. Include the Bearer prefix for fully managed ingestion, as shown above.CLICKSTACK_UI_URL controls the demo’s Open Observability links; it is separate from the telemetry ingestion endpoint.The server passes the telemetry endpoint and API key to the browser SDK. The ingestion key is visible in the browser, so use a test service for this demo.

You need an existing self-managed service and a running ClickStack OpenTelemetry collector connected to it. See Ingesting with OpenTelemetry for connection instructions or the deployment guide to start a collector.The collector’s OTLP HTTP endpoint must be reachable from your browser, with CORS allowing http://localhost:3000. The UI must support the new SDK’s session.id attribute in Client Sessions; see the SDK compatibility requirements.Set CLICKSTACK_OTEL_ENDPOINT to your collector’s OTLP HTTP endpoint, without a signal path such as /v1/traces. Set CLICKSTACK_UI_URL to the Client Sessions URL copied from your self-managed service’s UI.

export CLICKSTACK_OTEL_ENDPOINT='https://YOUR_COLLECTOR_HOST:4318'
export CLICKSTACK_API_KEY='YOUR_COLLECTOR_TOKEN'
export CLICKSTACK_UI_URL='YOUR_CLIENT_SESSIONS_URL'

Use the authentication token configured on your collector’s receiver. For a ClickStack collector secured with OTLP_AUTH_TOKEN, use that value without a Bearer prefix. If your receiver does not require authentication, set CLICKSTACK_API_KEY to an empty string. Do not use your ClickHouse database password here.The ingestion token is passed to the browser SDK and is visible in the browser. The collector’s ClickHouse database credentials remain on the collector.

Start the demo application

From the repository directory, run this command in the same terminal where you exported the connection variables:

docker compose --profile demo up --build --no-deps demo-app

--no-deps starts only the demo app, using your configured telemetry endpoint. It does not start the local ClickStack service bundled with the repository.Open http://localhost:3000 in your browser and interact with the app — search for topics, filter by category, view code examples, and bookmark items.The browser SDK captures the session and sends it to your configured telemetry endpoint.

View your session replay

Select Open Observability in the demo, then open Client Sessions in your service and select a time range covering your test, such as Last 15 minutes. Find the anonymous session matching the time you used the demo. The SDK records it under the service name clickhouse-session-replay-demo.Open your session and select Play to replay the recorded interactions.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. The examples below use the new ClickStack Browser SDK: 1. Include the SDK (app/public/index.html):

<script src="https://cdn.jsdelivr.net/npm/@clickhouse/clickstack-browser@1.0.0/dist/clickstack.iife.js"></script>

2. Initialize the browser SDK (app/public/js/app.js):

window.ClickStack.init({
  endpoint: window.CLICKSTACK_CONFIG.endpoint,
  apiKey: window.CLICKSTACK_CONFIG.apiKey,
  serviceName: 'clickhouse-session-replay-demo',
  console: 'debug',
});

app/server.js supplies window.CLICKSTACK_CONFIG from the CLICKSTACK_OTEL_ENDPOINT, CLICKSTACK_API_KEY, and CLICKSTACK_UI_URL environment variables. The SDK uses the endpoint and API key; the demo links use the UI URL. The SDK captures session replay, console logs, network requests, and errors without changing the application’s business logic. Text and input values are masked by default. See the Browser SDK privacy controls before changing masking settings.

Try it yourself

To instrument the app from scratch, stop the running demo with Ctrl+C, then switch to the pre-instrumented branch:

git checkout pre-instrumented

This branch contains the same application without the browser SDK enabled. Code comments in app/public/index.html and app/public/js/app.js indicate where to add the two snippets above. Keep the connection variables configured earlier, then rebuild and start the app:

docker compose --profile demo up --build --no-deps demo-app

Reload the demo in your browser and interact with it to generate a new session.

Troubleshooting

Sessions not appearing

Check the browser console for errors
Verify the demo app is running: docker compose ps demo-app
Confirm CLICKSTACK_OTEL_ENDPOINT and CLICKSTACK_API_KEY are set in the terminal used to start the app. If you change them, rerun the startup command and reload the browser tab.
For self-managed, check collector export errors, CORS configuration, and the SDK compatibility requirements above
Adjust the time range in the Client Sessions view (try Last 15 minutes)
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:

Exported CLICKSTACK_API_KEY in your terminal using the value for your deployment mode
Started the demo app in the same terminal where you exported it
For fully managed, used the ingestion API key from Team Settings → Data → Managed Telemetry with a Bearer prefix. For self-managed, used your collector’s receiver token without that prefix.

Cleanup

Close the demo browser tabs to stop browser telemetry, and press Ctrl+C in the terminal running the app. To stop it from another terminal, run this command from the repository directory:

docker compose stop demo-app

This stops the local app; telemetry already ingested into your service remains there.

Learn more

Session Replay — feature overview, SDK options, and privacy controls
Browser SDK Reference — full SDK options and advanced configuration
Fully managed Getting Started — connect your first data source
Self-managed getting started — connect your collector and ingest your first data
All Sample Datasets — other example datasets and guides

Introduction

Features

Administration

Guides

Integration partners

Self-managed

Overview

Prerequisites

Running the demo

The instrumentation

Try it yourself

Troubleshooting

Sessions not appearing

401 Unauthorized errors

Cleanup

Learn more

​Overview

​Prerequisites

​Running the demo

​The instrumentation

​Try it yourself

​Troubleshooting

​Sessions not appearing

​401 Unauthorized errors

​Cleanup

​Learn more

Overview

Prerequisites

Running the demo

The instrumentation

Try it yourself

Troubleshooting

Sessions not appearing

401 Unauthorized errors

Cleanup

Learn more