Skip to main content
Skip to main content
Edit this page

HyperDX Only

This option is designed for users who already have a running ClickHouse instance populated with observability or event data.

HyperDX can be used independently of the rest of the stack and is compatible with any data schema - not just OpenTelemetry (OTel). This makes it suitable for custom observability pipelines already built on ClickHouse.

To enable full functionality, you must provide a MongoDB instance for storing application state, including dashboards, saved searches, user settings, and alerts.

In this mode, data ingestion is left entirely to the user. You can ingest data into ClickHouse using your own hosted OpenTelemetry collector, direct ingestion from client libraries, ClickHouse-native table engines (such as Kafka or S3), ETL pipelines, or managed ingestion services like ClickPipes. This approach offers maximum flexibility and is suitable for teams that already operate ClickHouse and want to layer HyperDX on top for visualization, search, and alerting.

Suitable for​

  • Existing ClickHouse users
  • Custom event pipelines

Deployment steps​


Deploy with Docker​

Run the following command, modifying YOUR_MONGODB_URI as required.

Visit http://localhost:8080 to access the HyperDX UI.

Create a user, providing a username and password which meets the requirements.

On clicking Create you'll be prompted for connection details.

Complete connection details​

Connect to your own external ClickHouse cluster e.g. ClickHouse Cloud.

If prompted to create a source, retain all default values and complete the Table field with the value otel_logs. All other settings should be auto-detected, allowing you to click Save New Source.

Creating a source

Creating a source requires tables to exist in ClickHouse. If you don't have data, we recommend deploying the ClickStack OpenTelemetry collector to create tables.

Using Docker Compose​

Users can modify the Docker Compose configuration to achieve the same effect as this guide, removing the OTel collector and ClickHouse instance from the manifest.

ClickStack OpenTelemetry collector​

Even if you are managing your own OpenTelemetry collector, independent of the other components in the stack, we still recommend using the ClickStack distribution of the collector. This ensures the default schema is used and best practices for ingestion are applied.

This image configuration can be found here and can be deployed with the following command:

For example,

The OPAMP_SERVER_URL variable should point to your HyperDX deployment e.g. http://localhost:4320. This runs an OpAMP (Open Agent Management Protocol) server endpoint at /v1/opamp on port 4320 by default. This ensures the collectors OTLP interface is secured with the ingestion API key. See Securing the collector. The CLICKHOUSE_ENDPOINT here should be the full ClickHouse endpoint including the protocol and port e.g. http://localhost:8123.

This command exposes an OTLP endpoint on ports 4317 (HTTP) and 4318 (gRPC) for users to send OTel events.

For further details on deploying and configuring the collector see "Ingesting with OpenTelemetry" and "ClickStack OpenTelemetry Collector".