Performance tuning keeps TDengine TSDB efficient and reliable under real workloads. The main tuning areas are memory configuration, controlled performance testing, bottleneck analysis, query optimization, and continuous monitoring.
Memory optimization strategies
vnode memory configuration
Memory plays a central role in TDengine performance. The core configuration parameters are:
CREATE DATABASE demo (
BUFFER 256, <em>-- Write Buffer</em>
CACHESIZE 256, <em>-- Query Cache</em>
PAGES 256, <em>-- Number of pages</em>
PAGESIZE 4 <em>-- Page size (KB)</em>
);
Memory calculation formula
Total memory = vgroups x Replica x (BUFFER + PAGES x PAGESIZE + CACHESIZE)
This formula helps estimate the memory footprint of a database before deployment. Each vgroup allocates its own buffer, page pool, and query cache. The Replica count multiplies this by the number of copies maintained across the Cluster.
Optimization recommendations
| Workload type | Recommendation |
|---|---|
| High write throughput | Increase BUFFER to accommodate larger write batches and reduce disk flush frequency |
| High query throughput | Increase CACHESIZE to keep more frequently accessed data in the Query Cache |
| Mixed workloads | Balance BUFFER and CACHESIZE based on the observed read/write ratio; monitor memory usage and adjust iteratively |
Performance testing tools
taosBenchmark
taosBenchmark is the official TDengine performance testing tool. It supports both command-line parameters and JSON configuration files for defining test scenarios.
taosBenchmark -d db_name -t 10 -n 1000
taosBenchmark -f config.json
Key parameters include the target database (-d), the number of threads (-t), and the number of records to insert (-n). For more complex scenarios, a JSON configuration file can specify Supertable schemas, data generation rules, and mixed read/write workloads.
JMeter load testing
For scenarios that require simulating application-layer access patterns, Apache JMeter can be used with the TDengine JDBC driver:
- Install the TDengine JDBC driver
- Configure the JMeter data source connection
- Create a test plan that models real workload patterns, including concurrent reads, writes, and subscription queries
This approach is useful for end-to-end performance validation that includes the network stack and application logic.
Bottleneck analysis methods
CPU bottleneck
Identification: Use top -Hp taosd to inspect per-thread CPU usage of the TDengine server process. Look for threads that consistently saturate a single core.
Mitigation: Increase the number of vgroups to distribute processing across more threads. Add additional dnodes (Data Nodes) to the Cluster for horizontal scaling.
Memory bottleneck
Identification: Check system memory pressure with free -h. Inspect TDengine memory allocation with SHOW dnode VARIABLES; to review configured buffer and cache sizes.
Mitigation: Adjust BUFFER and CACHESIZE values to stay within available physical memory. If the working set exceeds available RAM, add physical memory to the node or redistribute data across additional nodes.
Disk I/O bottleneck
Identification: Use iostat -x 1 to monitor disk utilization and I/O wait times. High %util or await values indicate storage is the limiting factor.
Mitigation: Deploy SSDs to improve I/O throughput and reduce latency. Configure multiple physical disks and assign separate data directories to enable parallel read and write operations.
Query optimization techniques
Index optimization
Choose an appropriate Partition Key when creating a Supertable. The Partition Key determines how data is distributed across vgroups. A well-chosen Partition Key reduces the number of vgroups that must be scanned for a given query.
CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT)
TAGS (location BINARY(64), group_id INT);
Query cache
Adjust the Query Cache size to hold frequently accessed result sets in memory. This reduces repeated computation for identical or similar queries.
ALTER DATABASE demo CACHESIZE 256;
The optimal CACHESIZE depends on query patterns: a larger cache benefits dashboards and repeating queries, while a smaller cache frees memory for write buffers in write-heavy deployments.
Pre-aggregation
Use TSMA (Time-range Small Materialized Aggregates) to precompute summary data. For queries that aggregate over fixed time windows, pre-aggregation avoids scanning raw data entirely.
CREATE TABLE precompute AS
SELECT AVG(current) FROM meters INTERVAL(1h);
Pre-aggregated tables are updated automatically as new data arrives, so queries against them always return current results without the cost of scanning the full dataset.
Monitoring and tuning feedback loop
A systematic approach to performance tuning follows a continuous cycle:
Monitor data --> Analyze bottlenecks --> Adjust configuration --> Validate results
^ |
|______________________________________________________________|
Each iteration narrows the gap between observed and target performance. Key metrics to track include:
- Write throughput (rows per second)
- Query latency (P50, P95, P99 percentiles)
- CPU utilization per dnode
- Memory usage relative to configured limits
- Disk I/O throughput and latency
- Cache hit ratio for the Query Cache
Summary
- Configure memory parameters based on workload characteristics and available hardware
- Use performance testing tools to identify bottlenecks under controlled conditions
- Continuously monitor key metrics during production operation
- Establish a tuning feedback loop: measure, analyze, adjust, and validate
- This article was reviewed with post-humanization eiting to remove AI writing patterns and ensure a neutral, precise technical voice.
