# 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. ## FUNCTIONS ### data2line data2line($metric, $single_value); data2line($metric, $values_hashref); data2line($metric, $value, $tags_hashref); data2line($metric, $value, $nanoseconds); data2line($metric, $value, $tags_hashref, $nanoseconds); `data2line` takes various parameters and converts them to an InfluxDB Line. `metric` has to be valid InfluxDB measurement name. Required. `value` can be either a scalar, which will be turned into "value=$value"; or a hashref, if you want to write several values (or a value with another name than "value"). Required. `tags_hashref` is an optional hashref of tag-names and tag-values. `nanoseconds` is an optional integer representing nanoseconds since the epoch. If you do not pass it, `InfluxDB::LineProtocol` will use `Time::HiRes` to get the current timestamp. ### line2data my ($metric, $value_hashref, $tags_hashref, $timestamp) = line2data( $line ); `line2data` parses an InfluxDB line and always returns 4 values. `tags_hashref` is undef if there are no tags! # 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](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 # 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. # POD ERRORS Hey! **The above document had some coding errors, which are explained below:** - Around line 173: L<> starts or ends with whitespace