HyperDX

Last reviewed Aug 26, 2026 · 860 words

HyperDX is for debugging the software you write, not for watching the servers you run. If the question is "is the NAS up", it is the wrong tool and Uptime Kuma is the right one. If the question is "why did checkout return a 500 for this user at 14:03, and what did their screen look like", HyperDX answers it in one view: the trace, the logs around it, and a session replay of the click, all joined on the same OpenTelemetry IDs and stored in ClickHouse. It is a 2023 project with about 9,900 stars, MIT-licensed, and the catalogue's "requires ClickHouse" is both its main cost and the reason it is fast.

One image to start, four services underneath

The all-in-one image is the honest starting point and the one I would use for anything short of a team with an SRE.

services:
  hyperdx:
    image: hyperdx/hyperdx-all-in-one:latest
    ports:
      - "8080:8080"   # web UI and API
      - "4317:4317"   # OTLP over gRPC
      - "4318:4318"   # OTLP over HTTP
    volumes:
      - hdx-clickhouse:/data/db
      - hdx-mongo:/data/mongo
    restart: unless-stopped

volumes:
  hdx-clickhouse:
  hdx-mongo:

Inside it are four things: the HyperDX app, an OpenTelemetry collector, ClickHouse for the telemetry itself, and MongoDB for dashboards, saved searches and users. Check the image's documented data paths before you trust the volume mounts above; I have named them from memory and the point is that ClickHouse's data directory must persist, or a restart empties your history. For a production split, the project also publishes a compose file and a Helm chart that run each piece separately, and since 2025 it has been packaged as the interface of ClickStack, ClickHouse's own open-source observability bundle, which is where the long-term maintenance now sits.

The catalogue's 1 GB minimum is what the image idles at empty. ClickHouse likes memory for merges and queries, and 4 GB is the size where the search box stops feeling laggy.

Sending data is standard OTLP, plus one browser script

Nothing about ingestion is proprietary. Any OpenTelemetry SDK points at the collector with two variables:

OTEL_EXPORTER_OTLP_ENDPOINT=http://hyperdx.internal:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=<ingestion api key from Team Settings>
OTEL_SERVICE_NAME=checkout

Logs, traces and metrics arrive over that one channel. If you already run an OpenTelemetry Collector as the hub for your services, add HyperDX as an OTLP exporter and it slots in without touching the applications.

Session replay is the part nobody else in the self-hosted field offers. The @hyperdx/browser package records the DOM (it uses rrweb underneath), captures console output and network calls, and tags them with the same trace IDs your backend emits, so clicking a slow request in a replay opens its server-side trace. That is the feature that justifies HyperDX over a pure backend tool, and it is also the one to think about carefully: replays capture what users typed and saw, so mask inputs, exclude sensitive pages, and write it into your privacy notice.

Disk is the budget, so set retention on day one

ClickHouse compresses logs hard; 10:1 is a common figure for JSON logs and my own experience matches it, so 5 GB of raw application logs a day becomes roughly 500 MB on disk. That still adds up. Decide a retention window before the first byte lands, 14 or 30 days for a homelab, and set it in the image's retention setting so ClickHouse applies a TTL and drops old parts on its own. Put the data volume on SSD; ClickHouse on spinning disk is a merge-storm waiting to happen.

Where SigNoz, Grafana and GlitchTip still win

SigNoz is the closest relative: also OpenTelemetry-native, also ClickHouse, with stronger metrics dashboards and alerting, and no session replay. If your pain is backend latency and infrastructure metrics, SigNoz is the safer pick; if it is "what did the user experience", HyperDX. Grafana with Loki and Tempo is more moving parts and more to learn, but nothing matches its dashboards or its integrations with the rest of a homelab, and it pairs with Prometheus for the metrics half. GlitchTip is error tracking only, in 512 MB, and for a small app that is often all you need. For anyone leaving a commercial APM, the Datadog alternatives page is the map; the monitoring category covers the uptime and infrastructure tools HyperDX is not.

What I'd do

For a team running its own web application with real users, I would deploy the all-in-one image on a 4 GB VM with SSD, 30-day retention, OTLP from every service, and the browser SDK with input masking on. I would keep Uptime Kuma and Grafana for the infrastructure and not try to make HyperDX do their job. For a homelab with no application of my own to debug, I would skip it entirely; there is nothing for it to correlate. It is the best open-source answer to Datadog's RUM-plus-APM combination that I have run, on the condition that you have something worth replaying.