NAME

Net::Async::Statsd::Client - asynchronous API for Etsy's statsd protocol

VERSION

version 0.004

SYNOPSIS

use Future;
use IO::Async::Loop;
use Net::Async::Statsd::Client;
my $loop = IO::Async::Loop->new;
$loop->add(my $statsd = Net::Async::Statsd::Client->new(
  host => 'localhost',
  port => 3001,
));
# Wait until the stats are written before proceeding
Future->needs_all(
 $statsd->timing(
  'some.task' => 133,
 ),
 $statsd->gauge(
  'some.value' => 80,
 )
)->get;
# Fire-and-forget stat, record 25% of the time:
$statsd->increment('startup', 0.25);

DESCRIPTION

Provides an asynchronous API for statsd.

METHODS

All public methods return a Future indicating when the write has completed. Since writes are UDP packets, there is no guarantee that the remote will receive the value, so this is mostly intended as a way to detect when statsd writes are slow.

timing

Records timing information in milliseconds. Takes up to three parameters:

• $k - the statsd key

• $v - the elapsed time in milliseconds

• $rate - optional sampling rate

Only the integer part of the elapsed time will be sent.

Example usage:

$statsd->timing('some.key' => $ms, 0.1); # record this 10% of the time

Returns a Future which will be resolved when the write completes.

gauge

Records a current value. Takes up to three parameters:

• $k - the statsd key

• $v - the new value

• $rate - optional sampling rate

Only the integer value will be sent.

Example usage:

$statsd->timing('some.key' => 123);

Returns a Future which will be resolved when the write completes.

delta

Records changed value. Takes up to three parameters:

• $k - the statsd key

• $v - the change (positive or negative)

• $rate - optional sampling rate

Values are truncated to integers.

Example usage:

$statsd->timing('some.key' => -12);

Returns a Future which will be resolved when the write completes.

count

Alias for "delta".

increment

Shortcut for "delta" with a value of +1.

decrement

Shortcut for "delta" with a value of -1.

configure

Standard IO::Async::Notifier configuration - called on construction or manually when values need updating.

Accepts the following named parameters:

• host - the host we'll connect to

• port - the UDP port to send messages to

• default_rate - default sampling rate when none is provided for a given call

• prefix - string to prepend to any stats we record

INTERNAL METHODS

These methods are used internally, and are documented for completeness. They may be of use when subclassing this module.

queue_stat

Queues a statistic for write.

sample

Applies sampling based on the given rate - returns true if we should record this, false otherwise.

default_rate

Default sampling rate. Currently 1 if not overidden in constructor or "configure".

port

Statsd UDP port.

host

Statsd host to connect to.

connect

Establishes the underlying UDP socket.

on_socket

Called when the socket is established.

on_recv

Called if we receive data.

on_recv_error

Called if we had an error while receiving.

SEE ALSO

• Net::Statsd - synchronous implementation

INHERITED METHODS

IO::Async::Notifier

add_child, adopt_future, can_event, children, configure_unknown, debug_printf, get_loop, invoke_error, invoke_event, loop, make_event_cb, maybe_invoke_event, maybe_make_event_cb, new, notifier_name, parent, remove_child, remove_from_parent

AUTHOR

Tom Molesworth <TEAM@cpan.org>

LICENSE

Copyright Tom Molesworth 2014-2016. Licensed under the same terms as Perl itself.

cpanm Net::Async::Statsd

perl -MCPAN -e shell
install Net::Async::Statsd