Why not adopt me?
NAME
Mojolicious::Plugin::Statsd - Emit to Statsd, easy!
VERSION
version 0.06
SYNOPSIS
# Mojolicious
$self->plugin('Statsd');
# Mojolicious::Lite
plugin 'Statsd';
# Anywhere you have Mojo helpers available
$app->stats->increment('frobs.adjusted');
# It's safe to pass around if need be
my $stats = $app->stats;
# Only sample half of the time
$stats->increment('frobs.discarded', 0.5);
# Time a code section
$stats->timing('frobnicate' => sub {
# section to be timed
});
# Or do it yourself
$stats->timing('frobnicate', $milliseconds);
# Save repetition
my $jobstats = $app->stats->with_prefix('my-special-process.');
# This becomes myapp.my-special-process.foo
$jobstats->increment('foo');DESCRIPTION
Mojolicious::Plugin::Statsd is a Mojolicious plugin which adds a helper for throwing your metrics at statsd.
OPTIONS
adapter
# Mojolicious::Lite
plugin Statsd => {adapter => 'Memory'};The tail-end of a classname in the Mojolicious::Plugin::Statsd::Adapter:: namespace, or an object instance to be used as the adapter.
Defaults to Statsd, which itself defaults to emit to UDP localhost:8125.
Bundled adapters are listed in "SEE ALSO". Adapters MUST implement counter and timing.
prefix
# Mojolicious::Lite
plugin Statsd => {prefix => 'whatever.'};A prefix applied to all recorded metrics. This a simple string concatenation, so if you want to namespace, add the trailing . character yourself. It defaults to your $app->moniker, followed by ..
helper
# Mojolicious::Lite
plugin Statsd => {helper => 'statistics'};The helper name to be installed. Defaults to 'stats'
Other Options
Any further options are passed to the "adapter" during construction, unless you've passed an object already. Refer to the adapter documentation for supported options.
prefix
The current prefix to apply to metric names.
METHODS
register
$plugin->register(Mojolicious->new);
$plugin->register(Mojolicious->new, {prefix => 'foo'});Register plugin in Mojolicious application. The optional second argument is a hashref of "OPTIONS".
with_prefix
my $new = $stats->with_prefix('baz.');Returns a new instance with the given prefix appended to our own prefix, for scoped recording.
counter
$stats->counter('foo', 1);
$stats->counter('bar', 1, 0.5);Record a change to a counter.
increment
$stats->increment($name, $sample_rate);Shortcut for "counter".
decrement
$stats->decrement($name, $sample_rate);Shortcut for "counter".
timing
$stats->timing('foo', 2500, 0.5);
$stats->timing(foo => 0.5, sub { });
$stats->timing(foo => sub { });Record timing.
gauge
$stats->gauge(xyzzy => 76);
$stats->gauge(xyzzy => '+25');
$stats->gauge(xyzzy => -25);Send a gauge update. Some receiving servers accept sending a signed value rather than an absolute value, and this is supported. Note that on those servers, in order to reach a negative value, you must update to 0 first.
set_add
$stats->set_add(things => 42);
$stats->set_add(primes => 1, 3, 5, 7);Add one or more values to a set.
NAMES
In any place a metric name is specified, it can be substituted with an arrayref in order to update several metrics in a single packet, provided your server supports it.
EXAMPLE
use Mojolicious::Lite;
plugin 'Statsd';
hook after_dispatch => sub {
my ($c) = @_;
$c->stats->increment('path.' . $c->req->url->path);
};
#...
app->start;SECURITY CONSIDERATIONS
When using the "set_add" method, be wary of exposing sensitive information like IP addresses, usernames, email addresses or even session ids over insecure channels. One workaround is to log a message digest of the value instead, for example
use Digest::SHA qw/ hmac_sha1 /;
...
$statsd->set_key( "myapp.sessions", hmac_sha1( $session->id, $my_secret_key );Note that the keys should be consistent across worker processes and hosts.
When generating metric names based on untrusted sources (such as HTTP requests), ensure that the metrics contain only printable characters and do not contain colons (":") or pipes ("|"), since these are used by the statsd protocol.
SEE ALSO
Mojolicious::Plugin::Statsd::Adapter::Statsd
Mojolicious::Plugin::Statsd::Adapter::Memory
SOURCE
The development version is on github at https://github.com/robrwo/perl-Mojolicious-Plugin-Statsd and may be cloned from https://github.com/robrwo/perl-Mojolicious-Plugin-Statsd.git
SUPPORT
Only the latest version of this module will be supported.
This module requires Perl v5.16 or later. Future releases may only support Perl versions that are supported by Mojolicious.
Reporting Bugs and Submitting Feature Requests
Please report any bugs or feature requests on the bugtracker website https://github.com/robrwo/perl-Mojolicious-Plugin-Statsd/issues
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
If the bug you are reporting has security implications which make it inappropriate to send to a public issue tracker, then see SECURITY.md for instructions how to report security vulnerabilities.
AUTHOR
Meredith Howard <mhoward@cpan.org>
This module is currently maintained by Robert Rothenberg <perl@rhizomnic.com>.
CONTRIBUTOR
Robert Rothenberg <perl@rhizomnic.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2019, 2026 by Meredith Howard <mhoward@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.