Net::Dogstatsd - Perl client to Datadog's dogstatsd metrics collector.
Version 1.0.3
This module allows you to send multiple types of metrics to the Datadog service via dogstatsd, a local daemon installed by Datadog agent package.
use Net::Dogstatsd; # Create an object to communicate with Dogstatsd, using default server and # port settings. my $dogstatsd = Net::Dogstatsd->new( host => 'localhost', #optional. Default = 127.0.0.1 port => '8125', #optional. Default = 8125 verbose => 0, #optional. Default = 0 ); # Set, and print, the 'verbose' option value. $dogstatsd->verbose(1); print "In verbose mode." if $dogstatsd->verbose(); # Before sending metrics, we have to get or create a socket to dogstatsd my $socket = $dogstatsd->get_socket(); # Counter metrics can be incremented or decremented # By default, they will be incremented or decremented by 1, unless the # optional 'value' parameter is passed $dogstatsd->increment( name => 'test_metric.sample_counter', value => $increment_value, #optional; default = 1 tags => [ 'env:production', db ], #optional ); $dogstatsd->decrement( name => $metric_name, value => $decrement_value, #optional; default = 1 tags => [ 'env:devel', web ], #optional ); # Gauge metrics can be used for capturing value of something over time # Example: Gas gauge, inventory level, free memory $dogstatsd->gauge( name => 'test_metric.inventory_level', value => $gauge_value, #required - must be a number tags => [ 'warehouse:us' ], #optional ); # Histogram metrics measure the statistical distribution of a set of values. # Provides min/max/avg as well as 75th, 85th, 95th and 99th percentiles. # NOTE: do not use this for timers. Use timer() instead. $dogstatsd->histogram( name => $metric_name, value => $value, tags => [ 'tag1', 'tag2:value', 'tag3' ], #optional ); # Timers are a special type of histogram. $dogstatsd->timer( name => $metric_name, value => $metric_value, unit => $metric_unit, # 'ms' (milliseconds) or 's|sec' (seconds) tags => [ 'tag1', 'tag2:value', 'tag3' ], #optional ); # Set metrics are special counters that can track unique elements in a group. # Example: the number of unique visitors currently on a website $dogstatsd->sets( name => 'unique.site_visitors', value => $account_id, tags => [ 'referer:Google' ], #optional );
Create a new Net::Dogstatsd object that will be used to interact with dogstatsd.
use Net::Dogstatsd; my $dogstatsd = Net::Dogstatsd->new( host => 'localhost', #optional. Default = 127.0.0.1 port => '8125', #optional. Default = 8125 verbose => 1, #optional. Default = 0 );
Get or set the 'verbose' property.
my $verbose = $dogstatsd->verbose(); $dogstatsd->verbose( 1 );
Create a new socket, if one does not already exist.
my $socket = $dogstatsd->get_socket();
Increment a counter metric. Include optional 'value' argument to increment by >1. Include optional arrayref of tags/tag-values.
$dogstatsd->increment( name => $metric_name, value => $increment_value, #optional; default = 1 ); $dogstatsd->increment( name => $metric_name, value => $increment_value, #optional; default = 1 tags => [ tag1, tag2:value, tag3 ], );
Decrement a counter metric. Include optional 'value' argument to decrement by >1. Include optional arrayref of tags/tag-values.
$dogstatsd->decrement( name => $metric_name, value => $decrement_value, #optional; default = 1 ); $dogstatsd->decrement( name => $metric_name, value => $decrement_value, #optional; default = 1 tags => [ tag1, tag2:value, tag3 ], );
Send a 'gauge' metric. ex: gas gauge value, inventory stock level Value must be positive number. Include optional arrayref of tags/tag-values.
$dogstatsd->gauge( name => $metric_name, value => $gauge_value, ); $dogstatsd->gauge( name => $metric_name, value => $gauge_value, tags => [ 'tag1', 'tag2:value', 'tag3' ], );
Send a 'histogram' metric. Provides min/max/avg as well as 75th, 85th, 95th and 99th percentiles. NOTE: do not use this for timers. Use timer() instead. Include optional arrayref of tags/tag-values.
$dogstatsd->histogram( name => $metric_name, value => $value, ); $dogstatsd->histogram( name => $metric_name, value => $value, tags => [ 'tag1', 'tag2:value', 'tag3' ], );
Send a 'timer' metric. Provides min/max/avg as well as 75th, 85th, 95th and 99th percentiles. Ex: time to run a database query. Include optional arrayref of tags/tag-values.
$dogstatsd->timer( name => $metric_name, value => $metric_value, unit => $metric_unit, # 'ms' (milliseconds) or 's|sec' (seconds) ); $dogstatsd->timer( name => $metric_name, value => $metric_value, unit => $metric_unit, # 'ms' (milliseconds) or 's|sec' (seconds) tags => [ 'tag1', 'tag2:value', 'tag3' ], );
Send a 'sets' metric. Used to count the number of unique elements in a group. Ex: unique site visitors. Include optional arrayref of tags/tag-values.
$dogstatsd->sets( name => 'unique.site_visitors', value => $account_id, ); $dogstatsd->sets( name => 'unique.site_visitors', value => $account_id, tags => [ 'tag1', 'tag2:value', 'tag3' ], );
$self->_counter( action => [ increment | decrement ], %args );
$self->_error_checks( %args );
Common error checking for all metric types.
Send metric to stats server.
By default, only basic tests that do not require a connection to Datadog's platform are run in t/.
To run the developer tests, you will need to do the following:
Sign up to become a Datadog customer ( if you are not already), at https://app.datadoghq.com/signup. Free trial accounts are available.
Install and configure Datadog agent software (requires python 2.6) https://app.datadoghq.com/account/settings#agent
Jennifer Pinkham, <jpinkham at cpan.org>.
<jpinkham at cpan.org>
Please report any bugs or feature requests to the GitHub Issue Tracker at https://github.com/jpinkham/net-dogstatsd/issues. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
You can find documentation for this module with the perldoc command.
perldoc Net::Dogstatsd
You can also look for information at:
Bugs: GitHub Issue Tracker
https://github.com/jpinkham/net-dogstatsd/issues
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Net-Dogstatsd
CPAN Ratings
http://cpanratings.perl.org/d/Net-Dogstatsd
MetaCPAN
https://metacpan.org/release/Net-Dogstatsd
I originally developed this project for ThinkGeek (http://www.thinkgeek.com/). Thanks for allowing me to open-source it!
Copyright 2015 Jennifer Pinkham.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/
To install Net::Dogstatsd, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Dogstatsd
CPAN shell
perl -MCPAN -e shell install Net::Dogstatsd
For more information on module installation, please visit the detailed CPAN module installation guide.