The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Net-Dogstatsd-1.0.0
River stage zero No dependents
/ Net::Dogstatsd

NAME

Net::Dogstatsd - Perl client to Datadog's dogstatsd metrics collector.

VERSION

Version 1.0.0

SYNOPSIS

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/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 we can start 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
);

MAIN

METHODS

new()

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
);

verbose()

Get or set the 'verbose' property.

my $verbose = $dogstatsd->verbose();
$dogstatsd->verbose( 1 );

get_socket()

Create a new socket, if one does not already exist.

my $socket = $dogstatsd->get_socket();

increment()

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()

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 ],
);

gauge()

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' ],
);

histogram()

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' ],
);

timer()

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' ],
);

sets()

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' ],
);

INTERNAL FUNCTIONS

_counter

$self->_counter(
	action => [ increment | decrement ],
	%args
);

_error_checks()

$self->_error_checks( %args );

Common error checking for all metric types.

_send_metric()

Send metric to stats server.

RUNNING TESTS

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:

AUTHOR

Jennifer Pinkham, <jpinkham at cpan.org>.

BUGS

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.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::Dogstatsd

You can also look for information at:

ACKNOWLEDGEMENTS

I originally developed this project for ThinkGeek (http://www.thinkgeek.com/). Thanks for allowing me to open-source it!

COPYRIGHT & LICENSE

Copyright 2013 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/