ClickHouse Troubleshooting: How to use eBPF to Profile Performance

Table of Contents


Using the eBPF-based tool “perf” for troubleshooting ClickHouse involves several steps to collect and analyze performance data. Here’s a general guide on how to utilize “perf” for ClickHouse troubleshooting: 

  1. Install perf:
    • Ensure that the “perf” tool is installed on your system. On most Linux distributions, you can install it using the package manager. For example, on Ubuntu, you can run:
<strong>sudo apt-get install linux-tools-common linux-tools-generic</strong>
  1. Identify the ClickHouse Performance Metrics:
    • Determine the specific performance metrics you want to analyze in ClickHouse. This could include CPU utilization, memory usage, I/O activity, or query execution times.
  2. Run perf with eBPF:
    • Use the “perf” tool with eBPF-based tracing to capture performance data related to ClickHouse. Here are a few examples of how you can use “perf” for ClickHouse troubleshooting:
    • CPU Profiling: Profile CPU usage and identify hotspots in ClickHouse code.
sudo perf record -e cycles:u -g --clickhouse-server <clickhouse_command>
sudo perf report

I/O Profiling:

  • Monitor disk I/O activity for ClickHouse processes.
sudo perf record -e block:block_rq_issue -a
sudo perf report
  • Memory Profiling:
    • Track memory allocation and deallocation in ClickHouse.
sudo perf record -e kmem:* --clickhouse-server <clickhouse_command>
sudo perf report
  • Network Profiling:
    • Analyze network activity of ClickHouse processes.
sudo perf record -e skb:consume_skb --clickhouse-server <clickhouse_command>
sudo perf report
  1. Analyze and Interpret Data:
    • Once you have collected data using “perf” with eBPF, you can analyze and interpret the results to gain insights into ClickHouse performance. Use the various reporting options provided by “perf” to examine the captured data, identify bottlenecks, and understand resource utilization.
  2. Iterate and Refine:
    • Troubleshooting ClickHouse performance often requires an iterative approach. Use the insights from “perf” to refine your analysis and target specific areas or events of interest. Experiment with different “perf” options and eBPF-based tracing to better understand ClickHouse’s performance characteristics.

It’s important to note that ClickHouse-specific tools and monitoring utilities may provide more specialized insights into ClickHouse’s performance. Consider using those tools with “perf” for a comprehensive analysis of ClickHouse’s performance. 

Please consult the official documentation and resources for “perf” and eBPF to learn more about their usage and capabilities, as they can be powerful tools for ClickHouse troubleshooting and performance analysis.


Leveraging the eBPF-based tool “perf” for ClickHouse troubleshooting offers a powerful method to capture and analyze performance data, enabling in-depth insights into CPU, memory, I/O, and network activity. By iteratively refining analysis and combining with ClickHouse-specific tools, users can effectively optimize ClickHouse’s performance and address any bottlenecks with precision.

To know more about eBPF in ClickHouse, do read the following articles: 

About Shiv Iyer 227 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.