> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Session replay demo

> Interactive demo application showing how to instrument a web app for session replay in ClickHouse Observability

> [!NOTE]
>
> The instrumentation examples below use `@clickhouse/clickstack-browser`. The demo repository still bundles the legacy browser SDK; its [SDK migration](https://github.com/ClickHouse/clickstack-session-replay-demo/pull/2) is pending. The clone-and-run workflow uses that bundled SDK until the repository is updated.

> [!NOTE]
>
> **TL;DR**
>
> This 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](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 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](https://clickhouse.com/docs/clickstack/observability/features/session-replay.md) 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

**1. Clone the repository**

```shell theme={null}
git clone https://github.com/ClickHouse/clickstack-session-replay-demo
cd clickstack-session-replay-demo
```

**2. Configure the connection**

Choose your deployment mode:

> [tab] Fully managed
>
> [Beta offering](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)
>
> You need an existing [fully managed service](https://clickhouse.com/docs/clickstack/observability/getting-started.md). 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**.
>
> ![Managed Telemetry showing the masked OTLP HTTP endpoint and API key](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-managed-telemetry.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=e63a2ac2e6ab996d3fc360ebe0f487a5)
>
> 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:
>
> ```shell theme={null}
> 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.

> [tab] Self-managed
>
> You need an existing [self-managed service](https://clickhouse.com/docs/clickstack/self-configured/getting-started/managed.md) and a running ClickStack OpenTelemetry collector connected to it. See [Ingesting with OpenTelemetry](https://clickhouse.com/docs/clickstack/observability/ingesting-data/opentelemetry.md#installing-otel-collector-managed-self-configured) for connection instructions or the [deployment guide](https://clickhouse.com/docs/clickstack/self-configured/deployment/managed.md#start-a-collector-existing) 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](https://github.com/ClickHouse/clickstack-browser#clickstack-versions).
>
> 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.
>
> ```shell theme={null}
> 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.

**3. Start the demo application**

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

```shell theme={null}
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](http://localhost:3000) in your browser and interact with the app — search for topics, filter by category, view code examples, and bookmark items.

![Session replay demo app](https://mintcdn.com/private-7c7dfe99/y4_YksnkJMz9sseb/images/clickstack/session-replay/demo-app.webp?fit=max\&auto=format\&n=y4_YksnkJMz9sseb\&q=85\&s=21b2815a840359893301e889699c4bee)

The browser SDK captures the session and sends it to your configured telemetry endpoint.

**4. 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`.

![Client Sessions selected in the ClickHouse Observability sidebar with a recorded session listed](https://mintcdn.com/private-7c7dfe99/FqnhjwVWZILRZzw7/images/clickstack/session-replay/observability-client-sessions.png?fit=max\&auto=format\&n=FqnhjwVWZILRZzw7\&q=85\&s=ed5efe0ea6bcddb14c4ae9e41383d8ca)

Open your session and select **Play** to replay the recorded interactions.

![Session replay of the Documentation Explorer in ClickHouse Observability](https://mintcdn.com/private-7c7dfe99/FqnhjwVWZILRZzw7/images/clickstack/session-replay/observability-session-replay.png?fit=max\&auto=format\&n=FqnhjwVWZILRZzw7\&q=85\&s=aa1f89b664577233948ca2265b1fc7eb)

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`):**

```html theme={null}
<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`):**

```javascript theme={null}
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](https://clickhouse.com/docs/clickstack/observability/ingesting-data/sdks/browser.md#session-replay-and-privacy) 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:

```shell theme={null}
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:

```shell theme={null}
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

1. Check the browser console for errors
2. Verify the demo app is running: `docker compose ps demo-app`
3. 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.
4. For self-managed, check collector export errors, CORS configuration, and the SDK compatibility requirements above
5. Adjust the time range in the Client Sessions view (try **Last 15 minutes**)
6. 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 `CLICKSTACK_API_KEY` in your terminal using the value for your deployment mode
2. Started the demo app in the **same terminal** where you exported it
3. 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:

```bash theme={null}
docker compose stop demo-app
```

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

## Learn more

* [Session Replay](https://clickhouse.com/docs/clickstack/observability/features/session-replay.md) — feature overview, SDK options, and privacy controls
* [Browser SDK Reference](https://clickhouse.com/docs/clickstack/observability/ingesting-data/sdks/browser.md) — full SDK options and advanced configuration
* [Fully managed Getting Started](https://clickhouse.com/docs/clickstack/observability/getting-started.md) — connect your first data source
* [Self-managed getting started](https://clickhouse.com/docs/clickstack/self-configured/getting-started/managed.md) — connect your collector and ingest your first data
* [All Sample Datasets](https://clickhouse.com/docs/clickstack/observability/example-datasets) — other example datasets and guides