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

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.