# HyperDX: a ClickHouse-native observability UI for logs, traces and session replays

> HyperDX is an MIT-licensed TypeScript front end that puts logs, traces, metrics, session replays and errors over any ClickHouse cluster. It is the UI layer of ClickStack, and it is most useful to teams already storing telemetry in ClickHouse.

**hyperdxio/hyperdx** — Resolve production issues, fast. An open source observability platform unifying session replays, logs, metrics, traces and errors powered by ClickHouse and OpenTelemetry.

- Repository: https://github.com/hyperdxio/hyperdx
- Website: https://hyperdx.io/
- Stars: 9,919 · Forks: 481
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/hyperdxio-hyperdx

## The problem HyperDX addresses: telemetry in ClickHouse with no usable front end

ClickHouse is a fast column store, and a lot of teams end up with logs or traces inside it because the storage cost is manageable at volume. What they usually do not have is a search interface. The README frames the project as "imagine Kibana, for ClickHouse", which is a fair summary of the gap: the database can answer the query, but nobody on the on-call rotation wants to write SQL at 3am to find out which deploy broke checkout.

HyperDX targets that gap. It is a web UI, an API and an alerting task that sit on top of an existing ClickHouse cluster. The stated audience is engineers debugging production, not a dedicated observability platform team. The README's motivation section makes the positioning explicit: existing tools are expensive at terabyte scale, need full-time SREs to operate, and force you to hop between separate products for logs, session replay, APM and exceptions. HyperDX's answer is one interface over one database you already pay for.

That framing also tells you who it is not for. If you have no ClickHouse cluster, HyperDX is not a standalone product you install and forget; the README's own quickstart bundles ClickHouse, HyperDX, an OpenTelemetry Collector and MongoDB into a single container precisely because the UI is useless without the database behind it.

## How HyperDX works: schema-agnostic queries over your ClickHouse tables

The architecture visible in the repository is a set of services, not a single binary. The docker-compose.yml defines four: a MongoDB instance holding application state (users, dashboards, alerts, saved searches), an OpenTelemetry Collector that receives telemetry and writes it into ClickHouse, the app itself serving the UI and API, and the ClickHouse server. The collector talks to ClickHouse over the native protocol at tcp://ch-server:9000, and it registers with the app through OPAMP_SERVER_URL, which is how the UI learns about collector configuration.

The design decision that matters most is schema agnosticism. HyperDX does not require you to adopt its table layout. The README states it "works on top of your existing ClickHouse schema", which means the app maps your columns to its concepts through configuration rather than migration. That is the opposite of most observability vendors, who own the storage format and charge you for the privilege. The trade-off is real: you take on the job of telling HyperDX which column is the timestamp, which is the service name, and which holds the body, and if your schema is inconsistent across services, the mapping gets tedious.

Querying happens two ways. There is a property search syntax in the UI, with the README giving level:err as an example, and there is raw SQL as a fallback. Alerts run as a separate task process rather than inside the web request path, which is why the development script starts an alerts task alongside the API and app. The README also lists live tail for logs and traces, event deltas for anomaly analysis, and dashboards for high-cardinality events without a query language.

## Installing HyperDX with Docker and sending your first trace

The README's quickstart is a single container that bundles ClickHouse, HyperDX, the OpenTelemetry Collector and MongoDB. It maps the UI port, the OTLP gRPC port and the OTLP HTTP port.

```bash
docker run -p 8080:8080 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one
```

After the container starts, the README says to visit http://localhost:8080 for the UI. The README notes that if the server sits behind a firewall you will need to open or forward 8080 for the UI, 8000 for the API and 4318 for the OTel collector. It also recommends at least 4GB of RAM and 2 cores for testing, which is a useful floor: this is a database plus three services, not a lightweight agent.

For a real deployment the README points elsewhere. If you already run ClickHouse, or you want production instructions, it directs you to the deployment documentation rather than the one-liner. The repository also ships a docker-compose.yml with the four services separated, which is the shape you would adapt for anything beyond a laptop.

Instrumentation is the second half of setup. Once HyperDX is running, the README says to point your OpenTelemetry SDK at the collector on http://localhost:4318. Any OTLP-compatible SDK works; the README lists Kubernetes, JavaScript, Python, Java, Go, Ruby, PHP, .NET, Elixir and Rust as supported platforms, and points to dedicated Browser, Node.js and Python SDK pages for the HyperDX-specific integrations. Nothing in the README describes a separate agent to install on each host.

There is also a terminal path. The CLI package installs globally and provides an interactive TUI:

```bash
npm install -g @hyperdx/cli
hdx auth login
hdx tui
```

The README describes the TUI as supporting search, live tail and trace waterfalls with vim-style keybindings, plus dashboard tiles rendered as ANSI output. It also mentions raw SQL queries, NDJSON output and Drain log pattern mining aimed at scripts and agents. If your team lives in a terminal, that is a smaller commitment than standing up the web UI.

## Where HyperDX gets awkward: MongoDB, schema mapping and the collector

The dependency on MongoDB is the least discussed part of the stack and, in my reading, the one most likely to surprise people. ClickHouse holds the telemetry, but MongoDB holds the application state. That means a production HyperDX deployment is two databases, not one, and your backup, upgrade and capacity planning has to cover both. The docker-compose file comments out the MongoDB port mapping with an explicit warning that exposing it makes the database reachable from outside the container. That warning exists because people do this.

