The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
InfluxDB-Client-Simple-1.00
River stage zero No dependents
++
/ InfluxDB::Client::Simple

NAME

InfluxDB::Client::Simple - The lightweight InfluxDB client

VERSION

Version 1.00

SYNOPSIS

InfluxDB::Client::Simple provides an easy way to interact with an InfluxDB server.

    use InfluxDB::Client::Simple;

    ########################## TCP ##########################
    my $client = InfluxDB::Client::Simple->new( host => 'server.address.com', port => 8086, protocol => 'tcp' ) or die "Can't instantiate client";

    # Check server connectivity
    my $result = $client->ping();
    die "No pong" unless $result;

    # You can also get the server version
    print $result->{version};

    # Read
    $result = $client->query('SELECT "severity_code" FROM "syslog" WHERE ("severity" = \'err\' AND "hostname" =~ /^(srv01|srv02)$/) AND time >= 1558878013531ms and time <= 1609886964827ms', database => 'grafana');

    # Write
    $result = $client->write("testing,host=containment,repo=cadi-libs,file=testfile statement=42,pod=85", database => 'dbname');

    ########################## UDP ##########################
    $client = InfluxDB::Client::Simple->new( host => 'server.address.com', port => 8089, protocol => 'udp', database => 'grafana' ) or die "Can't instantiate client";

    # UDP allows only write()
    $result = $client->write("testing,host=containment,repo=cadi-libs,file=testfile statement=47,pod=89");
    # or with a timestamp
    $result = $client->write("testing,host=containment,repo=cadi-libs,file=testfile statement=47,pod=89 1610462906000");

WHY

In its current state this module offers few additional features over InfluxDB::HTTP (from which it's derived)

The only reasons why you would use this module are:

  • Minimal dependencies (no Object::Result and its dependencies)

  • You want to use UDP protocol for writing

SUBROUTINES/METHODS

new ( [%options] )

Constructor. %otions is a hash with the following keys:

  • database - Database name (default: 'grafana')

  • host - Server hostname (default: 'localhost')

  • port - Server port (default: 8086)

  • protocol - Transport protocol 'udp' or 'tcp' (default: 'tcp') Note that when using the udp protocol, the default behaviour is to avoid dying on errors. (You can change that with the 'strict_udp' option)

  • strict_udp - Boolean value to die on UDP error (false by default)

  • timeout - Timeout value in seconds (default: 180)

ping()

Check the server connectivity.

Returns a hashref which evaluates to true if the connection is ok and to false otherwise. The hashref has the following keys:

  • raw - The raw response from the server

  • error - The error message returned by the server (empty on success)

  • version - The InfluxDB verstion returned by the server through the 'X-Influxdb-Version' header

query( $query [, %options] )

Query the InfluxDB database using the $query passed as first parameter. Optionally %options can be passed as a hash Allowed keys for options are:

  • database - The database to be queried on the InfluxDB server

  • chunksize - The size of the chunks used for the returned data

  • epoch - The precision format (h, m, s, ms, u, ns) for epoch timestamps (default is 'ns' for nanosecond)

Returns a hashref whose keys are:

  • raw - The raw response from the server

  • error - The error message returned by the server (empty on success)

  • data - The InfluxDB data returned by the server

write ($measurement | \@measurements, [%options])

$measurement is the data to be send encoded according to the LineProtocol.

%options can have the following keys:

  • database - The database to be queried on the InfluxDB server

  • retention_policy - The retention policy to be used (if different from the default one)

  • precision - The precision used in the data (if diffectent from the default 'ns')

Returns a hashref whose keys are:

  • raw - The raw response from the server (obviously empty when using UDP)

  • error - The error message returned by the server (empty on success)

send_data ($measurement, \%tags, \%fields, [$timestamp, [%options]])

Write data to the influxDB after converting them into LineProtocol format. (call write() underneath)

$measurement is the name to be used for measurement

\%tags is the tag set associated to this datapoint

\%fields are the field set associated to this datapoint

$timestamp is an optional timestamp value expected to be in the database precision format (default is nanosecond)

\%options are also optional

%options can have the following keys:

  • database - The database to be queried on the InfluxDB server

  • retention_policy - The retention policy to be used (if different from the default one)

  • precision - The precision used in the data (if diffectent from the default 'ns')

Returns a hashref whose keys are:

  • raw - The raw response from the server (obviously empty when using UDP)

  • error - The error message returned by the server (empty on success)

AUTHOR

Arnaud (Arhuman) ASSAD, <aassad at cpan.org>

BUGS

Please report any bugs or feature requests to bug-influxdb-client at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=InfluxDB-Client-Simple. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SEE ALSO

This module is derived from InfluxDB::HTTP. This module borowed code from InfluxDB::LineProtocol

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc InfluxDB::Client::Simple

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is copyright (c) 2020 by Arnaud (Arhuman) ASSAD.

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