Database Monitoring for ClickHouse Cloud

Atatus Database Monitoring provides deep visibility into your ClickHouse Cloud services by collecting key system metrics, query summary statistics, active query samples, completed query events, query errors, EXPLAIN plans, and MergeTree parts/merges health.

ClickHouse Cloud exposes a single load-balanced endpoint that routes to one of the underlying replicas. To collect cluster-wide telemetry through that single endpoint, the Atatus Infra Agent rewrites system.<table> references to clusterAllReplicas('default', system.<table>). This guide walks you through the prerequisites and setup process.

• Setup Database Access for the Agent
• Configure Atatus Infrastructure Agent
• Verify

Before You Begin

Setup Database Access for the Agent

Open a SQL console for your ClickHouse Cloud service (from the ClickHouse Cloud UI or via clickhouse-client against the service endpoint) and run the following statements as an administrator.

1. Create the atatus user:

   copy

   CREATE USER atatus IDENTIFIED BY '<UNIQUEPASSWORD>';
   

2. Grant SELECT access on the system.* tables the Agent reads:

   copy

   GRANT SELECT ON system.metrics TO atatus;
   GRANT SELECT ON system.events TO atatus;
   GRANT SELECT ON system.asynchronous_metrics TO atatus;
   GRANT SELECT ON system.errors TO atatus;
   GRANT SELECT ON system.processes TO atatus;
   GRANT SELECT ON system.query_log TO atatus;
   GRANT SELECT ON system.parts TO atatus;
   GRANT SELECT ON system.detached_parts TO atatus;
   GRANT SELECT ON system.mutations TO atatus;
   GRANT SELECT ON system.replicas TO atatus;
   GRANT SELECT ON system.replication_queue TO atatus;
   GRANT SELECT ON system.dictionaries TO atatus;
   

3. Grant the REMOTE privilege so the Agent can query across all replicas via clusterAllReplicas():

   copy

   GRANT REMOTE ON *.* TO atatus;
   

   Note:

   REMOTE only allows the Agent to fan out the already-granted system.* SELECTs across replicas — it does not expand access to any other tables.

Configure Atatus Infrastructure Agent

1. Install the Atatus Infrastructure agent on a host that can reach your ClickHouse Cloud service over the public internet (or via a private link, if configured).

2. Copy the ClickHouse example configuration file:

   copy

   cd /etc/atatus-infra-agent/conf.d/clickhouse.d/
   sudo cp clickhouse.yml.template clickhouse.yml
   

3. Update the ClickHouse configuration file:

   Add the following configuration to /etc/atatus-infra-agent/conf.d/clickhouse.d/clickhouse.yml:

   copy

   metrics:
     - hosts: ["clickhouse://<SERVICE_HOSTNAME>.clickhouse.cloud:9440"]
       username: atatus
       password: <UNIQUEPASSWORD>
       database: default
       dbm: true
       single_endpoint_mode: true
       tls:
         enabled: true
         verification_mode: "certificate"
   

   Replace <SERVICE_HOSTNAME> with your ClickHouse Cloud service hostname (for example, xyz.us-east-2.aws.clickhouse.cloud) and <UNIQUEPASSWORD> with the password you created above.

   Key ClickHouse Cloud requirements:

   Setting	Value	Reason
   port	9440	ClickHouse Cloud requires TLS on the native protocol
   tls.enabled	true	Required for the secure connection
   single_endpoint_mode	true	Rewrites system.<table> to clusterAllReplicas('default', system.<table>)

4. Restart the Atatus Infra Agent:

   copy

   sudo service atatus-infra-agent restart
   

Verify

Confirm the atatus user can connect to the cloud service and read the core system.* tables across replicas:

clickhouse-client \
  --host <SERVICE_HOSTNAME>.clickhouse.cloud \
  --port 9440 --secure \
  --user atatus --password \
  --query "SELECT 1" \
  && echo -e "\e[0;32mClickHouse Cloud connection - OK\e[0m" \
  || echo -e "\e[0;31mCannot connect to ClickHouse Cloud\e[0m"

clickhouse-client \
  --host <SERVICE_HOSTNAME>.clickhouse.cloud \
  --port 9440 --secure \
  --user atatus --password \
  --query "SELECT count() FROM clusterAllReplicas('default', system.query_log)" \
  && echo -e "\e[0;32mclusterAllReplicas(system.query_log) read OK\e[0m" \
  || echo -e "\e[0;31mCannot read clusterAllReplicas(system.query_log) — check REMOTE grant\e[0m"

HTTP Protocol (Alternative)

If your environment only allows outbound HTTPS, you can use the ClickHouse Cloud HTTP interface on port 8443 instead of the native protocol on 9440:

metrics:
  - hosts: ["http://<SERVICE_HOSTNAME>.clickhouse.cloud:8443"]
    username: atatus
    password: <UNIQUEPASSWORD>
    database: default
    dbm: true
    single_endpoint_mode: true
    tls:
      enabled: true
      verification_mode: "certificate"

Tuning DBM Feature Toggles (Optional)

Each Database Monitoring feature can be turned on or off individually under dbm_clickhouse_options. All features are enabled by default once dbm: true (except query_explain, which can be opted out via enabled: false).

For the full list of feature toggles, query log tunables, EXPLAIN tunables, and parts/merges tunables, see the self-hosted setup guide.

Overriding the Reported Hostname (Optional)

ClickHouse Cloud service hostnames can be long. To report a friendlier name in events:

metrics:
  - hosts: ["clickhouse://<SERVICE_HOSTNAME>.clickhouse.cloud:9440"]
    username: atatus
    password: <UNIQUEPASSWORD>
    database: default
    dbm: true
    single_endpoint_mode: true
    reported_hostname: "clickhouse-cloud-prod"
    tls:
      enabled: true
      verification_mode: "certificate"