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

Component	Supported Versions / Requirements
ClickHouse Cloud	Any current ClickHouse Cloud service
Atatus Infra Agent	4.3.0 or higher

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.

Create the atatus user:

CREATE USER atatus IDENTIFIED BY '<UNIQUEPASSWORD>';

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

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;

Grant the REMOTE privilege so the Agent can query across all replicas via clusterAllReplicas():
GRANT REMOTE ON *.* TO atatus;
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

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).

Copy the ClickHouse example configuration file:

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

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

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>)`

Restart the Atatus Infra Agent:

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"

On serverless ClickHouse Cloud services with auto-suspend enabled, ongoing Database Monitoring collection may prevent the service from suspending during idle periods. Adjust collection intervals or feature toggles if this affects your billing.

​Before You Begin

​Setup Database Access for the Agent

​Configure Atatus Infrastructure Agent

​Verify

​HTTP Protocol (Alternative)

​Tuning DBM Feature Toggles (Optional)

​Overriding the Reported Hostname (Optional)

Before You Begin

Setup Database Access for the Agent

Configure Atatus Infrastructure Agent

Verify

HTTP Protocol (Alternative)

Tuning DBM Feature Toggles (Optional)

Overriding the Reported Hostname (Optional)