The OpenTelemetry Collector is the second operational surface. It is a separate process with its own configuration, and the compose file shows it being driven partly by environment variables from the app, including a flag that creates a legacy schema. The commented ENABLE_PROMQL line notes it must match the app service's setting, which is the kind of paired configuration that breaks silently when someone changes one side.

Schema agnosticism cuts both ways. It saves you a migration, and it means query quality depends on your column layout. If half your services log to a body column and half stuff everything into attributes, the search experience degrades and the fix is in your instrumentation, not in HyperDX.

Finally, the README states that HyperDX collects anonymized usage data for open source deployments. The text is truncated in the repository, so the full scope of what is collected and how to turn it off is not visible here. If your organization has restrictions on outbound telemetry from internal tooling, treat that as an open question to resolve before rollout rather than after.

## HyperDX compared with Grafana and SigNoz: same problem, different centre of gravity

Grafana is the obvious comparison because both are open source dashboards over time-series and log data. The difference in approach is where the query engine lives. Grafana is a visualization layer that connects to many backends through data source plugins, so a Grafana deployment typically means Loki for logs, Tempo for traces, Prometheus for metrics, and a separate session replay tool if you want one. HyperDX collapses that into ClickHouse plus its own UI. If you already run a Grafana stack, adding HyperDX means adding a second query path over the same data, not replacing the first.

SigNoz is the closer architectural match: also open source, also built around a column store for observability, also OpenTelemetry-native. The practical difference is the storage dependency. HyperDX is explicit that it works on top of any ClickHouse cluster and any existing schema, which matters if ClickHouse is already part of your infrastructure for non-observability reasons. SigNoz brings its own storage layer, so the question becomes whether you want an observability platform that owns its database or a UI that attaches to one you already operate. Neither is wrong; they are different commitments about who runs the storage.

One more difference worth naming: HyperDX is described in the README as a core component of ClickStack, the ClickHouse observability stack. That is a governance fact, not a quality claim. The project's direction is tied to ClickHouse's own observability strategy, which is reassuring for ClickHouse users and irrelevant to everyone else.

## Maintenance, releases and what the MIT licence actually gives you

The repository is not archived, and the last push was on 2026-08-28. That is recent enough that the project is clearly still receiving commits. Releases are versioned per package rather than as one product, with the most recent batch on that same date covering @hyperdx/otel-collector at 2.37.0, @hyperdx/hdx-eval at 0.3.3 and @hyperdx/common-utils at 0.28.0. The workspace is managed with Yarn workspaces and Nx, and changesets are in use, so version bumps appear to follow a structured release process rather than ad-hoc tagging.

For upgrade cost, the package split is the thing to watch. If you deploy the all-in-one container, you upgrade one image. If you run the compose stack or a production deployment, the collector, the app and the common utilities can move independently, and the compose file's paired environment variables (the PromQL flag being the clearest example) mean a partial upgrade can leave services disagreeing about schema. Pin image versions rather than tracking latest.

The licence is MIT, which is permissive and imposes no copyleft obligation on your own code. That covers the repository's own licensing; it says nothing about ClickHouse, MongoDB or the OpenTelemetry Collector, each of which carries its own terms and should be checked separately for your deployment model. Nothing here is legal advice, and the README's own note about anonymized usage data is a policy question rather than a licensing one.

One contribution detail is worth flagging because it affects anyone planning to send patches: the README states that first-time pull requests require a maintainer to vouch for the contributor through Vouch, and that getting vouched starts with opening an issue. That is a deliberate filter, and it means a drive-by bug fix will sit unreviewed.

## Conclusion

Adopt HyperDX if your telemetry already lands in ClickHouse and you want search, dashboards and alerts over it without adopting a per-host pricing model. Do not adopt it as a first observability stack if you have no ClickHouse cluster and no appetite for running ClickHouse, MongoDB and an OpenTelemetry collector alongside it. Before committing, verify three things: that your existing table schema maps cleanly onto HyperDX's source configuration, that your retention plan accounts for ClickHouse disk growth, and that the anonymized usage reporting described in the README is acceptable to your team.

## FAQ

### What is HyperDX?

HyperDX is an open source observability platform that unifies session replays, logs, metrics, traces and errors in one interface. It runs on top of a ClickHouse cluster and is described in the README as a core component of ClickStack.

### Is HyperDX open source?

Yes. The repository is licensed under MIT, and the README notes that HyperDX collects anonymized usage data for open source deployments.

### What are some alternatives to HyperDX?

Grafana is the closest general-purpose alternative, connecting to separate backends such as Loki and Tempo rather than querying ClickHouse directly. SigNoz is architecturally similar but brings its own storage layer instead of attaching to an existing ClickHouse schema.

### How do I use HyperDX?

The README's quickstart runs a single all-in-one container publishing ports 8080, 4317 and 4318, after which the UI is available at http://localhost:8080. The README recommends at least 4GB of RAM and 2 cores for testing, then you point an OpenTelemetry SDK at the collector on port 4318.

### How does HyperDX compare with SigNoz?

Both are open source and OpenTelemetry-native. The difference is storage: HyperDX works on top of any existing ClickHouse cluster and schema, while SigNoz brings its own storage layer, so the choice is about who operates the database.

## Sources

- [Official documentation](https://hyperdx.io/)
- [Official README](https://github.com/hyperdxio/hyperdx#readme)
- [Project repository](https://github.com/hyperdxio/hyperdx)
- [Release notes](https://github.com/hyperdxio/hyperdx/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hyperdxio-hyperdx