NAME

Net::Async::Graphite - Request data from graphite

SYNOPSIS

  use Net::Async::Graphite;

  my $graphite = Net::Async::Graphite->new(
      endpoint => 'https://graphite.example.com/',
  );

  # Find (requires graphite-api)
  my $metrics = $graphite->metrics_asperl('foo.*.datum')->get;

  # Download
  my $data = $graphite->render_asperl('foo.*.datum')->get;

  # Draw
  my $png = $graphite->render(png => 'foo.*.datum')->get;
  # or my $png = $graphite->png('foo.*.datum')->get;

  # Draw with gnuplot (requires gnuplot)
  my $ascii = $graphite->plot('foo.*.datum')->get;
  print $ascii;

DESCRIPTION

An interface to Graphite's data-request APIs graphite-web and graphite-api (which include's graphite-web's /render API).

Preliminary support exists in this version for most of the functionality of /render, /metrics/expand, /metrics/find and /metrics/index.json which is described in detail in Net::Async::Graphite::API.

There is also support to pass the raw data obtained from /render into gnuplot, which includes the ability to format it for terminal output. This support will probably be made optional at some point or maybe split into its own package.

BUGS

No attempt is made to configure a timeout for the HTTP request.

See individual components for their bugs that I know about.

OBJECT

Net::Async::Graphite is an object built from individual roles using Moo. It uses IO::Async internally to provide an asynchronous interface to the remote API and so all methods return a Future object.

If you don't know about Future or don't want to, you must only remember to call get on the return value of any Net::Async::Graphite method:

    my $data_when_it_comes = $graphite->render('me.tr.ic');
    ...; # Later
    my $data_finally = $data_when_it_comes->get();

    # or

    my $data_now = $graphite->render('me.tr.ic')->get();

Net::Async::Graphite's API consists of all of the methods, attributes and accessors defined in its roles (and theirs (and theirs (etc.))) which do not begin with an _. Being perl you are welcome to use these private methods, and even dig around inside the object's guts if you wish, but they do not constitute any part of the stable[*] API. You are thus also welcome to deal with the ensuing breakage.

[*] Hahaha.

Net::Async::Graphite's functionality comes from these roles:

Net::Async::Graphite::API

Interface between perl and Graphite's APIs (/metrics and /render). Of most interest are:

username

Mixed in by Net::Async::Graphite::HTTPClient.

password

Mixed in by Net::Async::Graphite::HTTPClient.

endpoint

metrics()

render()

find_target_from_spec()

Net::Async::Graphite::Draw

Render data in various ways after it has been downloaded. Note that Graphite's /render API include its own drawing routines which are not related to or affected by this role. This role uses data obtained from /render API call with format=raw; the relationship ends there.

Of most interest are:

last_value()

plot()

ATTRIBUTES

I don't know if I want these.

default_from

default_until

Default values for from= and until= URI parameters.

SEE ALSO

Net::Async::Graphite::API

Net::Async::Graphite::Draw

Future

Moo

Net::Async::HTTP

AUTHOR

Matthew King <matthew.king@cloudbeds.com>