.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "InfluxDB::LineProtocol 3pm"
.TH InfluxDB::LineProtocol 3pm "2021-01-11" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
InfluxDB::LineProtocol \- Write and read InfluxDB LineProtocol
.SH "VERSION"
.IX Header "VERSION"
version 1.014
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use InfluxDB::LineProtocol qw(data2line line2data);
\&
\&  # convert some Perl data into InfluxDB LineProtocol
\&  my $influx_line = data2line(\*(Aqmeasurement\*(Aq, 42);
\&  my $influx_line = data2line(\*(Aqmeasurement\*(Aq, { cost => 42 });
\&  my $influx_line = data2line(\*(Aqmeasurement\*(Aq, 42, { tag => \*(Aqfoo\*(Aq} );
\&
\&  # convert InfluxDB Line back into Perl
\&  my ($measurement, $values, $tags, $timestamp) =
\&    line2data("metric,location=eu,server=srv1 value=42 1437072299900001000");
.Ve
.SH "DESCRIPTION"
.IX Header "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).
.PP
Please read the InfluxDB docs so you understand how metrics, values
and tags work.
.PP
\&\f(CW\*(C`InfluxDB::LineProtocol\*(C'\fR 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 \f(CW0.9.3\fR and newer
per default, and \f(CW0.9.2\fR if you ask nicely.
.SS "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
\fIdata2line\fR
.IX Subsection "data2line"
.PP
.Vb 5
\& data2line($metric, $single_value);
\& data2line($metric, $values_hashref);
\& data2line($metric, $value, $tags_hashref);
\& data2line($metric, $value, $nanoseconds);
\& data2line($metric, $value, $tags_hashref, $nanoseconds);
.Ve
.PP
\&\f(CW\*(C`data2line\*(C'\fR takes various parameters and converts them to an
InfluxDB Line.
.PP
\&\f(CW\*(C`metric\*(C'\fR has to be valid InfluxDB measurement name. Required.
.PP
\&\f(CW\*(C`value\*(C'\fR can be either a scalar, which will be turned into
\&\*(L"value=$value\*(R"; or a hashref, if you want to write several values (or
a value with another name than \*(L"value\*(R"). Required.
.PP
\&\f(CW\*(C`tags_hashref\*(C'\fR is an optional hashref of tag-names and tag-values.
.PP
\&\f(CW\*(C`nanoseconds\*(C'\fR is an optional integer representing nanoseconds since
the epoch. If you do not pass it, \f(CW\*(C`InfluxDB::LineProtocol\*(C'\fR will use
\&\f(CW\*(C`Time::HiRes\*(C'\fR to get the current timestamp.
.PP
\fIline2data\fR
.IX Subsection "line2data"
.PP
.Vb 1
\&  my ($metric, $value_hashref, $tags_hashref, $timestamp) = line2data( $line );
.Ve
.PP
\&\f(CW\*(C`line2data\*(C'\fR parses an InfluxDB line and always returns 4 values.
.PP
\&\f(CW\*(C`tags_hashref\*(C'\fR is undef if there are no tags!
.SH "PRECISION"
.IX Header "PRECISION"
InfluxDB support different timestamp precisions:
.PP
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
\&\f(CW\*(C`InfluxDB::LineProtocol\*(C'\fR:
.PP
.Vb 1
\&  use InfluxDB::LineProtocol\->import(qw(data2line precision=ms));
.Ve
.PP
Please note that yo have to tell InfluxDB the precision when posting lines to \f(CW\*(C`/write\*(C'\fR!
.SH "LOADING LEGACY PROTOCOL VERSIONS"
.IX Header "LOADING LEGACY PROTOCOL VERSIONS"
To use an old version of the line protocol, specify the version you
want when loading \f(CW\*(C`InfluxDB::LineProtocol\*(C'\fR:
.PP
.Vb 1
\&  use InfluxDB::LineProtocol qw(v0.9.2 data2line);
.Ve
.PP
You will get a version of \f(CW\*(C`data2line\*(C'\fR that conforms to the \f(CW0.9.2\fR
version of the line protocol.
.PP
Currently supported version are:
.IP "\(bu" 4
0.9.3 and newer
.Sp
default, no need to specify anything
.IP "\(bu" 4
0.9.2
.Sp
load via \f(CW\*(C`v0.9.2\*(C'\fR
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
check if tag sorting algorithm matches
<http://golang.org/pkg/bytes/#Compare>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
InfluxDB <https://metacpan.org/pod/InfluxDB> provides access to the
old 0.8 \s-1API.\s0 It also allows searching etc.
.IP "\(bu" 4
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.
.SH "THANKS"
.IX Header "THANKS"
Thanks to
.IP "\(bu" 4
validad.com <http://www.validad.com/> for funding the
development of this code.
.IP "\(bu" 4
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.
.IP "\(bu" 4
mvgrimes <https://github.com/mvgrimes> for fixing a bug when
nanosecond timestamps cause some Perls to render the timestamp in
scientific notation.
.IP "\(bu" 4
Adrian Popa <https://github.com/mad-ady> for fixing a bug when
handling large scientific notation data.
.SH "AUTHOR"
.IX Header "AUTHOR"
Thomas Klausner <domm@plix.at>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2016 \- 2021 by Thomas Klausner.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.