diff --git a/src/UserGuide/Master/Tree/Ecosystem-Integration/Telegraf.md b/src/UserGuide/Master/Tree/Ecosystem-Integration/Telegraf.md index f09fb025d..1cb5848b8 100644 --- a/src/UserGuide/Master/Tree/Ecosystem-Integration/Telegraf.md +++ b/src/UserGuide/Master/Tree/Ecosystem-Integration/Telegraf.md @@ -1,22 +1,183 @@ - - -Comming Soon \ No newline at end of file +# 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. + +![](/img/telegraf-en.png) + +## 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. | | + +![](/img/Telegraf\_1.png) + +### 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 | + +![](/img/Telegraf\_2.png) + +### 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. diff --git a/src/UserGuide/latest/Ecosystem-Integration/Telegraf.md b/src/UserGuide/latest/Ecosystem-Integration/Telegraf.md index f09fb025d..1cb5848b8 100644 --- a/src/UserGuide/latest/Ecosystem-Integration/Telegraf.md +++ b/src/UserGuide/latest/Ecosystem-Integration/Telegraf.md @@ -1,22 +1,183 @@ - - -Comming Soon \ No newline at end of file +# 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. + +![](/img/telegraf-en.png) + +## 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. | | + +![](/img/Telegraf\_1.png) + +### 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 | + +![](/img/Telegraf\_2.png) + +### 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.