Add ClickStack Chrome extension sample dataset guide by kyreddie · Pull Request #6345 · ClickHouse/clickhouse-docs

kyreddie · 2026-06-04T14:12:33Z

Summary

Add a new ClickStack sample dataset guide for the HyperDX Chrome extension, which injects the Browser SDK into any website for session replay and RUM without application code changes.
Include an extension configuration screenshot and link the page from the sample datasets index.

Test plan

Previewed locally with yarn copy-clickhouse-repo-docs, yarn autogenerate-table-of-contents, and yarn start
Verified page renders at /docs/use-cases/observability/clickstack/example-datasets/chrome-extension
Confirmed screenshot and VerticalStepper steps display correctly
Checked sample datasets index links to the new page

Made with Cursor

Note

Low Risk
Documentation-only changes with no runtime, auth, or data-path impact.

Overview
Adds a Chrome extension sample-dataset guide that walks through installing the HyperDX extension, pointing it at a local or cloud ClickStack collector, browsing any site to generate RUM/session data, and viewing replays in HyperDX—without changing the target app’s code. The page mirrors other example guides (VerticalStepper, config table, URL filters, DevTools verification, troubleshooting, privacy) and includes a configuration screenshot.

The sample datasets landing table gains a row linking to chrome-extension.md.

^{Reviewed by Cursor Bugbot for commit 0872cbd. Bugbot is set up for automated code reviews on this repo. Configure here.}

Document installing and configuring the HyperDX Chrome extension for session replay and RUM, including collector setup and extension UI screenshot. Co-authored-by: Cursor <cursoragent@cursor.com>

vercel · 2026-06-04T14:12:38Z

Someone is attempting to deploy a commit to the ClickHouse Team on Vercel.

A member of the Team first needs to authorize it.

Copilot

Pull request overview

Adds a new ClickStack “sample dataset” guide showing how to generate session replay/RUM data by injecting the HyperDX Browser SDK via a Chrome extension, and links it from the example-datasets index.

Changes:

Added a new MDX guide page for the HyperDX Chrome extension workflow (setup, configuration, verification, troubleshooting, privacy).
Added a new entry in the sample datasets index linking to the new guide.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 4 comments.

File	Description
docs/use-cases/observability/clickstack/example-datasets/index.md	Adds a table row linking to the new Chrome extension guide.
docs/use-cases/observability/clickstack/example-datasets/chrome-extension.md	New guide documenting the Chrome extension-based instrumentation flow, including screenshot and stepper-based setup steps.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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


Blargian · 2026-06-04T15:49:57Z

+
+- Google Chrome or a Chromium-based browser (Edge, Brave, etc.)
+- [Docker](https://docs.docker.com/get-docker/) installed, if running ClickStack locally
+- Ports 4317, 4318, and 8080 available (for local ClickStack)


@kyreddie to confirm if this is a valid suggestion or not

+### Start ClickStack {#start-clickstack}
+
+If you already have a ClickStack or HyperDX ingestion endpoint, skip to [Configure the extension](#configure-extension).
+
+For a local ClickStack stack, start the OpenTelemetry collector. Replace `{{CLICKHOUSE_ENDPOINT}}` and `{{CLICKHOUSE_PASSWORD}}` with your ClickHouse connection details:
+
+```shell
+export CLICKHOUSE_ENDPOINT={{CLICKHOUSE_ENDPOINT}}
+export CLICKHOUSE_PASSWORD={{CLICKHOUSE_PASSWORD}}
+
+docker run \
+  -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
+  -e CLICKHOUSE_USER=default \
+  -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
+  -p 8080:8080 \
+  -p 4317:4317 \
+  -p 4318:4318 \
+  clickhouse/clickstack-otel-collector:latest
+```
+
+Open HyperDX at [http://localhost:8080](http://localhost:8080) to confirm the UI is running.
+
+For a full local deployment with ClickHouse and HyperDX UI, see [Getting started with ClickStack](/use-cases/observability/clickstack/getting-started/oss).
+


Specify `text` language for the fenced code block in verify injection. Co-authored-by: Cursor <cursoragent@cursor.com>

CLAassistant · 2026-06-04T14:22:50Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ kyreddie
❌ Eddie Kyriacou

Eddie Kyriacou seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

vercel · 2026-06-04T15:11:47Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clickhouse-docs	Ready	Preview	Jun 4, 2026 7:40pm

Blargian

LGTM as is, left a few minor suggestions

Blargian · 2026-06-04T15:38:00Z

+
+Click **Save Configuration**, then reload any tabs you want to instrument.
+
+<Image img={extension_config} alt="HyperDX Chrome extension configuration popup with local ClickStack settings" size="md" />


Suggested change

<Image img={extension_config} alt="HyperDX Chrome extension configuration popup with local ClickStack settings" size="md" />

<Image img={extension_config} alt="HyperDX Chrome extension configuration popup with local ClickStack settings" size="sm" />

The screenshot shows quite large for me even at md - might be better at sm

Blargian · 2026-06-04T15:46:45Z

+### Sessions not appearing in HyperDX {#sessions-not-appearing}
+
+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 ClickStack is running and the collector URL is correct (e.g. `http://localhost:4318`)
+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)
+
+### `chrome-extension://invalid/` errors {#extension-invalid}
+
+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.
+
+### No injection on a site {#no-injection}
+
+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
+
+### `HyperDX: Missing apiKey` in console {#missing-api-key}
+
+Expected when the API key field is empty. Add an ingestion API key from HyperDX for cloud endpoints, or ignore if your self-hosted collector accepts unauthenticated local traffic.


I'm wondering if we shouldn't make these detail drop downs rather than H3s, similar to how we have it on https://www.clickhouse.com/docs/use-cases/observability/clickstack/faq

That way the user just sees the information for the item they expand

Suggested change

### Sessions not appearing in HyperDX {#sessions-not-appearing}

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 ClickStack is running and the collector URL is correct (e.g. `http://localhost:4318`)

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)

### `chrome-extension://invalid/` errors {#extension-invalid}

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.

### No injection on a site {#no-injection}

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

### `HyperDX: Missing apiKey` in console {#missing-api-key}

Expected when the API key field is empty. Add an ingestion API key from HyperDX for cloud endpoints, or ignore if your self-hosted collector accepts unauthenticated local traffic.

<details>

<summary>Sessions not appearing in HyperDX</summary>

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 ClickStack is running and the collector URL is correct (e.g. `http://localhost:4318`)

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)

