NAME
Mojo::Graphite::Writer - A non-blocking Graphite metric writer using the Mojo stack
SYNOPSIS
my $graphite = Mojo::Graphite::Writer->new(address => 'graphite.myhost.com');
my $time = time;
$graphite->write(
"my.metric.one 1 $time",
"my.metric.two 2 $time",
...
);
# preprocessing
$graphite->write(
['my.metric.three', 3],
['my.metric.four', 4, $time],
['my.metric.five', 5, undef, {foo => 'bar'}],
...
);DESCRIPTION
Mojo::Graphite::Writer is a non-blocking client for feeding data to the Graphite metrics collector. This simple module is meant to aid in formattting, batching, and queuing writes to the server in a fork-safe way.
ATTRIBUTES
Mojo::Graphite::Writer inherits all attributes from Mojo::Base and implements the following new ones.
address
Address of the target Graphite server. Required.
batch_size
The number of metrics to send in each write batch. Default is 100.
preprocess
A callback that is used to process a metric specified as an arrayref, the callback is not called on raw strings. The callback is passed the array reference as its only argument, it should return a string to be written, it need not end with a newline.
The default callback expects a metric arrayref to contain a metric name and a value in the first two slots. If the time is not specified in the third slot (or is undef) then the current time will be used. If the fourth slot contains a non-empty hashref then those will be treated as key-value tags. The tags will be cleaned up, removing parenthesis characters and converting spaces to underscores. They will then be formatted by joining keys and values with an equal sign and joined to the metric name with semicolons.
Preprocessing can be fully disabled by setting the attribute to a false value. Passing an array reference without a preprocessing callback will probably not do anything useful.
port
Port of the target Graphite server. Default is 2003.
METHODS
Mojo::Graphite::Writer inherits all methods from Mojo::Base and implements the following new ones.
close
Close the current connection to "address".
connect
Open a new connection to "address":"port" using "client" in Mojo::IOLoop. Any additional arguments are passed through to that method. Returns a Mojo::Promise that resolves with the Mojo::IOLoop::Stream object of the connection.
Note that if the client is already connected, the promise is resolved again with the same stream and will until that stream is closed. In this way, for simple connections, you may simple call "write" while for more complex ones, you may open the connction using this method with additional arguments if needed and then call "write" later.
write
Write metrics to the "connect"-ed graphite server. Metrics are queued and written to the server in a non-blocking way, in the order that "write" is called.
Metrics are strings of the form path value time as documented as "the plaintext protocol". Each string is one metric. It will be line-ending normalized, no newline is required.
Metrics may also be specified as an array reference. If so they will be preprocessed using the callback in "preprocess" which will transform it to a string to be written as documented above. Preprocessing occurs immediately during the call to write.
Writes are batched in groups of size "batch_size". If the writer is not already connected, calling write will implicitly call "connect".
Returns a Mojo::Promise that will be resolved when the metrics passed in this write call are written. The promise is rejected if any write in the write queue fails, even if it is not from the write call.
FUTURE WORK
Future work may include
Possibly a blocking api, though this is questionable
SEE ALSO
THANKS
This module's development was sponsored by ServerCentral Turing Group.
SOURCE REPOSITORY
http://github.com/jberger/Mojo-Graphite-Writer
AUTHOR
Joel Berger, <joel.a.berger@gmail.com>
CONTRIBUTORS
None yet.
THANKS
Mohammad S Anwar (manwar)
COPYRIGHT AND LICENSE
Copyright (C) 2019 by "AUTHOR" and "CONTRIBUTORS"
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.