InfluxDB Line Protocol

GreptimeDB supports HTTP InfluxDB Line protocol.

Ingest data

Protocols

Post metrics

You can write data to GreptimeDB using the /influxdb/write API. Here’s an example of how to use this API:

  • InfluxDB line protocol V2
  • InfluxDB line protocol V1
  1. curl -i -XPOST "http://localhost:4000/v1/influxdb/api/v2/write?db=public&precision=ms" \
  2. --data-binary \
  3. 'monitor,host=127.0.0.1 cpu=0.1,memory=0.4 1667446797450
  4.  monitor,host=127.0.0.2 cpu=0.2,memory=0.3 1667446798450
  5.  monitor,host=127.0.0.1 cpu=0.5,memory=0.2 1667446798450'
  1. curl -i -XPOST "http://localhost:4000/v1/influxdb/write?db=public&precision=ms" \
  2. --data-binary \
  3. 'monitor,host=127.0.0.1 cpu=0.1,memory=0.4 1667446797450
  4.  monitor,host=127.0.0.2 cpu=0.2,memory=0.3 1667446798450
  5.  monitor,host=127.0.0.1 cpu=0.5,memory=0.2 1667446798450'

The /influxdb/write supports query params including:

  • db: Specifies the database to write to. The default value is public.
  • precision: Defines the precision of the timestamp provided in the request body. Accepted values are ns (nanoseconds), us (microseconds), ms (milliseconds), and s (seconds). The data type of timestamps written by this API is TimestampNanosecond, so the default precision is ns (nanoseconds). If you use timestamps with other precisions in the request body, you need to specify the precision using this parameter. This parameter ensures that timestamp values are accurately interpreted and stored with nanosecond precision.

You can also omit the timestamp when sending requests. GreptimeDB will use the current system time (in UTC) of the host machine as the timestamp. For example:

  • InfluxDB line protocol V2
  • InfluxDB line protocol V1
  1. curl -i -XPOST "http://localhost:4000/v1/influxdb/api/v2/write?db=public" \
  2. --data-binary \
  3. 'monitor,host=127.0.0.1 cpu=0.1,memory=0.4
  4.  monitor,host=127.0.0.2 cpu=0.2,memory=0.3
  5.  monitor,host=127.0.0.1 cpu=0.5,memory=0.2'
  1. curl -i -XPOST "http://localhost:4000/v1/influxdb/write?db=public" \
  2. --data-binary \
  3. 'monitor,host=127.0.0.1 cpu=0.1,memory=0.4
  4.  monitor,host=127.0.0.2 cpu=0.2,memory=0.3
  5.  monitor,host=127.0.0.1 cpu=0.5,memory=0.2'

Authentication

GreptimeDB is compatible with InfluxDB’s line protocol authentication format, both V1 and V2. If you have configured authentication in GreptimeDB, you need to provide the username and password in the HTTP request.

  • InfluxDB line protocol V2
  • InfluxDB line protocol V1

InfluxDB’s V2 protocol uses a format much like HTTP’s standard basic authentication scheme.

  1. curl 'http://localhost:4000/v1/influxdb/api/v2/write?db=public' \
  2.     -H 'authorization: token <username>:<password>' \
  3.     -d 'monitor,host=127.0.0.1 cpu=0.1,memory=0.4'

For the authentication format of InfluxDB’s V1 protocol. Add u for user and p for password to the HTTP query string as shown below:

  1. curl 'http://localhost:4000/v1/influxdb/write?db=public&u=<username>&p=<password>' \
  2.     -d 'monitor,host=127.0.0.1 cpu=0.1,memory=0.4'

Telegraf

GreptimeDB’s support for the InfluxDB line protocol ensures its compatibility with Telegraf. To configure Telegraf, simply add GreptimeDB URL into Telegraf configurations:

  • InfluxDB line protocol v2
  • InfluxDB line protocol v1
  1. [[outputs.influxdb_v2]]
  2.   urls = ["http://<host>:4000/v1/influxdb"]
  3.   token = "<greptime_user>:<greptimedb_password>"
  4.   bucket = "<db-name>"
  5.   ## Leave empty
  6.   organization = ""
  1. [[outputs.influxdb]]
  2.   urls = ["http://<host>:4000/v1/influxdb"]
  3.   database = "<db-name>"
  4.   username = "<greptime_user>"
  5.   password = "<greptimedb_password>"

Data model

While you may already be familiar with InfluxDB key concepts, the data model of GreptimeDB is something new to explore. Here are the similarities and differences between the data models of GreptimeDB and InfluxDB:

  • Both solutions are schemaless, eliminating the need to define a schema before writing data.
  • The GreptimeDB table is automatically created with the merge_mode option set to last_non_null. That means the table merges rows with the same tags and timestamp by keeping the latest value of each field, which is the same behavior as InfluxDB.
  • In InfluxDB, a point represents a single data record with a measurement, tag set, field set, and a timestamp. In GreptimeDB, it is represented as a row of data in the time-series table, where the table name aligns with the measurement, and the columns are divided into three types: Tag, Field, and Timestamp.
  • GreptimeDB uses TimestampNanosecond as the data type for timestamp data from the InfluxDB line protocol API.
  • GreptimeDB uses Float64 as the data type for numeric data from the InfluxDB line protocol API.

Consider the following sample data borrowed from InfluxDB docs as an example:

_time_measurementlocationscientist_field_value
2019-08-18T00:00:00Zcensusklamathandersonbees23
2019-08-18T00:00:00Zcensusportlandmullenants30
2019-08-18T00:06:00Zcensusklamathandersonbees28
2019-08-18T00:06:00Zcensusportlandmullenants32

The data mentioned above is formatted as follows in the InfluxDB line protocol:

  1. census,location=klamath,scientist=anderson bees=23 1566086400000000000
  2. census,location=portland,scientist=mullen ants=30 1566086400000000000
  3. census,location=klamath,scientist=anderson bees=28 1566086760000000000
  4. census,location=portland,scientist=mullen ants=32 1566086760000000000

In the GreptimeDB data model, the data is represented as follows in the census table:

  1. +---------------------+----------+-----------+------+------+
  2. | ts                  | location | scientist | bees | ants |
  3. +---------------------+----------+-----------+------+------+
  4. | 2019-08-18 00:00:00 | klamath  | anderson  |   23 | NULL |
  5. | 2019-08-18 00:06:00 | klamath  | anderson  |   28 | NULL |
  6. | 2019-08-18 00:00:00 | portland | mullen    | NULL |   30 |
  7. | 2019-08-18 00:06:00 | portland | mullen    | NULL |   32 |
  8. +---------------------+----------+-----------+------+------+

The schema of the census table is as follows:

  1. +-----------+----------------------+------+------+---------+---------------+
  2. | Column    | Type                 | Key  | Null | Default | Semantic Type |
  3. +-----------+----------------------+------+------+---------+---------------+
  4. | location  | String               | PRI  | YES  |         | TAG           |
  5. | scientist | String               | PRI  | YES  |         | TAG           |
  6. | bees      | Float64              |      | YES  |         | FIELD         |
  7. | ts        | TimestampNanosecond  | PRI  | NO   |         | TIMESTAMP     |
  8. | ants      | Float64              |      | YES  |         | FIELD         |
  9. +-----------+----------------------+------+------+---------+---------------+

Reference