</details>

<details>

<summary>`chrome-extension://invalid/` errors </summary>

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.

</details>

<details>

<summary>No injection on a site</summary>

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

4.

</details>

<details>

<summary>`HyperDX: Missing apiKey` in console </summary>

Expected when the API key field is empty. Add an ingestion API key from HyperDX for cloud endpoints, or ignore if your self-hosted collector accepts unauthenticated local traffic.

</details>

…e-extension.md Co-authored-by: Shaun Struwig <41984034+Blargian@users.noreply.github.com>

mintlify · 2026-06-04T19:54:05Z

Docs PR opened: ClickHouse/mintlify-docs-dev#127

Added a ClickStack sample dataset guide for using the HyperDX Chrome extension to instrument any website for session replay.

Add ClickStack Chrome extension sample dataset guide

ce8dd6a

Document installing and configuring the HyperDX Chrome extension for session replay and RUM, including collector setup and extension UI screenshot. Co-authored-by: Cursor <cursoragent@cursor.com>

kyreddie requested a review from a team as a code owner June 4, 2026 14:12

kyreddie requested a review from Copilot June 4, 2026 14:15

Copilot started reviewing on behalf of kyreddie June 4, 2026 14:15 View session

Copilot AI reviewed Jun 4, 2026

View reviewed changes

Fix markdownlint MD040 on console log code block

764bc2a

Specify `text` language for the fenced code block in verify injection. Co-authored-by: Cursor <cursoragent@cursor.com>

Blargian self-assigned this Jun 4, 2026

vercel Bot deployed to Preview – clickhouse-docs June 4, 2026 15:24 View deployment

Blargian approved these changes Jun 4, 2026

View reviewed changes

kyreddie and others added 2 commits June 4, 2026 12:01

Update docs/use-cases/observability/clickstack/example-datasets/chrom…

cea711f

…e-extension.md Co-authored-by: Shaun Struwig <41984034+Blargian@users.noreply.github.com>

Update docs/use-cases/observability/clickstack/example-datasets/chrom…

c3d1b8d

…e-extension.md Co-authored-by: Shaun Struwig <41984034+Blargian@users.noreply.github.com>

vercel Bot deployed to Preview – clickhouse-docs June 4, 2026 19:09 View deployment

Update docs/use-cases/observability/clickstack/example-datasets/chrom…

0872cbd

…e-extension.md Co-authored-by: Shaun Struwig <41984034+Blargian@users.noreply.github.com>

vercel Bot deployed to Preview – clickhouse-docs June 4, 2026 19:40 View deployment

Blargian merged commit aaa337d into ClickHouse:main Jun 4, 2026
11 of 16 checks passed

mintlify Bot mentioned this pull request Jun 4, 2026

docs: add ClickStack Chrome extension sample dataset guide ClickHouse/mintlify-docs-dev#127

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add ClickStack Chrome extension sample dataset guide#6345

Add ClickStack Chrome extension sample dataset guide#6345
Blargian merged 5 commits into
ClickHouse:mainfrom
kyreddie:docs/clickstack-chrome-extension

kyreddie commented Jun 4, 2026 •

edited by cursor Bot

Loading

Uh oh!

vercel Bot commented Jun 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Blargian Jun 4, 2026

Uh oh!

Uh oh!

CLAassistant commented Jun 4, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 4, 2026 •

edited

Loading

Uh oh!

Blargian left a comment

Uh oh!

Blargian Jun 4, 2026

Uh oh!

Blargian Jun 4, 2026

Uh oh!

Uh oh!

Uh oh!

mintlify Bot commented Jun 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		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.


		Click Save Configuration, then reload any tabs you want to instrument.

		<Image img={extension_config} alt="HyperDX Chrome extension configuration popup with local ClickStack settings" size="md" />

Conversation

kyreddie commented Jun 4, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

vercel Bot commented Jun 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Blargian Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

CLAassistant commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Blargian left a comment

Choose a reason for hiding this comment

Uh oh!

Blargian Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

Blargian Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mintlify Bot commented Jun 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kyreddie commented Jun 4, 2026 •

edited by cursor Bot

Loading

CLAassistant commented Jun 4, 2026 •

edited

Loading

vercel Bot commented Jun 4, 2026 •

edited

Loading