--- title: Setting Up Database Monitoring for ClickHouse Cloud description: Install and configure Database Monitoring for ClickHouse Cloud. breadcrumbs: >- Docs > Database Monitoring > Setting up ClickHouse > Setting Up Database Monitoring for ClickHouse Cloud --- # Setting Up Database Monitoring for ClickHouse Cloud {% alert level="info" %} This feature is in preview and requires Datadog Agent v7.78 or later. Customers who participate in the Datadog Database Monitoring for ClickHouse preview **will not be charged** for usage incurred during the preview period. Contact your Datadog representative or support to enable this feature. {% /alert %} Datadog Database Monitoring (DBM) for ClickHouse provides deep visibility into your ClickHouse Cloud services by collecting query metrics, live query samples, and completed query records to help you resolve issues and optimize query performance across your entire fleet. ## Before you begin{% #before-you-begin %} {% dl %} {% dt %} Supported Agent versions {% /dt %} {% dd %} 7.78+ {% /dd %} {% /dl %} ## Data collected{% #data-collected %} Database Monitoring collects the following data from ClickHouse: {% dl %} {% dt %} **Database instance** {% /dt %} {% dd %} Periodic collection (every 5 minutes) of instance information including version, hostname, and configuration. Custom tags defined in the `tags` option are attached to the instance for filtering and grouping by environment, region, service, or any other custom dimensions. {% /dd %} {% dt %} **Query metrics** {% /dt %} {% dd %} Aggregated performance metrics for executed queries, enabling analysis of query behavior and trends over time. Collected from `system.query_log`. {% /dd %} {% dt %} **Query samples** {% /dt %} {% dd %} Point-in-time snapshots of currently running queries are captured from `system.processes` at a 1-second interval. Because ClickHouse queries often complete in under one second, short-lived queries may not always appear in samples. {% /dd %} {% dt %} **Query completions** {% /dt %} {% dd %} Records of individual completed query executions, capturing all successfully executed queries. Use query completions alongside query samples to ensure complete visibility into all query activity, including short-lived queries not observed during sampling. {% /dd %} {% /dl %} ## Setup{% #setup %} ### Step 1: Grant Datadog Agent access{% #step-1-grant-datadog-agent-access %} Create a dedicated `datadog` user: ```sql CREATE USER datadog IDENTIFIED BY ''; ``` Grant the required permissions on system tables: ```sql GRANT SELECT ON system.metrics TO datadog; GRANT SELECT ON system.events TO datadog; GRANT SELECT ON system.asynchronous_metrics TO datadog; GRANT SELECT ON system.parts TO datadog; GRANT SELECT ON system.replicas TO datadog; GRANT SELECT ON system.dictionaries TO datadog; GRANT SELECT ON system.processes TO datadog; GRANT SELECT ON system.query_log TO datadog; ``` Grant `REMOTE` permissions to allow cross-replica querying: ```sql GRANT REMOTE ON *.* TO datadog; ``` {% alert level="info" %} The `REMOTE` privilege is required because the Agent uses ClickHouse's `clusterAllReplicas()` table function to aggregate data across all replicas in a ClickHouse Cloud service through the single endpoint. This privilege enables cross-node query execution—it does **not** grant access to any additional databases or tables beyond what was explicitly granted above. The `ON *.*` syntax is a ClickHouse requirement for this privilege type and does not expand the scope of data access. {% /alert %} ### Step 2: Configure the Agent{% #step-2-configure-the-agent %} For ClickHouse Cloud, the Agent connects to the service endpoint directly. Data is collected at the service level (aggregate across all replicas), not per individual node. {% alert level="warning" %} On serverless ClickHouse deployments with auto-suspend enabled, DBM collection activity may prevent the cluster from suspending during idle periods, which can impact billing. {% /alert %} {% alert level="info" %} This integration uses the ClickHouse **HTTP interface** (port 8443), not the native TCP protocol (port 9440). {% /alert %} ```yaml # /etc/datadog-agent/conf.d/clickhouse.d/conf.yaml init_config: instances: - dbm: true server: xyz.us-east-2.aws.clickhouse.cloud port: 8443 username: datadog password: # Required for ClickHouse Cloud tls_verify: true verify: true single_endpoint_mode: true tags: - env:production - deployment:cloud query_metrics: enabled: true collection_interval: 10 query_samples: enabled: true collection_interval: 1 query_completions: enabled: true collection_interval: 10 ``` `single_endpoint_mode: true` is required for ClickHouse Cloud. It enables `clusterAllReplicas()` queries to collect data across all nodes behind a single endpoint. ## Customizing the database identifier{% #customizing-the-database-identifier %} The `database_identifier` option controls how the database instance appears in DBM. Datadog recommends using the service name as a custom tag for identification and grouping. ```yaml instances: - dbm: true server: xyz.us-east-2.aws.clickhouse.cloud port: 8443 # ... other settings ... database_identifier: template: "$env-$server:$port" tags: - env:production - service_name:user-service ``` With `env:production`, `server: xyz.us-east-2.aws.clickhouse.cloud`, and `port: 8443`, this produces: | Template | Result | | ------------------------- | ---------------------------------------------------- | | `$server:$port` (default) | `xyz.us-east-2.aws.clickhouse.cloud:8443` | | `$env-$server:$port` | `production-xyz.us-east-2.aws.clickhouse.cloud:8443` | ## Configuration reference{% #configuration-reference %} ### Connection settings{% #connection-settings %} | Field | Type | Required | Default | Description | | ---------- | ------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------- | | `server` | string | Yes | - | ClickHouse Cloud service hostname (for example, `xyz.us-east-2.aws.clickhouse.cloud`). | | `port` | integer | No | `8123` | HTTP port. Use `8443` for ClickHouse Cloud (HTTPS). | | `username` | string | No | `default` | ClickHouse user account the Agent authenticates as. Datadog recommends a dedicated `datadog` user with limited permissions. | | `password` | string | No | - | Password for the specified user. | | `db` | string | No | `default` | Database to connect to. Most metrics come from system tables, so `default` is usually appropriate. | ### TLS settings{% #tls-settings %} | Field | Type | Default | Description | | ------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------- | | `tls_verify` | boolean | `false` | Enable TLS. Required for ClickHouse Cloud. | | `verify` | boolean | `true` | Validate the server's SSL certificate. Setting `false` in production is a security risk. | | `tls_ca_cert` | string | - | Path to a custom CA certificate file. Not needed for ClickHouse Cloud, which uses certificates from public CAs. | ### DBM settings{% #dbm-settings %} | Field | Type | Default | Description | | ---------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | | `dbm` | boolean | `false` | Enable Database Monitoring. Required for query metrics, samples, and completions collection. | | `single_endpoint_mode` | boolean | `false` | Required for ClickHouse Cloud. Enables `clusterAllReplicas()` queries to collect data across all nodes behind a single endpoint. | ### Database identifier{% #database-identifier %} | Field | Type | Default | Description | | ------------------------------ | ------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `database_identifier.template` | string | `$server:$port` | Template for the unique database identifier. Supports variables: `$server`, `$port`, and any custom tag keys (for example, `$env`, `$service_name`). | ### Query metrics{% #query-metrics %} Collects aggregated query statistics from `system.query_log`. | Field | Type | Default | Description | | ----------------------------------- | ------- | ------- | ------------------------------------------------------ | | `query_metrics.enabled` | boolean | `true` | Enable query metrics collection. Requires `dbm: true`. | | `query_metrics.collection_interval` | number | `10` | Collection interval in seconds. | ### Query samples{% #query-samples %} Collects currently running queries from `system.processes`. | Field | Type | Default | Description | | ----------------------------------- | ------- | ------- | ------------------------------------------------------ | | `query_samples.enabled` | boolean | `true` | Enable query samples collection. Requires `dbm: true`. | | `query_samples.collection_interval` | number | `1` | Collection interval in seconds. | | `query_samples.payload_row_limit` | integer | `1000` | Maximum number of active queries per snapshot. | ### Query completions{% #query-completions %} Collects records of individual completed queries from `system.query_log`. | Field | Type | Default | Description | | ---------------------------------------------- | ------- | ------- | -------------------------------------------------------------- | | `query_completions.enabled` | boolean | `true` | Enable query completions collection. Requires `dbm: true`. | | `query_completions.collection_interval` | number | `10` | Collection interval in seconds. | | `query_completions.samples_per_hour_per_query` | number | `15` | Maximum samples collected per hour per unique query signature. | - [Database Monitoring](https://docs.datadoghq.com/database_monitoring/) - [ClickHouse Integration](https://docs.datadoghq.com/integrations/clickhouse/) - [Troubleshooting Database Monitoring](https://docs.datadoghq.com/database_monitoring/troubleshooting/) - [Specifying a Database Identifier](https://docs.datadoghq.com/database_monitoring/guide/database_identifier/)