TCollector

1. Introduction

TCollector is a lightweight, distributed metrics collection tool designed for time-series data monitoring. It automatically collects performance metrics from servers and applications, such as CPU, memory, disk, and network metrics, and efficiently sends the data to a backend time-series database for storage and analysis. By configuring it with the domain name or IP address and corresponding port of the IoTDB_Adapter service deployed on a specific server, the collected data can be seamlessly ingested into the IoTDB storage engine. This integration takes full advantage of IoTDB's efficient time-series data storage and query performance, as well as its cluster processing capabilities.

2. Prerequisites

Before writing TCollector data to IoTDB, ensure that the following requirements are met:

• IoTDB >= V2.0.5.1 is deployed and running properly.

• IoTDB_Adapter is installed and running properly.

• TCollector is installed.

3. Installation and Configuration

3.1 IoTDB_Adapter Configuration

1. Contact Timecho staff to obtain the IoTDB_Adapter installation package.

2. Extract the package.

   # Version 1.0 is used as an example
   unzip IoTDB_Adapter-1.0.zip

3. Edit conf/application.properties to configure the listening port, IoTDB node addresses, username, password, and path prefix.

# Port on which Adapter listens
port=4242
# IoTDB instance addresses. Separate multiple nodeUrls with ;
iotdb.nodeUrls=127.0.0.1:6667
# Path prefix for data written to IoTDB, such as root.testdb (takes effect when sqlDialect is not table)
iotdb.prefix=root.sg
# IoTDB username
iotdb.user=root
# IoTDB password
iotdb.password=root
# IoTDB SQL dialect (tree/table; default: tree)
iotdb.sqlDialect=table
# IoTDB database (takes effect when sqlDialect is table)
iotdb.database=tcollector
# IoTDB table (takes effect when sqlDialect is table)
iotdb.table=test
# payload_formatter: supports statsd and opentsdb (default)
payload.formatter=opentsdb
# Source data precision (default: seconds; s | milliseconds ms | microseconds us | nanoseconds ns)
time.precision.source=s
# Target IoTDB data precision (default: seconds)
time.precision.iotdb=ms

Note: In the table model, the database specified by iotdb.database must be created in advance.

4. Restart the IoTDB_Adapter service.

/sbin/start.sh

3.2 TCollector Configuration

1. Download and install TCollector. For detailed instructions, see the official documentation.

   • Source code: GitHub

2. Configure the TCollector collector.

• Locate the collector script. Select the appropriate directory for your operating system. The following example uses Linux.

# Source path: collectors/available/{OS}/long-lived
cd tcollector/collectors/available/linux/long-lived

• Deploy the script to the enabled collector directory. For example, copy dfstat.py to tcollector/collectors/enabled/300.

# Using dfstat.py as an example. Target path: collectors/enabled/{collection interval in seconds}/
cp dfstat.py ../../../enabled/300

3. Start TCollector.

Go to the tcollector directory and run the startup script:

./tcollector start -H 127.0.0.1 -p 4242

• -H specifies the IP address of the server where IoTDB_Adapter is running.

• -p specifies the port configured in IoTDB_Adapter's conf/application.properties file.

3.3 Verification

Query the data through the IoTDB CLI to verify that it has been written successfully.

IoTDB:tcollector> select * from test where metric='df.inodes.used' limit 1
+-----------------------------+--------------+---------------------------+-------+---------+-----+---------+----+-----------------------+--------+----+----+-----+--------+-------+----+------+
|                         time|        metric|                       host|  value|collector|iface|direction| dev|                  mount|  fstype|type| cpu|state|endpoint|service|user|cpuset|
+-----------------------------+--------------+---------------------------+-------+---------+-----+---------+----+-----------------------+--------+----+----+-----+--------+-------+----+------+
|2025-07-31T09:49:58.656+08:00|df.inodes.used|iot-VMware-Virtual-Platform|21133.0|     null| null|     null|null|/snap/gnome-42-2204/202|squashfs|null|null| null|    null|   null|null|  null|
+-----------------------------+--------------+---------------------------+-------+---------+-----+---------+----+-----------------------+--------+----+----+-----+--------+-------+----+------+
Total line number = 1
It costs 0.024s