The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-Dogstatsd-1.0.3
River stage zero No dependents
++
/ Net::Dogstatsd

NAME

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

VERSION

Version 1.0.3

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

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