> ## 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.

# Chrome extension

> Capture session replay and RUM data for fully managed ClickHouse Observability using the HyperDX Chrome extension

> [tab] Fully managed
>
> [Beta offering](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)
>
> > [!NOTE]
> >
> > **TL;DR**
> >
> > This guide shows how to inject the browser SDK into any website using the [HyperDX Chrome extension](https://github.com/kyreddie/hyperdx-chrome-extension). No changes to the target application's source code are required — configure the extension once, browse the site, and view session replays in ClickHouse Observability.
> >
> > Time required: 10-15 minutes
>
> ## Overview
>
> The [HyperDX Chrome extension](https://github.com/kyreddie/hyperdx-chrome-extension) injects the [@hyperdx/browser](https://github.com/hyperdxio/hyperdx-js) SDK into pages you visit. It is useful when you want to debug session replay, RUM, or trace propagation on a site without modifying its codebase — for example, a third-party application, a production build, or a local dev server with strict Content Security Policy (CSP).
>
> The SDK is bundled inside the extension (\~480 KB), so pages do not need to load scripts from a CDN at runtime. The extension tries external `chrome-extension://` script injection first and falls back to inline injection when CSP blocks extension-origin scripts.
>
> Unlike the [Session Replay Demo](https://clickhouse.com/docs/clickstack/observability/example-datasets/session-replay.md), which instruments a demo application you control, this approach instruments supported pages you open in Chrome; some pages restrict script injection. You generate session data by interacting with the site as a normal user.
>
> For background on session replay and how it fits into ClickHouse Observability, see the [Session Replay](https://clickhouse.com/docs/clickstack/observability/features/session-replay.md) feature page.
>
> ## Prerequisites
>
> * Google Chrome or a Chromium-based browser (Edge, Brave, etc.)
> * An existing fully managed ClickHouse Observability service. See the [fully managed Getting Started guide](https://clickhouse.com/docs/clickstack/observability/getting-started.md).
>
> ## Running the demo
>
> **1. Clone the extension repository**
>
> ```shell theme={null}
> git clone https://github.com/kyreddie/hyperdx-chrome-extension
> cd hyperdx-chrome-extension
> ```
>
> **2. Install the extension**
>
> 1. Open Chrome and go to `chrome://extensions`.
> 2. Enable **Developer mode** (top right).
> 3. Click **Load unpacked**.
> 4. Select the `hyperdx-chrome-extension` directory you cloned.
>
> The extension appears in your toolbar as **HyperDX Browser Extension**.
>
> **3. Get your connection details**
>
> Open your ClickHouse Observability service and go to **Team Settings → Managed Telemetry**. Copy the **OTLP HTTP endpoint** and **API key** for the extension configuration.
>
> Use the full HTTPS endpoint provided, including its port, without appending `/v1/logs` or `/v1/traces`.
>
> ![Managed Telemetry in Team Settings 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)
>
> **4. Configure the extension**
>
> Click the **HyperDX Browser Extension** icon in the Chrome toolbar and fill in the settings:
>
> | Field | Fully managed setting | Notes |
> | - | - | - |
> | **Enable HyperDX Monitoring** | On | Master toggle for injection |
> | **Service Name** | `my-frontend-app` | Required — identifies the service in ClickHouse Observability |
> | **API Key** | Your managed telemetry API key | Required; copy from **Team Settings → Managed Telemetry** |
> | **Collector URL** | Your managed telemetry OTLP HTTP endpoint | Replace the extension’s default URL with the endpoint from **Managed Telemetry** |
> | **Environment** | `development` | Optional — sets `deployment.environment` resource attribute |
> | **Trace Propagation Targets** | `/api\.myapp\.domain/i, /localhost/i` | Optional — comma-separated JavaScript regex patterns for trace header propagation |
> | **Only inject on matching URLs** | Off | Enable to limit which sites are instrumented |
> | **Capture console logs** | Off | Enable to forward browser console output |
> | **Advanced network capture** | Off | Enable for detailed network request capture |
>
> Click **Save Configuration**, then reload any tabs you want to instrument.
>
> **5. Browse a site and generate a session**
>
> Open any website or local application in Chrome — for example, [http://localhost:3000](http://localhost:3000) for a frontend dev server.
>
> Interact with the page normally: click links, submit forms, trigger errors, and navigate between views. The extension injects the Browser SDK automatically on each page load when configuration is valid.
>
> **6. View your session replay**
>
> In your ClickHouse Observability service, open **Client Sessions** from the left sidebar. Choose a time range that includes your browsing activity.
>
> 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.
>
> ## URL filtering
>
> By default, the extension injects the SDK on every page you visit while monitoring is enabled. To restrict injection to specific sites, turn on **Only inject on matching URLs** and add one pattern per line (or comma-separated):
>
> | Pattern | Matches |
> | - | - |
> | `http://homedepot.com/*` | HTTP only on `homedepot.com` |
> | `*://homedepot.com/*` | HTTP and HTTPS on `homedepot.com` |
> | `*://*.homedepot.com/*` | Subdomains such as `www.homedepot.com` |
> | `https://localhost:3000/*` | Local dev server on port 3000 |
>
> Reload the tab after saving URL patterns.
>
> ## Verify injection
>
> Open DevTools on a monitored page (**Console** tab), reload the page, and look for:
>
> ```text theme={null}
> [HyperDX Extension] Configuration valid, injecting HyperDX
> [HyperDX Extension] Injected via extension scripts
> [HyperDX Extension] HyperDX initialized
> ```
>
> If extension-origin scripts are blocked by CSP, the extension logs a fallback message and retries with inline injection.
>
> ## Troubleshooting
>
> > [accordion] Sessions not appearing in ClickHouse Observability
> >
> > 1. Check the browser console for `[HyperDX Extension]` log messages or errors
> > 2. Confirm **Enable HyperDX Monitoring** is on and **Service Name** is set
> > 3. Confirm **Collector URL** and **API Key** match **Team Settings → Managed Telemetry** in your service
> > 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)
>
> > [accordion] chrome-extension://invalid/ errors
> >
> > Reload the extension at `chrome://extensions`, then hard-refresh the tab. This happens when the extension was updated or reloaded while tabs were still open.
>
> > [accordion] No injection on a site
> >
> > 1. Check that monitoring is enabled and a service name is configured
> > 2. If **Only inject on matching URLs** is on, confirm the current page URL matches one of your patterns
> > 3. Some sites block both extension-origin and inline script injection via CSP — injection may not be possible on those pages
>
> > [accordion] HyperDX: Missing apiKey in console
> >
> > Enter the API key from **Team Settings → Managed Telemetry**, save the configuration, and reload the monitored page. Fully managed ingestion requires this key.
>
> ## Privacy
>
> The extension injects observability code into pages you visit. Use it only on sites you are allowed to debug. Don't share API keys or commit them to version control.
>
> ## 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
> * [Session Replay Demo](https://clickhouse.com/docs/clickstack/observability/example-datasets/session-replay.md) — instrument a demo application from source code
> * [Fully managed Getting Started](https://clickhouse.com/docs/clickstack/observability/getting-started.md) — connect your service and ingest your first data
> * [HyperDX Chrome extension on GitHub](https://github.com/kyreddie/hyperdx-chrome-extension) — source code and issue tracker

> [tab] Self-managed
>
> Use the extension with an existing OpenTelemetry collector that sends data to your self-managed ClickHouse Observability service.
>
> ## Overview
>
> The [HyperDX Chrome extension](https://github.com/kyreddie/hyperdx-chrome-extension) injects the [@hyperdx/browser](https://github.com/hyperdxio/hyperdx-js) SDK into pages you visit. It is useful when you want to debug session replay, RUM, or trace propagation on a site without modifying its codebase — for example, a third-party application, a production build, or a local dev server with strict Content Security Policy (CSP).
>
> The SDK is bundled inside the extension (\~480 KB), so pages do not need to load scripts from a CDN at runtime. The extension tries external `chrome-extension://` script injection first and falls back to inline injection when CSP blocks extension-origin scripts.
>
> Unlike the [Session Replay Demo](https://clickhouse.com/docs/clickstack/observability/example-datasets/session-replay.md), which instruments a demo application you control, this approach instruments supported pages you open in Chrome; some pages restrict script injection. You generate session data by interacting with the site as a normal user.
>
> For background on session replay and how it works, see the [Session Replay](https://clickhouse.com/docs/clickstack/observability/features/session-replay.md) feature page.
>
> ## Prerequisites
>
> * Google Chrome or a Chromium-based browser (Edge, Brave, etc.)
> * An existing self-managed ClickHouse Observability service and a running ingestion collector. If needed, follow the [collector setup guide](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#configuring-the-collector-self-configured) first.
> * The collector’s OTLP HTTP endpoint, reachable from your browser, and its authentication token if configured.
>
> ## Running the demo
>
> **1. Clone the extension repository**
>
> ```shell theme={null}
> git clone https://github.com/kyreddie/hyperdx-chrome-extension
> cd hyperdx-chrome-extension
> ```
>
> **2. Install the extension**
>
> 1. Open Chrome and go to `chrome://extensions`.
> 2. Enable **Developer mode** (top right).
> 3. Click **Load unpacked**.
> 4. Select the `hyperdx-chrome-extension` directory you cloned.
>
> The extension appears in your toolbar as **HyperDX Browser Extension**.
>
> **3. Get your collector connection details**
>
> Use the OTLP HTTP endpoint of your running collector, for example `http://localhost:4318` when the collector runs on the same machine as your browser. For a remote collector, use its browser-accessible HTTPS URL. Do not append `/v1/logs` or `/v1/traces`.
>
> If your collector uses `OTLP_AUTH_TOKEN`, use that token as the extension's **API Key**, without adding a `Bearer` prefix. These are the collector's ingestion credentials, not your ClickHouse database username and password. See [Securing the collector](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md#securing-the-collector-self-configured).
>
> **4. Configure the extension**
>
> Click the **HyperDX Browser Extension** icon in the Chrome toolbar and fill in the settings:
>
> | Field | Self-managed setting | Notes |
> | - | - | - |
> | **Enable HyperDX Monitoring** | On | Master toggle for injection |
> | **Service Name** | `my-frontend-app` | Required — identifies the service in ClickHouse Observability |
> | **API Key** | Your collector’s authentication token | Use the `OTLP_AUTH_TOKEN` value if configured |
> | **Collector URL** | Your collector’s OTLP HTTP endpoint | Replace the extension’s default URL; use `http://localhost:4318` only for a collector on your machine |
> | **Environment** | `development` | Optional — sets `deployment.environment` resource attribute |
> | **Trace Propagation Targets** | `/api\.myapp\.domain/i, /localhost/i` | Optional — comma-separated JavaScript regex patterns for trace header propagation |
> | **Only inject on matching URLs** | Off | Enable to limit which sites are instrumented |
> | **Capture console logs** | Off | Enable to forward browser console output |
> | **Advanced network capture** | Off | Enable for detailed network request capture |
>
> Click **Save Configuration**, then reload any tabs you want to instrument.
>
> ![HyperDX Chrome extension configuration popup with local ClickStack settings](https://mintcdn.com/private-7c7dfe99/LCIbqddLfKHZZnfk/images/clickstack/chrome-extension/extension-config.png?fit=max\&auto=format\&n=LCIbqddLfKHZZnfk\&q=85\&s=2eba96be74ec050a591310aa999536cb)
>
> The screenshot above shows a typical local setup: monitoring enabled, service name set, collector pointed at `http://localhost:4318`, and trace propagation limited to API and localhost URLs.
>
> **5. Browse a site and generate a session**
>
> Open any website or local application in Chrome — for example, [http://localhost:3000](http://localhost:3000) for a frontend dev server.
>
> Interact with the page normally: click links, submit forms, trigger errors, and navigate between views. The extension injects the Browser SDK automatically on each page load when configuration is valid.
>
> **6. View your session replay**
>
> Open your self-managed ClickHouse Observability service in ClickHouse Cloud and select **Client Sessions** from the left sidebar. Choose a time range that includes your browsing activity.
>
> 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.
>
> ## URL filtering
>
> By default, the extension injects the SDK on every page you visit while monitoring is enabled. To restrict injection to specific sites, turn on **Only inject on matching URLs** and add one pattern per line (or comma-separated):
>
> | Pattern | Matches |
> | - | - |
> | `http://homedepot.com/*` | HTTP only on `homedepot.com` |
> | `*://homedepot.com/*` | HTTP and HTTPS on `homedepot.com` |
> | `*://*.homedepot.com/*` | Subdomains such as `www.homedepot.com` |
> | `https://localhost:3000/*` | Local dev server on port 3000 |
>
> Reload the tab after saving URL patterns.
>
> ## Verify injection
>
> Open DevTools on a monitored page (**Console** tab), reload the page, and look for:
>
> ```text theme={null}
> [HyperDX Extension] Configuration valid, injecting HyperDX
> [HyperDX Extension] Injected via extension scripts
> [HyperDX Extension] HyperDX initialized
> ```
>
> If extension-origin scripts are blocked by CSP, the extension logs a fallback message and retries with inline injection.
>
> ## Troubleshooting
>
> > [accordion] Sessions not appearing in ClickStack UI
> >
> > 1. Check the browser console for `[HyperDX Extension]` log messages or errors
> > 2. Confirm **Enable HyperDX Monitoring** is on and **Service Name** is set
> > 3. Verify the collector is running, its OTLP HTTP endpoint is reachable from your browser, and the API key matches its authentication token
> > 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)
>
> > [accordion] chrome-extension://invalid/ errors
> >
> > Reload the extension at `chrome://extensions`, then hard-refresh the tab. This happens when the extension was updated or reloaded while tabs were still open.
>
> > [accordion] No injection on a site
> >
> > 1. Check that monitoring is enabled and a service name is configured
> > 2. If **Only inject on matching URLs** is on, confirm the current page URL matches one of your patterns
> > 3. Some sites block both extension-origin and inline script injection via CSP — injection may not be possible on those pages
>
> > [accordion] HyperDX: Missing apiKey in console
> >
> > If your collector requires authentication, enter its token in **API Key**, save the configuration, and reload the monitored page. Check browser network requests and collector logs for export errors rather than relying on the injection message alone.
>
> ## Privacy
>
> The extension injects observability code into pages you visit. Use it only on sites you are allowed to debug. Don't share API keys or commit them to version control.
>
> ## 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
> * [Session Replay Demo](https://clickhouse.com/docs/clickstack/observability/example-datasets/session-replay.md) — instrument a demo application from source code
> * [Getting started with Self-managed](https://clickhouse.com/docs/clickstack/self-configured/getting-started/managed.md) — set up your service and ingest your first data
> * [HyperDX Chrome extension on GitHub](https://github.com/kyreddie/hyperdx-chrome-extension) — source code and issue tracker