HyperDX

HyperDX is an open source observability platform built to help engineering teams resolve production issues fast. As the core UI component of ClickStack — ClickHouse’s integrated observability solution — it gives you a single interface to correlate session replays, logs, metrics, traces, and errors without jumping between tools or paying per-seat or per-host fees.

Powered by ClickHouse’s columnar storage engine, HyperDX delivers blazing-fast queries across terabytes of telemetry data with schema-agnostic ingestion — meaning it works on top of your existing ClickHouse schema without requiring data migration or pre-defined schemas. Engineers can search with intuitive property syntax, write native SQL queries, or use the visual chart builder to surface production insights in seconds.

Deployment is flexible: spin up a single Docker container for local testing, connect to an existing ClickHouse cluster, or use ClickHouse Cloud for a fully managed backend. OpenTelemetry is natively supported, meaning any OTel-compatible language or framework — Node.js, Python, Go, Java, Ruby, Rust, .NET, and more — sends data directly to HyperDX without proprietary agents or sidecars.

HyperDX is backed by an active development team releasing multiple versions per month, with comprehensive test coverage across unit, integration, and end-to-end layers. It ships with SDKs for browser and Node.js environments, a CLI tool for source map uploads, and deep integration with Kubernetes, AWS, and Vercel deployment environments.

What You Get

• Session Replay Correlation - Links frontend session recordings directly to backend logs, traces, and errors so you can watch exactly what a user experienced while tracing the server-side root cause simultaneously.
• Schema-Agnostic Log and Trace Search - Queries your existing ClickHouse schema without requiring data migration — use intuitive property syntax like level:err or user_id:123, optional SQL, or a visual chart builder.
• ClickHouse-Powered Sub-Second Queries - Leverages ClickHouse’s columnar storage to scan terabytes of telemetry in milliseconds, making real-time incident investigation practical at any data scale.
• OpenTelemetry Native Ingestion - Accepts data from any OTel-compatible language (JavaScript, Python, Go, Java, Ruby, .NET, Rust, Elixir, PHP) without proprietary agents or configuration overhead.
• Visual Dashboard Builder - Drag-and-drop chart creation for high-cardinality metrics like error rates grouped by customer ID, P99 latency trends, or deployment health — no complex query language required.
• Live Tail Logs and Traces - Streams incoming telemetry in real time, letting you monitor ongoing events and debug active incidents as they unfold.
• Multi-Channel Alerting - Configures threshold and anomaly alerts in a few clicks, delivering notifications via Slack, email, or PagerDuty with AI-assisted query suggestions.
• Source Map Deobfuscation via CLI - Upload JavaScript source maps through the included @hyperdx/cli tool to automatically map minified stack frames back to original source code.
• AI-Assisted Query Generation - Suggests meaningful search filters and chart configurations using contextual metadata from your telemetry schema, not just generic NL-to-SQL translations.
• Event Delta Analysis - Compares event volumes across time windows to identify regressions, spikes, or anomalies introduced by recent deployments.
• Kubernetes and Cloud-Native Integration - Ships with out-of-the-box dashboards and instrumentation guides for Kubernetes, AWS EC2, Vercel, and ClickHouse Cloud deployments.
• MCP Server Support - Exposes a Model Context Protocol server endpoint, enabling AI agents and LLM tools to query your telemetry data programmatically.

Common Use Cases

• Diagnosing a microservice outage end-to-end - A site reliability engineer correlates a spike in 500 errors from Kubernetes pod logs with distributed traces across five backend services, isolating a failed database query within minutes using HyperDX’s unified search.
• Connecting user complaints to server behavior - A support engineer pastes a user’s session ID into HyperDX and immediately sees their session replay alongside the exact API request that failed, its trace, and the upstream ClickHouse query that timed out.
• Migrating from Datadog to cut costs - An infrastructure lead replaces Datadog on a team ingesting 200 GB/day of telemetry by pointing their existing OpenTelemetry collectors at a self-hosted HyperDX instance, eliminating per-host and per-user fees.
• Monitoring a multi-language tech stack - A platform engineer instruments Node.js APIs, Python data pipelines, and Go microservices with OpenTelemetry SDKs, sending all telemetry to a single HyperDX deployment for unified visibility.
• Tracking deployment health in real time - A release engineer tails live logs during a canary rollout, watching for error rate increases across regions and setting an alert to fire if P99 latency exceeds a threshold for more than two minutes.
• AI-powered telemetry querying - A development team connects their AI coding assistant to HyperDX’s MCP server endpoint to automatically investigate production errors during code review and debugging sessions.

