Influx...otocol(3pm)

💖 NAME 💖

InfluxDB::LineProtocol — bestie, this is the module that writes and reads InfluxDB LineProtocol for you. It lives in the User Contributed Perl Documentation section of your man pages, and yes it's a 3pm page, we love that for it.

✨ VERSION ✨

version 1.015 — current, fresh, iconic.

---

🎀 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");

okay so literally two functions and they carry the whole module on their backs, no cap 💅

---

🦋 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 lets you generate such a line from a datastructure, and it handles all the annoying escaping and sorting for you. Obsessed. You can also use it to parse a line — maybe you wanna add some tags to a line that another app wrote, and honestly? valid.

Please read the InfluxDB docs so you understand how metrics, values and tags work. fr fr, do the reading, it's giving homework but it's worth it 📚

InfluxDB::LineProtocol will always try to implement the most current version of the InfluxDB line protocol, while also letting you 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 into an InfluxDB Line. main character behaviour, honestly 👑

• metric — has to be a valid InfluxDB measurement name. Required. No metric, no line, bestie.
• 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 — an optional hashref of tag-names and tag-values.
• nanoseconds — an optional integer representing nanoseconds since the epoch. If you don't pass it, InfluxDB::LineProtocol will use Time::HiRes to get the current timestamp. it'll just grab the time for you, so generous 💖

💫 line2data

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

line2data parses an InfluxDB line and always returns 4 values. Always. Four. Count them.

tags_hashref is undef if there are no tags! like, it's not an empty hash, it's straight-up undef, okay? don't get caught out 🙈

---

⏱️ PRECISION ⏱️

InfluxDB supports 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 you have to tell InfluxDB the precision when posting lines to /write! The module can't do that part for you, that's between you and your /write endpoint 🫶

---

🕰️ 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. blast from the past, but make it functional ✨

Currently supported versions are:

• 0.9.3 and newer — the default, no need to specify anything, just vibe
• **0.9.2 — load via v0.9.2

---

📝 TODO 📝

• check if tag sorting algorithm matches http://golang.org/pkg/bytes/#Compare — yeah, that's the whole todo. it's giving "one thing on the list and it's been there a while" 💀

---

🔍 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. It 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. dynamic duo energy fr 🫶

---

🌈 THANKS 🌈

Thanks to

• validad.com (http://www.validad.com/) — for funding the development of this code. patrons of the arts, honestly 👑
• 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. slay 💅

---

okay that's the whole page bestie, go write some lines ✨ this was perl v5.34.0, dated 2022-05-08, and yes the page header really does say Influx...otocol(3pm) because man pages truncate like that, iconic behaviour, no notes 🌸🦋💖