InfluxElixir.Write.LineProtocol (InfluxElixir v0.1.30)

Copy Markdown View Source

Encodes Point structs into InfluxDB line protocol format.

Handles tag sorting, field type encoding, escaping, multi-point delimiters, and timestamp conversion.

Line Protocol Format

measurement[,tag_key=tag_val]... field_key=field_val[,field_key=field_val]... [timestamp]

Field Type Encoding

  • Integers: suffixed with i (e.g. 42i)
  • Floats: as-is (e.g. 0.64)
  • Strings: double-quoted (e.g. "hello")
  • Booleans: true or false

Escaping Rules

  • Measurement names: spaces, commas, backslashes
  • Tag keys/values: spaces, commas, equals, backslashes
  • Field keys: spaces, commas, equals, backslashes
  • Field string values: double-quotes, backslashes

Validation

A point that no InfluxDB accepts is refused here, with a tagged error, rather than encoded into a line the server rejects — or worse, one it misreads. Line protocol has no escape for a newline outside a quoted string value, so a newline in a measurement, tag key, tag value or field key ends the line early and the remainder is parsed as a second line: verified against InfluxDB 3, tags: %{"host" => "a\nb"} stores a bogus measurement b. The checks, each verified against the engine:

ProblemError
No fields:empty_fields
Empty measurement:empty_measurement
Measurement not a string, or containing a newline{:invalid_measurement, value}
Tag key empty, not a string, or containing a newline{:invalid_tag_key, key}
Tag value empty, not a string, or containing a newline{:invalid_tag_value, key, value}
Tag key time (reserved on every version){:reserved_tag_key, "time"}
Field key empty, not a string, or containing a newline{:invalid_field_key, key}
Field value not an integer, float, string or boolean{:invalid_field_value, key, value}
Timestamp not a DateTime, integer or nil{:invalid_timestamp, value}

A field named time is left to the server: InfluxDB 3 rejects it and InfluxDB 2 drops it silently. A newline inside a string field value is fine — it is quoted, and both versions store it.

Summary

Types

encode_result()

Functions

encode(point)

Encodes a Point or list of Points into InfluxDB line protocol binary.

encode!(point_or_points)

Encodes a Point or list of Points into InfluxDB line protocol binary.

Types

encode_result()

@type encode_result() :: {:ok, binary()} | {:error, term()}

Functions

encode(point)

@spec encode(InfluxElixir.Write.Point.t() | [InfluxElixir.Write.Point.t()]) ::
  encode_result()

Encodes a Point or list of Points into InfluxDB line protocol binary.

Returns {:ok, binary} on success or {:error, reason} on failure; see "Validation" in the moduledoc for the reasons.

Examples

iex> point = InfluxElixir.Write.Point.new("cpu", %{"value" => 0.64})
iex> {:ok, lp} = InfluxElixir.Write.LineProtocol.encode(point)
iex> lp
"cpu value=0.64"

iex> point = InfluxElixir.Write.Point.new("cpu", %{"count" => 42},
...>   tags: %{"host" => "server01"},
...>   timestamp: 1_630_424_257_000_000_000
...> )
iex> {:ok, lp} = InfluxElixir.Write.LineProtocol.encode(point)
iex> lp
"cpu,host=server01 count=42i 1630424257000000000"

iex> point = InfluxElixir.Write.Point.new("cpu", %{"v" => 1}, tags: %{"host" => ""})
iex> InfluxElixir.Write.LineProtocol.encode(point)
{:error, {:invalid_tag_value, "host", ""}}

encode!(point_or_points)

@spec encode!(InfluxElixir.Write.Point.t() | [InfluxElixir.Write.Point.t()]) ::
  binary()

Encodes a Point or list of Points into InfluxDB line protocol binary.

Raises ArgumentError on failure.

Examples

iex> point = InfluxElixir.Write.Point.new("cpu", %{"value" => 0.64})
iex> InfluxElixir.Write.LineProtocol.encode!(point)
"cpu value=0.64"