Keeping a TDengine cluster running reliably is a core operations task. This article covers the TDengine monitoring architecture and how to configure Grafana, TDinsight, and other visualization tools for runtime monitoring.
TDengine monitoring architecture
TDengine uses a unified monitoring architecture built around four components: the TDengine Cluster (taosd and taosX), taosKeeper, a TDengine monitoring database, and Grafana. Metrics flow from the cluster through taosKeeper into the monitoring database, where Grafana queries and displays them.
Configure taosKeeper
taosKeeper collects and exports TDengine monitoring data. It runs as an independent service, pulling metrics from taosd and taosX and writing them into a TDengine database dedicated to monitoring.
Configuration file location
/etc/taos/taoskeeper.toml
Key configuration items
[monitor]
fqdn = "localhost"
port = 6043
database = "log"
The fqdn field sets the hostname taosKeeper listens on. The port field sets the listening port, default 6043. The database field specifies the target database for monitoring data. Restart taosKeeper after changing these settings.
Deploy the TDinsight monitoring dashboard
TDinsight is the official TDengine Grafana plugin. It provides pre-built dashboards that display node health, query performance, write throughput, and resource usage.
Prerequisites
The following must be installed and running: TDengine, taosAdapter, taosKeeper, and Grafana.
Installing the TDengine data source plugin
grafana-cli plugins install tdengine-datasource
Restart Grafana after installation.
Configuring the data source
In Grafana, go to Configuration, Data Sources, and add a TDengine data source. Set the URL to http://your-taosadapter:6041 and enter the TDengine username and password. Click “Save and Test” to verify.
Importing the TDinsight dashboard
Import using Dashboard ID 18180, or load from: https://grafana.com/grafana/dashboards/18180-tdinsight-for-3-x/
After import, select the TDengine data source from the previous step. The dashboard displays cluster metrics immediately.
Monitoring metrics in detail
taosd monitoring metrics
| Category | Metrics |
|---|---|
| System | CPU, memory, disk usage |
| Query | QPS (Queries Per Second), response time, error rate |
| Write | Write throughput, backlog queue length |
| Connection | Current connections, maximum connections |
System metrics track resource consumption at each node. Query metrics surface slow queries and bottlenecks. Write metrics show ingestion throughput and whether the write queue is backing up. Connection metrics reflect client load per node.
taosX monitoring metrics
taosX exposes process status, Agent processes, Connector subprocesses, and data write tasks. These show whether data ingestion pipelines are healthy and whether subtasks are stalled.
Configure alerting rules
Grafana alerting notifies operators when cluster conditions cross defined thresholds. This example triggers when CPU usage on any TDengine node exceeds 80% for five minutes:
alert: TDengineHighCPU
expr: taosd_cpu_usage > 80
for: 5m
labels:
severity: critical
annotations:
summary: "TDengine node CPU usage is too high"
Other alerts to configure: high memory usage, rising query error rates, write queue backlog, and node-down detection. Grafana can route alerts through email, Slack, PagerDuty, or any supported notification channel.
Visual management UI integration
taosExplorer can embed Grafana dashboards so operators see TDengine’s built-in management pages and external Grafana panels together.
Configuring Grafana
[server]
root_url = http://ip:3000/grafana
serve_from_sub_path = true
[security]
allow_embedding = true
The root_url and serve_from_sub_path settings make Grafana serve under a sub-path. The allow_embedding option permits iframe embedding from taosExplorer. Restart Grafana after making these changes.
Configuring taosExplorer
[grafana.dashboards]
TDengine3 = "http://ip:3000/d/000000001/tdengine3"
taosX = "http://ip:3000/d/000000002/taosx"
Each entry maps a dashboard name to its Grafana URL. After configuration, the linked dashboards appear in taosExplorer alongside native management pages.
Cluster monitoring overview
The Overview page in taosExplorer shows: the count of each type of service component in the cluster, dnode (Data Node) host information, and the running status of each component. This gives operators a fast health check without switching tools.
Summary
- Deploy taosKeeper to collect monitoring data.
- Use TDinsight for visual cluster monitoring.
- Configure alerting rules for your workload thresholds.
- Check monitoring data regularly to catch issues before they affect service.
- Integrate monitoring into your existing operations workflow.
