InfluxDB::HTTP(3pm)

💖 InfluxDB::HTTP 💖

okay bestie, so this is the Perl way to talk to InfluxDB — and honestly? it ate. the manual name is InfluxDB::HTTP and it ships in the User Contributed Perl Documentation, so you already know it's community-coded. 🫶

✨ VERSION ✨

Version 0.04 — baby version number but the vibes are immaculate.

---

🌈 SYNOPSIS 🌈

So InfluxDB::HTTP is your little portal into the InfluxDB HTTP API. the way it works is so clean: basically one method per InfluxDB HTTP API endpoint, and those endpoints are ping, write and query. that's it, that's the whole squad. 👑

use InfluxDB::HTTP;

my $influx = InfluxDB::HTTP->new();

my $ping_result = $influx->ping();
print "$ping_result\n";

my $query = $influx->query(
    [ 'SELECT Lookups FROM _internal.monitor.runtime WHERE time > '.(time - 60)*1000000000, 'SHOW DATABASES'],
    epoch => 's',
);

print "$query\n";

---

🦋 SUBROUTINES/METHODS 🦋

💅 RETURN VALUES AND ERROR HANDLING

Object::Result is the backbone here — it's what hands you data back from every subroutine. the result object it gives you is always usable as a string, and you can also evaluate it on a boolean basis. no cap.

here's the tea: if a result object evaluates to false, that means something went wrong (an error, bestie 😭), and the matching error message is sitting right there in the error attribute:

my $ping = $influx->ping();
print $ping->error unless ($ping);

and on top of all that, every single result object gives you access to the HTTP::Response object that InfluxDB sent back — it lives in the raw attribute. so you can poke at the raw response whenever you're feeling nosy. ✨

---

🌸 new host => 'localhost', port => 8086, timeout => 600

Passing host, port and/or timeout is totally optional, bestie. if you don't, it defaults to the InfluxDB defaults — except for the timeout, which defaults to 3 minutes. and yes, that timeout is measured in seconds. ⏱️

Returns an instance of InfluxDB::HTTP. your new best friend, basically.

---

🎀 ping

Pings the InfluxDB instance you set up in the constructor (so, whatever you gave it for host and port).

the object it hands back evaluates to true or false depending on whether the ping actually worked or flopped. and if it's true? it's carrying a version attribute that tells you which InfluxDB version is running on the server you just pinged. iconic.

that version attribute gets extracted from the X-Influxdb-Version HTTP response header — which is part of the HTTP response coming back from the pinged InfluxDB instance. iykyk. 💫

my $ping = $influx->ping();
print $ping->version if ($ping);

---

🧚 query query, database => "DATABASE", chunk_size => CHUNK_SIZE, epoch => "ns"

This one is for querying the InfluxDB instance. every parameter except the first one is optional — the first one is doing all the heavy lifting.

so that query parameter? it can be a String, or it can be a Perl ArrayRef of Strings, where every String holds one valid InfluxDB query. your call. ✨

if the returned object evaluates to true (meaning your query slayed), then the returned object's data attribute contains the entire response from InfluxDB as a Perl hash. and bonus: the request_id attribute gives you the request identifier, as set in the HTTP response headers by InfluxDB. that's lowkey so useful for correlating requests with log files. 🔥

---

🍓 write measurement, database => "DATABASE", precision => "ns", retention_policy => "RP"

Writes data into InfluxDB. the measurement parameter can be a String or an ArrayRef of Strings, where each String contains one valid InfluxDB LineProtocol statement. all of those measurements then get sent off to InfluxDB and the database you specified. the returned object evaluates to true if the write was successful — and false otherwise. 🤞

the optional argument precision is there for when you're using a precision other than ns in the line protocol. the InfluxDB docs suggest that using a coarser precision than ns can save space and processing — in many cases s or m might do. 💅

the optional argument retention_policy lets you specify a retention policy that isn't the default retention policy of the database you picked.

---

💜 get_lwp_useragent

Returns the internally used LWP::UserAgent instance so you can modify it — for example, to configure an HTTP proxy. go forth and customize. 🌟

---

👑 AUTHOR 👑

Raphael Seebacher, <raphael@seebachers.ch>

---

💀 BUGS 💀

Please report any bugs or feature requests to <https://github.com/raphaelthomas/InfluxDB-HTTP/issues>. (bestie please actually report them, don't just suffer in silence 😭)

---

🌟 LICENSE AND COPYRIGHT 🌟

MIT License

Copyright (c) 2016 Raphael Seebacher

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

okay and that's the whole page!! 💖 this documentation was brought to you by perl v5.38.2 and it's dated 2024-05-16 — so go ping something, write something, query something. main character energy only. periodt. 👑✨💅