Under The Hood

Architecture HyperDX is organized as a monorepo with clearly delineated packages for the API backend, Next.js frontend, shared utilities, OpenTelemetry collector, and a CLI tool. The Express-based API layer uses interface-driven design with typed contracts for alerts, webhooks, connections, and sources, enabling extensibility without coupling. Services communicate over standardized protocols — OTLP for telemetry ingestion, OpAMP for dynamic collector configuration — meaning the architecture follows open standards rather than proprietary inter-service contracts. The frontend and backend share a common-utils package for chart rendering logic, type definitions, and ClickHouse query construction, maintaining DRY principles across the stack while keeping a clear boundary between presentation and data layers.

Tech Stack The backend runs on Node.js with Express and TypeScript, using MongoDB via Mongoose for user data, dashboards, alerts, and saved searches, while ClickHouse serves as the exclusive telemetry storage engine accessed through a custom typed SQL construction library. The frontend is Next.js with React, Mantine UI components, and uPlot for high-performance time series visualizations. A custom SQL macro system in common-utils handles parameterized ClickHouse queries with dynamic expansion, source-aware schema inference, and support for both builder-style configurations and raw SQL modes. The OpenTelemetry collector is distributed as a Go binary alongside the app, and Yarn 4 with NX manages the monorepo build graph. A CLI package built with TypeScript handles source map uploads and integrates with the API’s external REST interface.

Code Quality HyperDX has extensive test coverage across all layers — unit tests for query builders and error utilities, integration tests that spin up actual ClickHouse and MongoDB instances against fixture data, and end-to-end tests using Playwright with page object models for complex UI flows. TypeScript strict mode is enforced throughout with Zod validation at API boundaries and well-typed interfaces for all major domain objects. Error handling uses a structured hierarchy of custom error classes with HTTP status codes and operational flags, and structured JSON logging is present at all critical paths. Linting and formatting are enforced via ESLint and Prettier with pre-commit hooks, and NX manages caching and build isolation to keep CI fast across the multi-package workspace.

What Makes It Unique HyperDX’s most distinctive technical contribution is its unified SQL query layer that abstracts logs, traces, and metrics into a single schema-agnostic interface — allowing it to work directly on top of existing ClickHouse clusters without data migration, unlike Grafana Loki or Elasticsearch-based stacks that require dedicated storage formats. The macro expansion system in common-utils enables complex analytical queries — percentile calculations, histogram bucketing, event delta comparisons — to be expressed as high-level chart configurations and compiled into optimal ClickHouse SQL at runtime. Its session replay integration goes deeper than typical RUM tools by linking browser-side recording playback directly to server-side traces, enabling end-to-end debugging from a single UI. The MCP server endpoint is a forward-looking addition that exposes telemetry search as a tool for AI agents, positioning HyperDX as infrastructure that AI-assisted development workflows can query natively.

Self-Hosting

HyperDX is released under the MIT License, which grants unrestricted rights to use, modify, distribute, and sublicense the software — including for commercial purposes — with no copyleft requirements. You can run it in a commercial product, modify the source code, and distribute your modifications without any obligation to open-source your changes. The only requirement is preserving the copyright notice and license text. There are no open-core enterprise tiers or license keys needed to unlock features; every capability in the codebase is available to self-hosters.

Running HyperDX yourself requires three core dependencies: a ClickHouse instance (the single source of truth for all telemetry), MongoDB (for user accounts, dashboards, alerts, and saved searches), and the HyperDX application container itself. The all-in-one Docker image bundles everything for evaluation, but production deployments typically run each service separately and require planning for ClickHouse storage sizing, MongoDB replication for durability, and reverse proxy configuration for HTTPS. ClickHouse is operationally demanding at scale — compaction, disk I/O, and memory tuning require hands-on attention as data volumes grow. The team recommends at least 4 GB RAM and two CPU cores for meaningful workloads, though production systems handling hundreds of gigabytes per day will need substantially more.

The main trade-off compared to ClickHouse Cloud-backed deployments is operational responsibility: you own uptime, backups, upgrades, and capacity planning. ClickHouse Cloud provides managed storage, automatic scaling, and built-in high availability, which HyperDX can connect to as its backend — eliminating the ClickHouse ops burden while you still self-host the HyperDX UI layer. There is no SaaS version of HyperDX itself with a dedicated support tier or SLA; community support happens through GitHub issues and Discord. Teams evaluating self-hosting should weigh the zero licensing cost against the engineering time needed to operate ClickHouse reliably.