Datadog Database Monitoring (DBM) for ClickHouse provides deep visibility into your ClickHouse clusters 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 ClickHouse versions

21.1 and later (21.x, 22.x, 23.x, 24.x, 25.x). Recommended minimum: 21.1 LTS.

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, cluster, 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;

The system.processes and system.query_log grants are required for DBM query collection. The remaining grants enable collection of core ClickHouse infrastructure metrics.

Step 2: Configure the Agent

For self-hosted deployments, the Datadog Agent must connect to each ClickHouse node individually. Add a separate instances entry per node. A single Agent can monitor multiple nodes by defining multiple instances in the same configuration file.

• HTTP (default): port 8123
• HTTPS/TLS: port 8443 with tls_verify: true

# /etc/datadog-agent/conf.d/clickhouse.d/conf.yaml

init_config:

instances:
  - dbm: true
    server: clickhouse-node-01.example.com
    port: 8123
    username: datadog
    password: <PASSWORD>

    tags:
      - env:production
      - node:clickhouse-01

    query_metrics:
      enabled: true
      collection_interval: 10

    query_samples:
      enabled: true
      collection_interval: 1

    query_completions:
      enabled: true
      collection_interval: 10

  # Add an entry for each additional node
  - dbm: true
    server: clickhouse-node-02.example.com
    port: 8123
    username: datadog
    password: <PASSWORD>

    tags:
      - env:production
      - node:clickhouse-02

    query_metrics:
      enabled: true
      collection_interval: 10

    query_samples:
      enabled: true
      collection_interval: 1

    query_completions:
      enabled: true
      collection_interval: 10

Customizing the database identifier

The database_identifier option controls how the database instance appears in DBM. This is useful when you want meaningful, human-readable identifiers instead of the default server:port format.

instances:
  - dbm: true
    server: clickhouse-01
    port: 8123
    # ... other settings ...

    database_identifier:
      template: "$env-$server:$port"

    tags:
      - env:production

With env:production, server: clickhouse-01, and port: 8123, 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