NAME

InfluxDB::LineProtocol - Write and read InfluxDB LineProtocol

VERSION

version 1.015

SYNOPSIS

  use InfluxDB::LineProtocol qw(data2line line2data);
  # convert some Perl data into InfluxDB LineProtocol
  my $influx_line = data2line('measurement', 42);
  my $influx_line = data2line('measurement', { cost => 42 });
  my $influx_line = data2line('measurement', 42, { tag => 'foo'} );
  # convert InfluxDB Line back into Perl
  my ($measurement, $values, $tags, $timestamp) =
    line2data("metric,location=eu,server=srv1 value=42 1437072299900001000");

DESCRIPTION

InfluxDB <https://influxdb.com> is a rather new time series database. Since version 0.9 they use their LineProtocol <https://influxdb.com/docs/v0.9/write_protocols/line.html> to write time series data into the database. This module allows you to generate such a line from a datastructure, handling all the annoying escaping and sorting for you. You can also use it to parse a line (maybe you want to add some tags to a line written by another app).

Please read the InfluxDB docs so you understand how metrics, values and tags work.

"InfluxDB::LineProtocol" will always try to implement the most current version of the InfluxDB line protocol, while allowing you to also get the old behaviour. Currently we support 0.9.3 and newer per default, and 0.9.2 if you ask nicely.

 data2line($metric, $single_value);
 data2line($metric, $values_hashref);
 data2line($metric, $value, $tags_hashref);
 data2line($metric, $value, $nanoseconds);
 data2line($metric, $value, $tags_hashref, $nanoseconds);

  my ($metric, $value_hashref, $tags_hashref, $timestamp) = line2data( $line );

PRECISION

InfluxDB support different timestamp precisions:

Nanosecond (ns, the default), microseconds (us), milliseconds (ms), seconds (s), minutes (m) and hours (h). If you do not want to generate lines using nanoseconds (which might be a good idea, because InfluxDB uses less space and has better performance if you choose a smaller precision), you can specify the wanted precision on load of "InfluxDB::LineProtocol":

  use InfluxDB::LineProtocol->import(qw(data2line precision=ms));

Please note that yo have to tell InfluxDB the precision when posting lines to "/write"!

LOADING LEGACY PROTOCOL VERSIONS

To use an old version of the line protocol, specify the version you want when loading "InfluxDB::LineProtocol":

  use InfluxDB::LineProtocol qw(v0.9.2 data2line);

You will get a version of "data2line" that conforms to the 0.9.2 version of the line protocol.

Currently supported version are:

• 0.9.3 and newer

  default, no need to specify anything

• 0.9.2

  load via "v0.9.2"

TODO

•

check if tag sorting algorithm matches <http://golang.org/pkg/bytes/#Compare>

SEE ALSO

• InfluxDB <https://metacpan.org/pod/InfluxDB> provides access to the old 0.8 API. It also allows searching etc.
• AnyEvent::InfluxDB <https://metacpan.org/pod/AnyEvent::InfluxDB> - An asynchronous library for InfluxDB time-series database. Does not implement escaping etc, so if you want to use AnyEvent::InfluxDB to send data to InfluxDB you can use InfluxDB::LineProtocol to convert your measurement data structure before sending it via AnyEvent::InfluxDB.

THANKS

Thanks to

• validad.com <http://www.validad.com/> for funding the development of this code.
• Jose Luis Martinez <https://github.com/pplu> for implementing negative & exponential number support and pointing out the change in the line protocol in 0.9.3.
• mvgrimes <https://github.com/mvgrimes> for fixing a bug when nanosecond timestamps cause some Perls to render the timestamp in scientific notation.
• Adrian Popa <https://github.com/mad-ady> for fixing a bug when handling large scientific notation data.
• zachary-bull <https://github.com/zachary-bull> for adding code to escape "=" in tag keys.

AUTHOR

Thomas Klausner <domm@plix.at>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 - 2022 by Thomas Klausner.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.