README.pod

NAME

Net::Statsd - Perl client for Etsy's statsd daemon

SYNOPSIS

# Configure where to send events
# That's where your statsd daemon is listening.
$Net::Statsd::HOST = 'localhost';    # Default
$Net::Statsd::PORT = 8125;           # Default

#
# Keep track of events as counters
#
Net::Statsd::increment('site.logins');
Net::Statsd::increment('database.connects');

#
# Log timing of events, ex. db queries
#
use Time::HiRes;
my $start_time = [ Time::HiRes::gettimeofday ];

# do the complex database query
Net::Statsd::timing(
    'database.complexquery',
    Time::HiRes::tv_interval($start_time)
);

DESCRIPTION

This module implement a UDP client for the statsd statistics collector daemon in use at Etsy.com.

You want to use this module to track statistics in your Perl application, such as how many times a certain event occurs (user logins in a web application, or database queries issued), or you want to time and then graph how long certain events take, like database queries execution time or time to download a certain file, etc...

If you're uncertain whether you'd want to use this module or statsd, then you can read some background information here:

http://codeascraft.etsy.com/2011/02/15/measure-anything-measure-everything/

The github repository for statsd is:

http://github.com/etsy/statsd

By default the client will try to send statistic metrics to localhost:8125, but you can change the default hostname and port with:

$Net::Statsd::HOST = 'your.statsd.hostname.net';
$Net::Statsd::PORT = 9999;

just after including the Net::Statsd module.

FUNCTIONS

timing($stat, $time, $sample_rate = 1)

Log timing information. Time is assumed to be in milliseconds (ms).

Net::Statsd::timing('some.time', 500);

increment($stats, $sample_rate=1)

Increments one or more stats counters

# +1 on 'some.int'
Net::Statsd::increment('some.int');

# 0.5 = 50% sampling
Net::Statsd::increment('some.int', 0.5);

To increment more than one counter at a time, you can pass an array reference:

Net::Statsd::increment(['grue.dinners', 'room.lamps'], 1);

You can also use "inc()" instead of "increment()" to type less.

decrement($stats, $sample_rate=1)

Same as increment, but decrements. Yay.

Net::Statsd::decrement('some.int')

You can also use "dec()" instead of "decrement()" to type less.

update_stats($stats, $delta=1, $sample_rate=1)

Updates one or more stats counters by arbitrary amounts

Net::Statsd::update_stats('some.int', 10)

equivalent to:

Net::Statsd::update_stats('some.int', 10, 1)

A sampling rate less than 1 means only update the stats every x number of times (0.1 = 10% of the times).

_sample_data(\%data, $sample_rate = 1)

This method is used internally, it's not part of the public interface.

Takes care of transforming a hash of metrics data into a sampled hash of metrics data, according to the given $sample_rate.

If $sample_rate == 1, then sampled data is exactly the incoming data.

If $sample_rate = 0.2, then every metric value will be marked with the given sample rate, so the Statsd server will automatically scale it. For example, with a sample rate of 0.2, the metric values will be multiplied by 5.

send(\%data, $sample_rate = 1)

Squirt the metrics over UDP.

Net::Statsd::send({ 'some.int' => 1 });