ClickHouse Monitor
Introduction
The ClickHouse Monitoring O11ySource enables real-time collection of ClickHouse database metrics including queries, memory, connections, replication and storage performance via the Telegraf clickhouse input plugin.
Getting Started
Compatibility
ClickHouse version 22.x and above
Data Collection Method
vuSmartMaps supports the monitoring of your ClickHouse via the Vunet internal collector deployed on the vuSmartMaps server. The Vunet internal collector connects to the ClickHouse HTTP interface (default port 8123, or 8443 for HTTPS/TLS) and queries system tables including system.metrics, system.events, system.asynchronous_metrics, system.replication_queue, system.tables, system.zookeeper, system.processes, system.dictionaries, system.mutations, system.disks, system.detached_parts, and system.text_log to collect server, query, connection, replication, and storage metrics.
Prerequisites
Dependent Configuration
To configure this O11ySource, create a 'credential' of type 'user' under the 'Definition' tab.
Inputs for Configuring Data Source
- Source Name: Unique name to identify this ClickHouse monitoring source
- Server URLs: ClickHouse HTTP(s) endpoint URLs, one per line (e.g. http://host:8123 or https://host:8443). TLS is activated automatically when https:// is used.
- Authentication Method: Select the Authentication Method
- Credential: Credentials to access the storage Array endpoint
- Query Timeout: HTTP timeout for metric collection including connection, redirects and response body (e.g. 5s, 10s)
- Server Variant: Set to "Managed Cloud" for ClickHouse Cloud instances — this skips queries on tables not available in cloud environments (e.g. Zookeeper metrics)
- Auto Discover Cluster Nodes: When enabled, Telegraf queries system.clusters to auto-discover and connect to all nodes in the cluster using the same credentials
- Cluster Filter (Include): Comma-separated list of cluster names to include when auto-discovery is enabled. Leave blank to discover all clusters.
- Cluster Filter (Exclude): Comma-separated list of cluster names to exclude when auto-discovery is enabled.
Firewall Requirement
To collect data from this O11ySource, ensure the following ports are opened:
| Source IP | Destination IP | Destination Port | Protocol | Direction |
|---|---|---|---|---|
| vuSmartMaps IP | ClickHouse server IP | 8123 | TCP | Outbound |
| vuSmartMaps IP | ClickHouse server IP | 8443 | TCP | Outbound |
*Before providing the firewall requirements, please update the port based on the customer environment.
Configuring the Target
Before configuring the O11ySource, ensure that:
The ClickHouse HTTP interface is enabled and accessible on port 8123 (or 8443 for HTTPS). Check http_port (or https_port) in config.xml or config.d/.
A dedicated monitoring user is created with read-only access to system tables: CREATE USER vunet_collector IDENTIFIED WITH sha256_password BY '' SETTINGS PROFILE 'readonly'; GRANT SELECT ON system.* TO vunet_collector;
If HTTPS is used, ensure the ClickHouse server certificate is signed by a CA trusted by the OS on the vuSmartMaps host.
Configuration Steps
Enablethe O11ySource.- Select the sources tab and press Add Source.
- Enter a unique Source Name.
- Enter one or more Server URLs (one per line, e.g. http://192.168.1.10:8123 or https://192.168.1.10:8443). TLS is activated automatically when https:// is used.
- Select the Authentication Method (no_authentication or basic).
- If basic auth is selected, choose the stored Credential.
- Set the Query Timeout (default 5s). Format: number followed by 's', e.g. 10s.
- Select the Server Variant: Self-hosted (default) for on-premises deployments, or Managed Cloud for ClickHouse Cloud instances (this skips queries on tables unavailable in cloud environments such as Zookeeper metrics).
- Set Auto Discover Cluster Nodes to Yes to enable automatic node discovery via system.clusters using the same credentials.
- If auto-discovery is enabled, optionally enter Cluster Filter (Include) and/or Cluster Filter (Exclude) as comma-separated cluster names to control which clusters are discovered.
- Click Save to begin monitoring.
Metrics Collected
| Name | Description | Data Type |
|---|---|---|
| host | Host that collected the metric | LowCardinality(String) |
| name | Metric measurement name | LowCardinality(String) |
| source | Source of the metric (e.g. system.events) | String |
| target | Target ClickHouse instance being monitored | String |
| kafka_topic | Kafka topic the metric was received from | LowCardinality(String) |
| timestamp | Detailed timestamp with milliseconds | DateTime64(3) |
| query | Number of queries to be interpreted and potentially executed | UInt64 |
| select_query | Number of SELECT queries | UInt64 |
| insert_query | Number of INSERT queries | UInt64 |
| failed_query | Number of failed queries | UInt64 |
| failed_select_query | Number of failed SELECT queries | UInt64 |
| failed_insert_query | Number of failed INSERT queries | UInt64 |
| inserted_rows | Number of rows inserted into all tables | UInt64 |
| inserted_bytes | Number of bytes (uncompressed) inserted into all tables | UInt64 |
| selected_rows | Number of rows selected from all tables | UInt64 |
| selected_bytes | Number of bytes (uncompressed) selected from all tables | UInt64 |
| network_receive_bytes | Total bytes received from the network | UInt64 |
| network_send_bytes | Total bytes sent to the network | UInt64 |
| memory_worker_run | Number of runs done by the memory worker | UInt64 |
| memory_worker_run_elapsed_microseconds | Total time spent by the memory worker in microseconds | UInt64 |
| query_time_microseconds | Total time of all queries in microseconds | UInt64 |
| select_query_time_microseconds | Total time of SELECT queries in microseconds | UInt64 |
| insert_query_time_microseconds | Total time of INSERT queries in microseconds | UInt64 |
| merge | Number of launched background merges | UInt64 |
| merge_total_milliseconds | Total time spent on background merges in milliseconds | UInt64 |
| disk_read_elapsed_microseconds | Total time spent waiting for disk reads in microseconds | UInt64 |
| disk_write_elapsed_microseconds | Total time spent waiting for disk writes in microseconds | UInt64 |
| os_read_bytes | Number of bytes read from disks or block devices | UInt64 |
| os_write_bytes | Number of bytes written to disks or block devices | UInt64 |
| zoo_keeper_transactions | Number of ZooKeeper/Keeper operations | UInt64 |
| zoo_keeper_wait_microseconds | Time spent waiting for ZooKeeper/Keeper responses in microseconds | UInt64 |
| _raw_message | Raw message received from Kafka before parsing | String |
| _error | Parsing/ingestion error message, if any | String |
| type | Metric type | String |
| log_uuid | Unique record identifier generated at insert | UUID |
