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

Supported Agent versions

7.78+

Data collected

Database Monitoring collects the following data from ClickHouse:

Database instance

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.

Query metrics

Aggregated performance metrics for executed queries, enabling analysis of query behavior and trends over time. Collected from system.query_log.

Query samples

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.

Query completions

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.

Setup

Step 1: Grant Datadog Agent access

Create a dedicated datadog user:

CREATE USER datadog IDENTIFIED BY '<PASSWORD>';

Grant the required permissions on system tables:

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:

GRANT REMOTE ON *.* TO datadog;

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.

# /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: <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

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.

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:

Configuration reference

Connection settings

TLS settings

DBM settings

Database identifier

Query metrics

Collects aggregated query statistics from system.query_log.

Query samples

Collects currently running queries from system.processes.

Query completions

Collects records of individual completed queries from system.query_log.

Additional helpful documentation, links, and articles:

Database MonitoringDOCUMENTATION ClickHouse IntegrationDOCUMENTATION Troubleshooting Database MonitoringDOCUMENTATION Specifying a Database IdentifierDOCUMENTATION