HyperDX: An Open Source Observability Stack Built on ClickHouse and OpenTelemetry

What HyperDX Actually Solves

HyperDX is an open source observability platform that combines session replays, logs, metrics, traces, and errors into a single interface. The README positions it as a core component of ClickStack, a ClickHouse-backed observability stack, and compares it to Kibana but for ClickHouse. The problem it addresses is the fragmentation of observability tools: teams often jump between separate products for logs, APM, and session replay, stitching together clues manually. HyperDX also targets the cost problem, where commercial tools charge per terabyte and force teams to cut data collection. The intended user is an engineer who wants to search and visualize telemetry on top of an existing ClickHouse cluster, without adopting a proprietary query language or a separate storage engine. The project is schema agnostic, meaning it can work with your existing ClickHouse schema, which is a significant departure from tools that require a predefined data model.

How the Data Flow Works

HyperDX relies on OpenTelemetry as its ingestion standard. The README lists supported languages including JavaScript, Python, Java, Go, Ruby, PHP, .NET, Elixir, and Rust, and states that you can point your OpenTelemetry SDK to the collector at `http://localhost:4318`. The all-in-one container runs an OpenTelemetry Collector alongside the HyperDX API and UI, so telemetry flows from your instrumented app to the collector, then into ClickHouse. The UI then queries ClickHouse directly for search, visualization, and alerting. The README highlights full-text search and property search syntax like `level:err`, with SQL optional. This suggests that HyperDX translates user-friendly queries into ClickHouse SQL under the hood, though the exact mechanism is not detailed in the README. The platform also supports live tailing of logs and traces, which implies a streaming or polling mechanism on top of ClickHouse, but the implementation details are not specified in the provided material.

Getting HyperDX Running

The quickest start is the all-in-one Docker image, which bundles ClickHouse, HyperDX, OpenTelemetry Collector, and MongoDB. The README gives this command: `docker run -p 8080:8080 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one`. After that, you visit `http://localhost:8080` to access the UI. The README warns that you need to open ports 8080, 8000, and 4318 on your firewall for the UI, API, and OTel collector, respectively, if you are behind a firewall. It also recommends at least 4GB of RAM and 2 cores for testing, which is a modest requirement for a stack that includes ClickHouse. For production, the README points to deployment docs that cover using an existing ClickHouse instance or deploying with ClickHouse Cloud. The inclusion of MongoDB in the stack is notable; it likely stores metadata, user accounts, or alert configurations, though the README does not specify. Instrumenting your app requires either the HyperDX SDKs for Browser, Node.js, and Python, or any OpenTelemetry SDK pointed at the collector. This dual path is flexible, but it means you must choose between HyperDX-specific SDKs and the vendor-neutral OpenTelemetry route.

The HyperDX CLI and Agent-Friendly Output

Beyond the web UI, HyperDX ships a command-line tool called `hdx`, installable via `npm install -g @hyperdx/cli`. The README describes an interactive TUI with vim-style keybindings for searching, live tailing, and viewing trace waterfalls. It can also render dashboard tiles and ad-hoc charts as ANSI output directly in the terminal. More interestingly, the CLI is positioned as agent-friendly: it supports raw SQL queries, NDJSON output, and Drain log pattern mining. This is a practical feature for scripting and for AI agents that need to consume telemetry data programmatically. The CLI requires authentication via `hdx auth login`, which suggests it connects to a HyperDX instance over the network. This terminal-first approach is a differentiator; most observability platforms are web-only. However, the CLI is an additional tool to learn, and its feature set may overlap with the UI in ways that require maintenance.

Limitations and When It Is the Wrong Tool

HyperDX is not a fit for every team. First, it assumes you are willing to run and operate ClickHouse, or at least pay for ClickHouse Cloud. If you have no ClickHouse expertise, the operational burden of tuning clusters, managing shards, and handling high-cardinality data falls on you. The README's recommendation of 4GB RAM for testing is a hint that production workloads will demand significantly more. Second, the schema-agnostic promise is double-edged: while it works on top of your existing ClickHouse schema, that schema may not be optimized for HyperDX's query patterns. You may need to design or alter your schema to get the advertised search performance. Third, the README mentions that HyperDX collects anonymized usage data for open source deployments. This is a privacy consideration that some organizations will find unacceptable, especially for self-hosted infrastructure. Fourth, the project uses a contribution gate called Vouch, where a maintainer must vouch for you before your first PR is reviewed. This is a deliberate anti-spam measure, but it can slow down external contributions. Finally, the project is not a managed service; you are responsible for upgrades, backups, and security patches.

Alternatives and the ClickHouse Difference

The most direct alternative is Elastic Stack (Elasticsearch, Logstash, Kibana), which HyperDX explicitly evokes with the Kibana comparison. Elastic Stack is also open source, but it is built on Lucene-based search, not ClickHouse. The key difference is storage and query engine: Elasticsearch is optimized for full-text search with inverted indexes, while ClickHouse is a columnar OLAP database designed for analytical queries over large datasets. This means HyperDX's performance profile will differ from Elasticsearch, particularly for aggregations and high-cardinality metrics. Another alternative is SigNoz, which also uses ClickHouse and OpenTelemetry, but SigNoz is a dedicated APM tool with its own UI and does not include session replay out of the box. HyperDX's session replay is a differentiator. If you are already invested in Elasticsearch, HyperDX would require a separate ClickHouse cluster, adding operational complexity. If you want a managed SaaS, alternatives like Datadog or Honeycomb are easier to adopt, but they come with the per-TB pricing that HyperDX's README criticizes.

Maintenance, Licensing, and Upgrade Considerations

HyperDX is licensed under MIT, which is permissive and allows commercial use without copyleft obligations. That is a low-friction license for adoption. The project is actively maintained, with recent releases of `@hyperdx/otel-collector@2.37.0` and `@hyperdx/hdx-eval@0.3.3` as of August 2026. The repository is not archived, and the last push is recent, so maintenance appears ongoing. However, the README does not provide a migration path or upgrade guide, so you will need to rely on the deployment docs for version upgrades. The all-in-one container bundles multiple components (ClickHouse, MongoDB, OTel Collector), which means upgrading HyperDX may also require updating ClickHouse and MongoDB, and you must test compatibility. The README also notes that HyperDX collects anonymized usage data; this is a maintenance consideration because you may need to configure or disable it in your deployment, depending on your privacy policy. The Vouch contribution gate is a maintenance cost for the community, but it is a deliberate choice to filter low-quality PRs.

Editorial conclusion

Adopt HyperDX if you already run ClickHouse or want a self-hosted observability stack that avoids per-TB pricing and vendor lock-in, and if you are comfortable with OpenTelemetry instrumentation. Do not adopt it if you need a managed, turnkey SaaS with minimal ops overhead, or if your team lacks ClickHouse tuning experience. Before committing, verify that your ClickHouse schema works with HyperDX's schema-agnostic queries, test the all-in-one container with your own telemetry volume, and review the data retention and anonymized usage collection settings in the deployment docs.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes