File Coverage

blib/lib/Graphite/Enumerator.pm

Criterion	Covered	Total	%
statement	24	51	47.0
branch	6	20	30.0
condition	0	5	0.0
subroutine	6	10	60.0
pod	6	6	100.0
total	42	92	45.6

package Graphite::Enumerator;

use 5.14.1;
use Carp qw/croak/;
use LWP::UserAgent;
use JSON;

our $VERSION = '0.01';

# Recognized constructor options:
# - host (base URL)
# - basepath (top-level metric to scan)
# - lwp_options (hashref)

sub new {
    my ($class, %args) = @_;
    $args{host} or croak "No host provided";
    $args{host} =~ m{^https?://} or $args{host} = "http://".$args{host};
    $args{host} =~ m{/$} or $args{host} .= '/';
    if (defined $args{basepath}) {
        $args{basepath} =~ /\.$/ or $args{basepath} .= '.';
    }
    else {
        $args{basepath} = '';
    }
    $args{_finder} = $args{host} . 'metrics/find?format=completer&query=';
    $args{_ua} = LWP::UserAgent->new( %{ $args{lwp_options} || {} } );
    bless \%args, $class;
}

sub enumerate {
    my ($self, $callback, $path, $level) = @_;
    $path //= $self->{basepath};
    $level //= 0;
    my $url = $self->{_finder} . $path;
    my $res = $self->{_ua}->get($url);
    if ($res->is_success) {
        my $completer_answer = eval { decode_json($res->content) };
        if (!$completer_answer) {
            $self->log_warning("URL <$url>: Couldn't decode JSON string: <" . $res->content . ">: $@");
            return 0;
        }
        return 0 if !$completer_answer->{metrics};
        for my $metric (@{ $completer_answer->{metrics} }) {
            if ($metric->{is_leaf}) {
                $callback->($metric->{path}, $level);
            }
            else {
                $self->enumerate($callback, $metric->{path}, $level + 1);
            }
        }
        return 1;
    }
    else {
        $self->log_warning("Can't get <$url>: " . $res->status_line);
        return 0;
    }
}

sub host {
    my ($self) = @_;
    return $self->{host};
}

sub ua {
    my ($self) = @_;
    return $self->{_ua};
}

sub log_message {
    my ($self, $message) = @_;
    print $message, "\n";
}

sub log_warning {
    my ($self, $message) = @_;
    warn $message, "\n";
}

1;

=head1 NAME

Graphite::Enumerator - Utility module to recursively enumerate graphite metrics

=head1 SYNOPSIS

    my $gren = Graphite::Enumerator->new(
        host => 'https://graphite.example.com',
        basepath => 'general.metrics',
        lwp_options => {
            env_proxy => 1,
            keep_alive => 1,
        },
    );
    $gren->enumerate(sub {
        my ($path) = @_;
        print "Found metric $path !\n";
    });

=head1 METHODS

=head2 Graphite::Enumerator->new(%args)

The constructor recognizes 3 arguments:

  host => host name (in that case, the protocol defaults to http) or base URL
  basepath => top-level metric namespace to scan
  lwp_options => hash of options to initialize LWP::UserAgent internally

=head2 $g->enumerate($coderef)

Calls C<$coderef> for each metric under the basepath, with two parameters:
1. the metric name as a string; 2. the depth level of the metric relative
to the base path (starting at 0).

=head2 $g->host

Returns the host passed to the constructor (with eventually
C prepended).

=head2 $g->ua

Returns the internal LWP::UserAgent object.

=head2 $g->log_message($message)

Prints the C<$message> to STDOUT.

=head2 $g->log_warning($message)

Warns about the C<$message>.

=head1 ACKNOWLEDGMENT

This module was originally developed for Booking.com.
With approval from Booking.com, this module was generalized
and put on CPAN, for which the author would like to express
his gratitude.

=head1 AUTHOR

Rafael Garcia-Suarez, [e-mail]

This code is available under the same license as Perl version 5.10.1 or higher.

A git repository for this module is available at L.

=cut