Skip to content

Commit 95ea2ca

Browse files
leto-bleto-b
authored
add telegraf en in 2.0.x tree (#632)
1 parent 3d793d5 commit 95ea2ca

File tree

2 files changed

+366
-44
lines changed

2 files changed

+366
-44
lines changed

‎src/UserGuide/Master/Tree/Ecosystem-Integration/Telegraf.md‎

Lines changed: 183 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,183 @@
1-
<!--
2-
3-
Licensed to the Apache Software Foundation (ASF) under one
4-
or more contributor license agreements. See the NOTICE file
5-
distributed with this work for additional information
6-
regarding copyright ownership. The ASF licenses this file
7-
to you under the Apache License, Version 2.0 (the
8-
"License"); you may not use this file except in compliance
9-
with the License. You may obtain a copy of the License at
10-
11-
http://www.apache.org/licenses/LICENSE-2.0
12-
13-
Unless required by applicable law or agreed to in writing,
14-
software distributed under the License is distributed on an
15-
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16-
KIND, either express or implied. See the License for the
17-
specific language governing permissions and limitations
18-
under the License.
19-
20-
-->
21-
22-
Comming Soon
1+
# Telegraf Plugin
2+
3+
## 1. Product Overview
4+
5+
### 1.1 Telegraf
6+
7+
[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.
8+
9+
Telegraf offers the following key features:
10+
11+
* 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.
12+
* 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.
13+
* 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.
14+
* Simple Configuration: Telegraf configurations are managed via TOML files. This simplicity enables users to easily define inputs, outputs, and processors, streamlining customization.
15+
* 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.
16+
17+
### 1.2 Telegraf-IoTDB Plugin
18+
19+
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.
20+
21+
![](/img/telegraf-en.png)
22+
23+
## 2. Installation Requirements
24+
25+
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/).
26+
27+
## 3. Installation Steps
28+
29+
For specific installation instructions, see [Installation Steps](https://docs.influxdata.com/telegraf/v1/install/).
30+
31+
* Note: This plugin is a built-in plugin of Telegraf and requires no additional installation.
32+
33+
## 4. Usage Guide
34+
35+
### 4.1 Configuring ​Input Sources
36+
37+
In the `telegraf.conf` configuration file, locate the `INPUT PLUGINS` section to define input sources. Key configuration parameters are listed below:
38+
39+
| **Parameter** | **Description** | **Notes** |
40+
| --------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
41+
| alias | Name the plugin instance. | |
42+
| interval | Frequency for collecting metrics. Adjust this to reduce data rate limits. | Default plugins use a global interval; override here for specific inputs. |
43+
| 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. |
44+
| collection\_jitter | Override the agent’s collection\_jitter setting. Adds randomness to intervals. | Helps stagger data collection across multiple inputs. |
45+
| 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). |
46+
| name\_prefix | Prefix appended to the measurement name. | |
47+
| name\_suffix | Suffix appended to the measurement name. | |
48+
49+
![](/img/Telegraf\_1.png)
50+
51+
### 4.2 Configure Output Source
52+
53+
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).
54+
55+
| **Configuration Item** | **Description** | **Before Modification** | **After Modification** | **Notes** |
56+
| ------------------------------ | -------------------------------- | -------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------- |
57+
| host | IoTDB host address | # host = "127.0.0.1" | host = "deployment host of IoTDB" | Default: 127.0.0.1 |
58+
| port | IoTDB port number | # port = "6667" | port = "deployment port of IoTDB" | Default: 6667 |
59+
| user | IoTDB username | # user = "root" | user = "IoTDB username" | Default: root |
60+
| password | IoTDB password | # password = "root" | password = "IoTDB password" | Default: root |
61+
| timestamp\_precision | Timestamp precision | timestamp\_precision = "millisecond" | timestamp\_precision = "same timestamp precision as IoTDB" | Check "timestamp\_precision" field in "iotdb-system.properties" |
62+
| 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 |
63+
64+
![](/img/Telegraf\_2.png)
65+
66+
### 4.3 Start Telegraf Service
67+
68+
```Bash
69+
telegraf -config /path/to/telegraf.conf
70+
```
71+
72+
## 5. Usage Example
73+
74+
The following example demonstrates how to use Telegraf to collect CPU metrics and output them to IoTDB using the Telegraf-IoTDB plugin.
75+
76+
1. Generate a Configuration File
77+
78+
Use the `telegraf` command to generate a sample configuration file for CPU input and IoTDB output:
79+
80+
```Bash
81+
telegraf --sample-config --input-filter cpu --output-filter iotdb > cpu_iotdb.conf
82+
```
83+
84+
2. Modify the Input Plugin Configuration
85+
86+
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:
87+
88+
```Bash
89+
# Read metrics about cpu usage
90+
[[inputs.cpu]]
91+
## Whether to report per-cpu stats or not
92+
percpu = true
93+
## Whether to report total system cpu stats or not
94+
totalcpu = true
95+
## If true, collect raw CPU time metrics
96+
collect_cpu_time = false
97+
## If true, compute and report the sum of all non-idle CPU states
98+
report_active = false
99+
## If true and the info is available then add core_id and physical_id tags
100+
core_tags = false
101+
name_override = "root.demo.telgraf.cpu"
102+
```
103+
104+
3. Configure the IoTDB Output Plugin
105+
106+
Locate the `[[outputs.iotdb]]` section in `cpu_iotdb.conf` and modify the settings as shown below. Ensure alignment with your IoTDB deployment parameters.
107+
108+
| **Configuration Item** | **Description** | **Before Modification** | **After Modification** | **Notes** |
109+
| ------------------------------ | -------------------------------- | -------------------------------------- | ------------------------------------------ | ----------------------------------------------------------- |
110+
| host | IoTDB host address | # host = "127.0.0.1" | host = "your\_iotdb\_host" | Default: 127.0.0.1 |
111+
| port | IoTDB port number | # port = "6667" | port = "your\_iotdb\_port" | Default: 6667 |
112+
| user | IoTDB username | # user = "root" | user = "your\_iotdb\_username" | Default: root |
113+
| password | IoTDB password | # password = "root" | password = "your\_iotdb\_password" | Default: root |
114+
| timestamp\_precision | Timestamp precision | timestamp\_precision = "millisecond" | timestamp\_precision = "same\_as\_iotdb" | Match the timestamp\_precision in iotdb-system.properties |
115+
| 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 |
116+
117+
```Bash
118+
# Save metrics to an IoTDB Database
119+
[[outputs.iotdb]]
120+
## Configuration of IoTDB server connection
121+
host = "127.0.0.1"
122+
# port = "6667"
123+
124+
## Configuration of authentication
125+
# user = "root"
126+
# password = "root"
127+
128+
## Timeout to open a new session.
129+
## A value of zero means no timeout.
130+
# timeout = "5s"
131+
132+
## Configuration of type conversion for 64-bit unsigned int
133+
## IoTDB currently DOES NOT support unsigned integers (version 13.x).
134+
## 32-bit unsigned integers are safely converted into 64-bit signed integers by the plugin,
135+
## however, this is not true for 64-bit values in general as overflows may occur.
136+
## The following setting allows to specify the handling of 64-bit unsigned integers.
137+
## Available values are:
138+
## - "int64" -- convert to 64-bit signed integers and accept overflows
139+
## - "int64_clip" -- convert to 64-bit signed integers and clip the values on overflow to 9,223,372,036,854,775,807
140+
## - "text" -- convert to the string representation of the value
141+
# uint64_conversion = "int64_clip"
142+
143+
## Configuration of TimeStamp
144+
## TimeStamp is always saved in 64bits int. timestamp_precision specifies the unit of timestamp.
145+
## Available value:
146+
## "second", "millisecond", "microsecond", "nanosecond"(default)
147+
timestamp_precision = "millisecond"
148+
149+
## Handling of tags
150+
## Tags are not fully supported by IoTDB.
151+
## A guide with suggestions on how to handle tags can be found here:
152+
## https://iotdb.apache.org/UserGuide/Master/API/InfluxDB-Protocol.html
153+
##
154+
## Available values are:
155+
## - "fields" -- convert tags to fields in the measurement
156+
## - "device_id" -- attach tags to the device ID
157+
##
158+
## For Example, a metric named "root.sg.device" with the tags `tag1: "private"` and `tag2: "working"` and
159+
## fields `s1: 100` and `s2: "hello"` will result in the following representations in IoTDB
160+
## - "fields" -- root.sg.device, s1=100, s2="hello", tag1="private", tag2="working"
161+
## - "device_id" -- root.sg.device.private.working, s1=100, s2="hello"
162+
# convert_tags_to = "device_id"
163+
## Handling of unsupported characters
164+
## Some characters in different versions of IoTDB are not supported in path name
165+
## A guide with suggetions on valid paths can be found here:
166+
## for iotdb 0.13.x -> https://iotdb.apache.org/UserGuide/V0.13.x/Reference/Syntax-Conventions.html#identifiers
167+
## for iotdb 1.x.x and above -> https://iotdb.apache.org/UserGuide/V1.3.x/User-Manual/Syntax-Rule.html#identifier
168+
##
169+
## Available values are:
170+
## - "1.0", "1.1", "1.2", "1.3" -- enclose in `` the world having forbidden character
171+
## such as @ $ # : [ ] { } ( ) space
172+
## - "0.13" -- enclose in `` the world having forbidden character
173+
## such as space
174+
##
175+
## Keep this section commented if you don't want to sanitize the path
176+
sanitize_tag = "1.3"
177+
```
178+
179+
4. Run Telegraf with the Configuration File
180+
181+
Start Telegraf using the `cpu_iotdb.conf` file.
182+
183+
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.

0 commit comments

Comments
 (0)