iotdb

README

IoTDB Output Plugin

This output plugin saves Telegraf metrics to an Apache IoTDB backend, supporting session connection and data insertion.

Apache IoTDB

Apache IoTDB (Database for Internet of Things) is an IoT native database with high performance for data management and analysis, deployable on the edge and the cloud. Due to its light-weight architecture, high performance and rich feature set together with its deep integration with Apache Hadoop, Spark and Flink, Apache IoTDB can meet the requirements of massive data storage, high-speed data ingestion and complex data analysis in the IoT industrial fields.

For more details consult the Apache IoTDB website or the Apache IoTDB GitHub page.

Getting started

Before using this plugin, please configure the IP address, port number, user name, password and other information of the database server, as well as some data type conversion, time unit and other configurations.

Please see the configuration section for an example configuration.

Metric Translation

IoTDB uses a different data format for metric data than telegraf. It is important to note that depending on the metrics being written, the translation may be lossy. This plugin translates to IoTDB format in the following ways:

Unsigned Integers

IoTDB currently DOES NOT support unsigned integer. There are three available options of converting uint64, which are specified by setting uint64_conversion.

• int64_clip, default option. If an unsigned integer is greater than math.MaxInt64, save it as int64; else save math.MaxInt64 (9223372036854775807).
• int64, force converting an unsigned integer to aint64,no mater what the value it is. This option may lead to exception if the value is greater than int64.
• textforce converting an unsigned integer to a string, no mater what the value it is.

Time Precision

IoTDB supports a variety of time precision. You can specify which precision you want using the timestamp_precision setting. Default is nanosecond. Other options are second, millisecond, microsecond.

Metadata (tags)

IoTDB uses a tree model for metadata while Telegraf uses a tag model (see InfluxDB-Protocol Adapter). There are two available options of converting tags, which are specified by setting convert_tags_to:

• fields. Treat Tags as measurements. For each Key:Value in Tag, convert them into Measurement, Value, DataType, which are supported in IoTDB.
• device_id, default option. Treat Tags as part of device id. Tags constitute a subtree of Name.

For example, there is a metric:

Name="root.sg.device", Tags={tag1="private", tag2="working"}, Fields={s1=100, s2="hello"}

• fields, result: root.sg.device, s1=100, s2="hello", tag1="private", tag2="working"
• device_id, result: root.sg.device.private.working, s1=100, s2="hello"

Global configuration options

In addition to the plugin-specific configuration settings, plugins support additional global and plugin configuration settings. These settings are used to modify metrics, tags, and field or create aliases and configure ordering, etc. See the CONFIGURATION.md for more details.

Secret-store support

This plugin supports secrets from secret-stores for the username and password option. See the secret-store documentation for more details on how to use them.

Configuration

# 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 = "nanosecond"

  ## 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"

Documentation

Index

• type IoTDB
  • func (s *IoTDB) Close() error
  • func (s *IoTDB) Connect() error
  • func (s *IoTDB) Init() error
  • func (*IoTDB) SampleConfig() string
  • func (s *IoTDB) Write(metrics []telegraf.Metric) error

Types

type IoTDB

type IoTDB struct {
	Host            string          `toml:"host"`
	Port            string          `toml:"port"`
	User            config.Secret   `toml:"user"`
	Password        config.Secret   `toml:"password"`
	Timeout         config.Duration `toml:"timeout"`
	ConvertUint64To string          `toml:"uint64_conversion"`
	TimeStampUnit   string          `toml:"timestamp_precision"`
	TreatTagsAs     string          `toml:"convert_tags_to"`
	SanitizeTags    string          `toml:"sanitize_tag"`
	Log             telegraf.Logger `toml:"-"`
	// contains filtered or unexported fields
}

func (*IoTDB) Close

func (s *IoTDB) Close() error

func (*IoTDB) Connect

func (s *IoTDB) Connect() error

func (*IoTDB) Init

func (s *IoTDB) Init() error

Init is for setup, and validating config.

func (*IoTDB) SampleConfig

func (*IoTDB) SampleConfig() string

func (*IoTDB) Write

func (s *IoTDB) Write(metrics []telegraf.Metric) error

Write should write immediately to the output, and not buffer writes (Telegraf manages the buffer for you). Returning an error will fail this batch of writes and the entire batch will be retried automatically.