TDengine clusters that support industrial IoT, connected vehicles, energy systems, and other high-volume workloads need clear runtime visibility. taosKeeper exports TDengine metrics in a format that monitoring systems such as Prometheus can scrape, making it easier to track health, performance, and capacity trends.
What is taosKeeper
taosKeeper is a dedicated monitoring metrics export component for TDengine. Its core job is converting internal TDengine runtime metrics into a standard format that external monitoring systems can consume. With taosKeeper, teams can track query performance, write throughput, storage usage, connection counts, and other key indicators.
The design is lightweight and minimally intrusive. It runs independently on a dedicated port over HTTP without affecting TDengine’s core processing. It integrates with the Prometheus ecosystem and Grafana for building complete monitoring dashboards.
Installation methods
Two installation paths are available:
Method 1: Bundled with the TDengine package. taosKeeper ships with the standard TDengine install package. After installing the TDengine server, the taosKeeper binary is automatically deployed to the system directory. This is the simplest approach for production environments.
Method 2: Build from source. Users can compile from source via the official GitHub repository. This requires a Go development environment:
git clone https://github.com/taosdata/TDengine.git
cd TDengine/src/kit/taosKeeper
go build -o taosKeeper .
sudo cp taosKeeper /usr/local/bin/
After compilation, configure it as a system service if it needs to start automatically after reboot.
Configuration details
taosKeeper supports multiple configuration methods with a priority hierarchy: command-line arguments (highest), environment variables, and configuration file (lowest).
Configuration file. Create taosKeeper.conf:
# taosKeeper listening address
host = 0.0.0.0
# HTTP service port
port = 6043
# TDengine server connection settings
tdengine.host = localhost
tdengine.port = 6030
# Monitoring database name
metrics.database = log
host: Listening IP.0.0.0.0accepts connections from any network interface.port: HTTP service port, default 6043.tdengine.host/tdengine.port: TDengine server connection info.metrics.database: Name of the database storing monitoring data.
Environment variables. Variable names follow the pattern of uppercasing config keys with a TAOSKEEPER_ prefix:
export TAOSKEEPER_HOST="0.0.0.0"
export TAOSKEEPER_PORT="6043"
export TAOSKEEPER_TDENGINE_HOST="localhost"
export TAOSKEEPER_TDENGINE_PORT="6030"
export TAOSKEEPER_METRICS_DATABASE="log"
Command-line arguments. Highest priority, suitable for temporary overrides or automation scripts:
taosKeeper --host 0.0.0.0 --port 6043 --tdengine.host localhost --tdengine.port 6030
Prometheus integration
taosKeeper exposes standard Prometheus metric endpoints:
/metrics: returns standard-format Prometheus monitoring metrics/metrics/v2: returns enhanced metrics with additional label dimensions
Both endpoints return data fully compatible with Prometheus text format.
Prometheus configuration. Add a scrape job to your Prometheus config:
scrape_configs:
- job_name: 'tdengine-taoskeeper'
static_configs:
- targets: ['localhost:6043']
scrape_interval: 15s
scrape_timeout: 10s
After reloading the configuration, TDengine metrics collection begins. A scrape interval of 15 to 30 seconds is a practical starting point for many environments.
Use cases
Runtime metrics export. For daily operations, taosKeeper provides real-time TDengine status data including query response times, write rates, cache hit ratios, and disk I/O. These are key for assessing performance and identifying bottlenecks.
Prometheus and Grafana visualization. Combining taosKeeper with Prometheus and Grafana builds comprehensive monitoring dashboards showing QPS curves, connection trends, and storage usage over time.
Cluster health monitoring. For TDengine clusters, taosKeeper supports multi-node metric collection, enabling centralized monitoring of overall cluster health and timely detection of individual node anomalies.
Startup and verification
Start the service and verify it is running:
taosKeeper --host 0.0.0.0 --port 6043 &
curl http://localhost:6043/health
curl http://localhost:6043/metrics
A response of {"status":"ok"} from the health endpoint or standard Prometheus metrics output indicates successful operation.
Summary
taosKeeper is TDengine’s official lightweight monitoring tool with flexible deployment options. For production environments, integrating it with Grafana and Prometheus is recommended to build a complete database monitoring and alerting mechanism. For production TDengine deployments, taosKeeper provides the operational visibility teams need to troubleshoot performance, watch cluster health, and plan capacity.
