view release on metacpan or  search on metacpan

lib/InfluxDB/HTTP.pm  view on Meta::CPAN

    else {
        $error = $content;
    }

    result {
        raw    { return $response; }
        error  { return $error; }
        <STR>  { return "Error executing query: $error"; }
        <BOOL> { return; }
    }
}

sub write {
    my $self = shift;
    my $measurement = shift;
    my %args = @_;
    my ($database, $precision, $retention_policy) = @args{'database', 'precision', 'retention_policy'};

    die "Missing argument 'measurement'" if !$measurement;
    die "Missing argument 'database'" if !$database;
    die "Argument precision '$precision' is set and not one of (h,m,s,ms,u,ns)" if $precision && $precision !~ /^(h|m|s|ms|u|ns)$/;

    if (ref($measurement) eq 'ARRAY') {
        $measurement = join("\n", @$measurement);
    }

    my $uri = $self->_get_influxdb_http_api_uri('write');

    $uri->query_form(
        db => $database,
        ($precision ? (precision => $precision) : ()),
        ($retention_policy ? (rp => $retention_policy) : ())
    );

    my $response = $self->{lwp_user_agent}->post($uri->canonical(), Content => $measurement);

    chomp(my $content = $response->content());

    if ($response->code() != 204) {
        local $@;
        my $data = eval { decode_json($content) };
        my $error = $@;
        $error = $data->{error} if (!$error && $data);

        result {
            raw    { return $response; }
            error  { return $error; }
            <STR>  { return "Error executing write: $error"; }
            <BOOL> { return; }
        }
    }

    result {
        raw    { return $response; }
        <STR>  { return "Write successful"; }
        <BOOL> { return 1; }
    }
}

sub _get_influxdb_http_api_uri {
    my ($self, $endpoint) = @_;

    die "Missing argument 'endpoint'" if !$endpoint;

    my $uri = URI->new();

    $uri->scheme('http');
    $uri->host($self->{host});
    $uri->port($self->{port});
    $uri->path($endpoint);

    return $uri;
}

1;

__END__

=head1 NAME

InfluxDB::HTTP - The Perl way to interact with InfluxDB!

=head1 VERSION

Version 0.04

=head1 SYNOPSIS

InfluxDB::HTTP allows you to interact with the InfluxDB HTTP API. The module essentially provides
one method per InfluxDB HTTP API endpoint, that is C<ping>, C<write> and C<query>.

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


=head1 SUBROUTINES/METHODS

=head2 RETURN VALUES AND ERROR HANDLING

C<Object::Result> is relied upon for returning data from subroutines. The respective result
object can always be used as string and evaluated on a boolean basis. A result object
evaluating to false indicates an error and a corresponding error message is provided in the
attribute C<error>:

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

Furthermore, all result objects provide access to the C<HTTP::Response> object that is returned
by InfluxDB in the attribute C<raw>.

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

Passing C<host>, C<port> and/or C<timeout> is optional, defaulting to the InfluxDB defaults or
to 3 minutes for the timeout. The timeout is in seconds.

Returns an instance of InfluxDB::HTTP.

=head2 ping

Pings the InfluxDB instance configured in the constructor (i.e. by C<host> and C<port>).

Returned object evaluates to true or false depending on whether the ping was successful or not.
If true, then it contains a C<version> attribute that indicates the InfluxDB version running on
the pinged server.

The C<version> attribute is extracted from the C<X-Influxdb-Version> HTTP response header, which
is part of the HTTP response from the pinged InfluxDB instance.

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

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

Used to query the InfluxDB instance. All parameters but the first one are optional. The
C<query> parameter can either be a String or a Perl ArrayRef of Strings, where every String
contains a valid InfluxDB query.

If the returned object evaluates to true, indicating that the query was successful, then
the returned object's C<data> attribute contains the entire response from InfluxDB as Perl