Troubleshooting Disk I/O Performance in ClickHouse


Disk I/O performance is an absolutely critical element of high performance of ClickHouse servers & systems. Troubleshooting disk I/O performance upon observation of any anomalies is helpful in sustaining performance of your system.

Runbook for Troubleshooting Disk I/O Performance

Troubleshooting disk I/O performance in ClickHouse can be a bit challenging, but there are a few things you can do to help identify and resolve the issue.

  1. Monitoring disk I/O: One of the first things you should do is to monitor disk I/O on the server where ClickHouse is running. You can use tools like iostat or iotop to monitor disk I/O and identify whether there are any specific processes or devices that are causing high disk I/O.
  2. Examining system status: You can use the system status endpoint of ClickHouse to examine the performance of the system and identify potential performance bottlenecks. This endpoint returns a JSON object containing various performance metrics, including disk I/O.
  3. Identifying slow queries: You can also use the system.query_log table to identify any slow queries that might be causing high disk I/O. This table contains information about all queries that have been executed by the server, including the execution time, the number of rows read and written, and the number of data bytes read and written.
  4. Checking Data Compression: ClickHouse uses data compression in order to reduce the amount of disk I/O required to read and write data. If the compression ratio is low, it may indicate that the data is not being compressed effectively. Therefore, you can check the compression ratio of the table and make sure that you are using the best compression method for your data.
  5. Checking Data Partitioning: ClickHouse uses data partitioning in order to distribute data across multiple disks. If a large amount of data is concentrated on one disk, it may cause disk I/O problems. Therefore, you can check the partitioning method of the table and make sure that you are using the best partitioning method for your data.
  6. Checking Disk Space: If disk space is running low, it can lead to disk I/O problems. Therefore, you need to check the disk space usage and make sure that there is enough free space on the disk.
  7. Checking Hardware: In some cases, disk I/O problems may be caused by hardware issues, such as a failing disk or a malfunctioning controller. Therefore, you need to check your hardware and make sure that everything is working properly.
  8. Checking Configuration: Make sure that your configuration is appropriate for your use case, for example, increasing the number of merge threads or the number of background threads can help with disk I/O performance.

By monitoring disk I/O, examining system status, identifying slow queries, checking data compression and partitioning, checking disk space, checking hardware and configuration you can help identify and resolve disk I/O performance issues in ClickHouse.

Python script to Monitor Read-Write Operations on ClickHouse Server

import requests
import time

# Set the URL for the ClickHouse server status endpoint
url = 'http://<hostname>:8123/'

while True:
    # Make a GET request to the status endpoint
    response = requests.get(url)
    data = response.json()

    # Extract the read and write information from the response
    read_rows = data['performance_counters']['merges']['read_rows']['value']
    written_rows = data['performance_counters']['merges']['written_rows']['value']

    # Print the read and write information
    print("Read Rows:", read_rows)
    print("Written Rows:", written_rows)

    # Wait for a few seconds before making the next request

Python Script Details

This script uses the requests library to make a GET request to the ClickHouse server status endpoint, which returns a JSON object containing various performance metrics. The script then extracts the read and write information from the JSON object, and prints it to the console. It also uses a while loop to continuously make requests to the status endpoint and print the read and write information, with a 5 seconds delay between each request.

It’s important to note that you need to replace <hostname> with the appropriate value for your ClickHouse server.

You can also customize this script as per your requirements, like storing the read and write information in a file or in a database for future reference or setting alert threshold when the load is high.


It’s also important to note that this script will only work if you have the HTTP interface enabled in your ClickHouse server. You may want to check this setting first, as it’s disabled by default.

It’s also important to mention that the above script only returns the total number of rows read and written since the start of the server. In case you want to monitor read-write operations over a specific period, you need to use ClickHouse system table system.merges or use the query SELECT read_rows, written_rows FROM system.merges that returns the number of rows read and written by the merge tree over the last minute.

To know more about Troubleshooting Disk I/O in ClickHouse, please do consider reading the below articles: 


About Shiv Iyer 215 Articles
Open Source Database Systems Engineer with a deep understanding of Optimizer Internals, Performance Engineering, Scalability and Data SRE. Shiv currently is the Founder, Investor, Board Member and CEO of multiple Database Systems Infrastructure Operations companies in the Transaction Processing Computing and ColumnStores ecosystem. He is also a frequent speaker in open source software conferences globally.