| # Telegraf Plugin |
| |
| ## 1. Product Overview |
| |
| ### 1.1 Telegraf |
| |
| [Telegraf](https://www.influxdata.com/time-series-platform/telegraf/) is an open-source agent designed for collecting, processing, and transmitting metrics and telemetry data, developed by InfluxData. |
| |
| Telegraf offers the following key features: |
| |
| * Plugin Architecture: Telegraf’s power lies in its extensive plugin ecosystem. It supports a wide range of input, output, and processor plugins, seamlessly integrating with various data sources and destinations. |
| * Data Collection: Telegraf excels at gathering metrics from diverse sources, such as system metrics, logs, databases, and more. Its versatility makes it ideal for monitoring applications, infrastructure, and IoT devices. |
| * Output Destinations: Once collected, data can be routed to multiple output destinations, including popular databases like InfluxDB. This flexibility allows Telegraf to adapt to diverse monitoring and analytics setups. |
| * Simple Configuration: Telegraf configurations are managed via TOML files. This simplicity enables users to easily define inputs, outputs, and processors, streamlining customization. |
| * Community & Support: As an open-source project, Telegraf benefits from an active community. Users can contribute plugins, report issues, and seek assistance through forums and documentation. |
| |
| ### 1.2 Telegraf-IoTDB Plugin |
| |
| The Telegraf-IoTDB plugin enables exporting monitoring data stored in Telegraf to IoTDB. This output plugin connects and writes data using the IoTDB session interface. |
| |
|  |
| |
| ## 2. Installation Requirements |
| |
| Telegraf supports multiple operating systems, including Linux, Windows, and macOS. To ensure successful installation, it is recommended to run Telegraf with administrator (root) privileges. For detailed requirements, refer to [Installation Requirements](https://docs.influxdata.com/telegraf/v1/install/). |
| |
| ## 3. Installation Steps |
| |
| For specific installation instructions, see [Installation Steps](https://docs.influxdata.com/telegraf/v1/install/). |
| |
| * Note: This plugin is a built-in plugin of Telegraf and requires no additional installation. |
| |
| ## 4. Usage Guide |
| |
| ### 4.1 Configuring Input Sources |
| |
| In the `telegraf.conf` configuration file, locate the `INPUT PLUGINS` section to define input sources. Key configuration parameters are listed below: |
| |
| | **Parameter** | **Description** | **Notes** | |
| | --------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | |
| | alias | Name the plugin instance. | | |
| | interval | Frequency for collecting metrics. Adjust this to reduce data rate limits. | Default plugins use a global interval; override here for specific inputs. | |
| | precision | Override the agent’s precision setting. Metrics are rounded to this value. | When set for a service input (e.g., statsd), the database may merge events with identical timestamps. | |
| | collection\_jitter | Override the agent’s collection\_jitter setting. Adds randomness to intervals. | Helps stagger data collection across multiple inputs. | |
| | name\_override | Custom time series path name for output to IoTDB. | The path name must comply with the [syntax rules](../SQL-Manual/Syntax-Rule.md). | |
| | name\_prefix | Prefix appended to the measurement name. | | |
| | name\_suffix | Suffix appended to the measurement name. | | |
| |
|  |
| |
| ### 4.2 Configure Output Source |
| |
| Find the `outputs.iotdb `section in the `telegraf.conf` configuration file to configure the output source. Specific configuration items are shown in the following table. For configuration examples, refer to the [Output Source Examples](https://docs.influxdata.com/telegraf/v1/configuration/#output-configuration-examples). |
| |
| | **Configuration Item** | **Description** | **Before Modification** | **After Modification** | **Notes** | |
| | ------------------------------ | -------------------------------- | -------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------- | |
| | host | IoTDB host address | # host = "127.0.0.1" | host = "deployment host of IoTDB" | Default: 127.0.0.1 | |
| | port | IoTDB port number | # port = "6667" | port = "deployment port of IoTDB" | Default: 6667 | |
| | user | IoTDB username | # user = "root" | user = "IoTDB username" | Default: root | |
| | password | IoTDB password | # password = "root" | password = "IoTDB password" | Default: root | |
| | timestamp\_precision | Timestamp precision | timestamp\_precision = "millisecond" | timestamp\_precision = "same timestamp precision as IoTDB" | Check "timestamp\_precision" field in "iotdb-system.properties" | |
| | sanitize\_tag | Database version compatibility | N/A | sanitize\_tag = "0.13/1.0/1.1/1.2/1.3" | Configure according to the actual IoTDB version | |
| |
|  |
| |
| ### 4.3 Start Telegraf Service |
| |
| ```Bash |
| telegraf -config /path/to/telegraf.conf |
| ``` |
| |
| ## 5. Usage Example |
| |
| The following example demonstrates how to use Telegraf to collect CPU metrics and output them to IoTDB using the Telegraf-IoTDB plugin. |
| |
| 1. Generate a Configuration File |
| |
| Use the `telegraf` command to generate a sample configuration file for CPU input and IoTDB output: |
| |
| ```Bash |
| telegraf --sample-config --input-filter cpu --output-filter iotdb > cpu_iotdb.conf |
| ``` |
| |
| 2. Modify the Input Plugin Configuration |
| |
| In the `cpu_iotdb.conf` file, locate the `[[inputs.cpu]]` section and configure it as follows. The `name_override` field defines the custom time series path in IoTDB: |
| |
| ```Bash |
| # Read metrics about cpu usage |
| [[inputs.cpu]] |
| ## Whether to report per-cpu stats or not |
| percpu = true |
| ## Whether to report total system cpu stats or not |
| totalcpu = true |
| ## If true, collect raw CPU time metrics |
| collect_cpu_time = false |
| ## If true, compute and report the sum of all non-idle CPU states |
| report_active = false |
| ## If true and the info is available then add core_id and physical_id tags |
| core_tags = false |
| name_override = "root.demo.telgraf.cpu" |
| ``` |
| |
| 3. Configure the IoTDB Output Plugin |
| |
| Locate the `[[outputs.iotdb]]` section in `cpu_iotdb.conf` and modify the settings as shown below. Ensure alignment with your IoTDB deployment parameters. |
| |
| | **Configuration Item** | **Description** | **Before Modification** | **After Modification** | **Notes** | |
| | ------------------------------ | -------------------------------- | -------------------------------------- | ------------------------------------------ | ----------------------------------------------------------- | |
| | host | IoTDB host address | # host = "127.0.0.1" | host = "your\_iotdb\_host" | Default: 127.0.0.1 | |
| | port | IoTDB port number | # port = "6667" | port = "your\_iotdb\_port" | Default: 6667 | |
| | user | IoTDB username | # user = "root" | user = "your\_iotdb\_username" | Default: root | |
| | password | IoTDB password | # password = "root" | password = "your\_iotdb\_password" | Default: root | |
| | timestamp\_precision | Timestamp precision | timestamp\_precision = "millisecond" | timestamp\_precision = "same\_as\_iotdb" | Match the timestamp\_precision in iotdb-system.properties | |
| | sanitize\_tag | Database version compatibility | Not present | sanitize\_tag = "0.13/1.0/1.1/1.2/1.3" | Configure based on your IoTDB version | |
| |
| ```Bash |
| # Save metrics to an IoTDB Database |
| [[outputs.iotdb]] |
| ## Configuration of IoTDB server connection |
| host = "127.0.0.1" |
| # port = "6667" |
| |
| ## Configuration of authentication |
| # user = "root" |
| # password = "root" |
| |
| ## Timeout to open a new session. |
| ## A value of zero means no timeout. |
| # timeout = "5s" |
| |
| ## Configuration of type conversion for 64-bit unsigned int |
| ## IoTDB currently DOES NOT support unsigned integers (version 13.x). |
| ## 32-bit unsigned integers are safely converted into 64-bit signed integers by the plugin, |
| ## however, this is not true for 64-bit values in general as overflows may occur. |
| ## The following setting allows to specify the handling of 64-bit unsigned integers. |
| ## Available values are: |
| ## - "int64" -- convert to 64-bit signed integers and accept overflows |
| ## - "int64_clip" -- convert to 64-bit signed integers and clip the values on overflow to 9,223,372,036,854,775,807 |
| ## - "text" -- convert to the string representation of the value |
| # uint64_conversion = "int64_clip" |
| |
| ## Configuration of TimeStamp |
| ## TimeStamp is always saved in 64bits int. timestamp_precision specifies the unit of timestamp. |
| ## Available value: |
| ## "second", "millisecond", "microsecond", "nanosecond"(default) |
| timestamp_precision = "millisecond" |
| |
| ## Handling of tags |
| ## Tags are not fully supported by IoTDB. |
| ## A guide with suggestions on how to handle tags can be found here: |
| ## https://iotdb.apache.org/UserGuide/Master/API/InfluxDB-Protocol.html |
| ## |
| ## Available values are: |
| ## - "fields" -- convert tags to fields in the measurement |
| ## - "device_id" -- attach tags to the device ID |
| ## |
| ## For Example, a metric named "root.sg.device" with the tags `tag1: "private"` and `tag2: "working"` and |
| ## fields `s1: 100` and `s2: "hello"` will result in the following representations in IoTDB |
| ## - "fields" -- root.sg.device, s1=100, s2="hello", tag1="private", tag2="working" |
| ## - "device_id" -- root.sg.device.private.working, s1=100, s2="hello" |
| # convert_tags_to = "device_id" |
| ## Handling of unsupported characters |
| ## Some characters in different versions of IoTDB are not supported in path name |
| ## A guide with suggetions on valid paths can be found here: |
| ## for iotdb 0.13.x -> https://iotdb.apache.org/UserGuide/V0.13.x/Reference/Syntax-Conventions.html#identifiers |
| ## for iotdb 1.x.x and above -> https://iotdb.apache.org/UserGuide/V1.3.x/User-Manual/Syntax-Rule.html#identifier |
| ## |
| ## Available values are: |
| ## - "1.0", "1.1", "1.2", "1.3" -- enclose in `` the world having forbidden character |
| ## such as @ $ # : [ ] { } ( ) space |
| ## - "0.13" -- enclose in `` the world having forbidden character |
| ## such as space |
| ## |
| ## Keep this section commented if you don't want to sanitize the path |
| sanitize_tag = "1.3" |
| ``` |
| |
| 4. Run Telegraf with the Configuration File |
| |
| Start Telegraf using the `cpu_iotdb.conf` file. |
| |
| After running Telegraf for a period of time, you can query the collected CPU metrics in IoTDB. Use IoTDB’s CLI or REST API to verify the data. |
