++ed by:
Author image Binary.com
and 11 contributors


DataDog::DogStatsd::Helper - helper for DataDog::DogStatsd


    use DataDog::DogStatsd::Helper qw(stats_inc stats_dec stats_timing
                                      stats_gauge stats_count
                                      stats_histogram stats_timed);

    stats_inc('logins'); # shortcut for DataDog::DogStatsd->new->increment('logins')
    stats_dec('logins'); # shortcut for DataDog::DogStatsd->new->decrement('logins')
    stats_timing('test.timing', 1); # ->timing
    stats_gauge('test.gauge', 10); # ->gauge
    stats_count('test.count', 20); # ->count
    stats_histogram('test.histogram', 100); # ->histogram
    stats_event('event title', 'event text'); # ->event

    stats_timed {
        my @param = @_;
        # some code
    } 'test.timing', {tags => \@tags}, @params;



DataDog::DogStatsd::Helper is a helper for DataDog::DogStatsd. It's main purpose is to maintain a global DataDog::DogStatsd object.


For all the functions below, $what is the name of a metric sent to datadog. \%opts is a hash reference which can contain a key tags pointing to an array of tags sent to datadog along with the metric and a key sample_rate with a number between 0 and 1 as value. See https://docs.datadoghq.com/developers/metrics/dogstatsd_metrics_submission/#sample-rates for more information on sample rates.

stats_inc $what, \%opts

equivalent to $dogstatsd->increment($what, \%opts)

stats_inc $what, $sample_rate

equivalent to $dogstatsd->increment($what, +{sample_rate=>$sample_rate})

stats_dec $what, \%opts

equivalent to $dogstatsd->decrement($what, \%opts)

stats_timing $what $millisec, \%opts

equivalent to $dogstatsd->timing($what, $millisec, \%opts)

stats_timing $what $millisec, $sample_rate

equivalent to $dogstatsd->timing($what, $millisec, +{sample_rate=>$sample_rate})

Note, $millisec will be truncated to an integer value.

stats_gauge $what, $measured_value, \%opts

equivalent to $dogstatsd->gauge($what, $measured_value, \%opts)

stats_count $what, $increment, \%opts

equivalent to $dogstatsd->count($what, $increment, \%opts)

stats_histogram $what, $measured_value, \%opts

equivalent to $dogstatsd->histogram($what, $measured_value, \%opts)

stats_event $title, $text, \%opts

equivalent to $dogstatsd->event($what, $title, $text, \%opts)

Naturally, sample_rate does not make sense in \%opts. $opts{tags} is processed as usual. Besides that, the %opts hash can contain the following optional keys:


For more information see https://docs.datadoghq.com/developers/events/dogstatsd/

stats_timed {BLOCK} $what, \%opts, @other_params

this offers a somewhat more convenient interface to timing a piece of code. It's supposed to be called like this:

 my $value = stats_timed {
     # timed piece of code
     my ($p1, $p2, ...) = @_;
 } $what, {tags => \@tags}, $param1, $param2, ...;

Before the code block is executed the current time is taken with Time::HiRes::gettimeofday. Then the code block is executed in an eval environment. If no exception is thrown the time is reported the same way stats_timing does. If the code block ends in an exception, the $what.failure metric is incremented passing the same tags.

If called in scalar context, the code block is also called in scalar context and the resulting value is returned.

If called in list context, the code block is also called in list context and the resulting list is returned.

If called in void context, the code block is also called in void context.


returns the internal DataDog::DogStatsd object. This can be used to modify certain parameters like the namespace.

This function is not exported. It can be called both as function and as class method.


allows to set the internal DataDog::DogStatsd object. Useful mainly for testing.

This function is not exported. It can be called both as function and as class method.


Fayland Lam <fayland@binary.com>


Copyright 2015- Fayland Lam


This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.