Skip to main content

Using External ClickHouse

It is recommended to use the ClickHouse instance that is deployed along with Signoz. However, if you want to use an external ClickHouse instance, you can do so by relevant instructions below.


  • Must have at least one Zookeeper instance
  • Distributed cluster named cluster set up required: clickhouse-cluster.xml
  • User credentaials passed must have enough privileges to create/manage databases and tables
  • Secure connection is not supported between Signoz and ClickHouse yet
  • (Optional) UDF script and histogram quantile binary required: custom-function.xml and histogramQuantile binary

The name of the cluster must be cluster as it is hardcoded in the SigNoz OtelCollector migration files due to the limitations of golang-migrate library.

Setting up ClickHouse

  1. Run at least an instance of Zookeeper.
  2. Create configuration for distributed cluster named cluster as described in clickhouse-cluster.xml and include it in /etc/clickhouse-server/config.d/.
  3. Include Zookeeper information in above clickhouse-cluster.xml file as well.
  4. (Optional) Below steps are only required if you want to use histogram quantile functions using Query Builder.
  5. Run at least an instance of ClickHouse with the above configuration.

For Docker and Docker Swarm Users

In Docker and Docker Swarm, we will be modifying the docker-compose.yml file to use an external ClickHouse.

  1. Comment out clickhouse and zookeeper services in docker-compose.yml.
  2. Comment out x-clickhouse-defaults and x-clickhouse-depend sections in docker-compose.yml.
  3. Replace clickhouse:9000 with relavant ClickHouse endpoint and TCP port in the files below:
    • docker-compose.yaml
    • otel-collector-config.yaml
    • otel-collector-metrics-config.yaml
    • prometheus-config.yml
  4. Start SigNoz using relevant instructions.

For Kubernetes Users

In Kubernetes, we will update override-values.yaml file to use an external ClickHouse.

At first, we will disable the default ClickHouse instance by setting clickhouse.enabled to false. Then, we will include the external ClickHouse information in the externalClickhouse section.


enabled: false

host: <clickhouse-endpoint>
httpPort: 8123
tcpPort: 9000
cluster: cluster
secure: false
user: <ch-user>
password: <ch-password>

To install SigNoz using the above configuration, run the following command:

kubectl create namespace platform
helm --namespace platform install my-release signoz/signoz -f override-values.yaml