Plack::Middleware::Statsd - send statistics to statsd
version v0.6.3
use Plack::Builder; use Net::Statsd::Tiny; builder { enable "Statsd", client => Net::Statsd::Tiny->new( ... ), sample_rate => 1.0; ... sub { my ($env) = @_; # Send statistics via other middleware if (my $stats = $env->{'psgix.monitor.statsd'}) { $stats->increment('myapp.wibble'); } }; };
This middleware gathers metrics from the application send sends them to a statsd server.
This is a statsd client, such as an instance of Net::Statsd::Tiny.
It is required.
psgix.monitor.statsd will be set to the current client if it is not set.
psgix.monitor.statsd
The only restriction on the client is that it has the same API as Net::Statsd::Tiny or similar modules, by supporting the following methods:
increment
timing_ms or timing
timing_ms
timing
set_add
This has been tested with Net::Statsd::Lite and Net::Statsd::Client.
Other statsd client modules may be used via a wrapper class.
The default sampling rate to be used, which should be a value between 0 and 1. This will override the default rate of the "client", if there is one.
The default is 1.
1
This is a code reference to a wrapper around the "client" timing method. You do not need to set this unless you want to override it.
It takes as arguments the Plack environment and the arguments to pass to the client method, and calls that method. If there are errors then it attempts to log them.
This is a code reference to a wrapper around the "client" increment method. You do not need to set this unless you want to override it.
This is a code reference to a wrapper around the "client" set_add method. You do not need to set this unless you want to override it.
If this is set to "1", then any fatal errors in the PSGI application will be caught and logged, and metrics will continue to be logged.
Alternatively, you may specify a subroutine that handles the errors and returns a valid response, for example.
sub handle_errors { my ( $env, $error ) = @_; if ( my $logger = $env->{'psgix.logger'} ) { $logger->( { level => 'error', message => $error } ); } else { $env->{'psgi.errors'}->print($error); } return [ 503, [ 'Content-Type' => 'text/plain', 'Content-Length' => 11, ], [ 'Unavailable' ] ]; } ... enable "Statsd", catch_errors => \&handle_errors;
This is disabled by default, which means that no metrics will be logged if there is a fatal error.
Added in v0.5.0.
The following metrics are logged:
psgi.request.method.$METHOD
This increments a counter for the request method.
psgi.request.remote_addr
The remote address is added to the set.
psgi.request.content-length
The content-length of the request, if it is specified in the header.
This is treated as a timing rather than a counter, so that statistics can be saved.
psgi.request.content-type.$TYPE.$SUBTYPE
A counter for the content type of request bodies is incremented, e.g. psgi.request.content-type.application.x-www-form-urlencoded.
psgi.request.content-type.application.x-www-form-urlencoded
Any modifiers in the type, e.g. charset, will be ignored.
charset
psgi.response.content-length
The content-length of the response, if it is specified in the header.
psgi.response.content-type.$TYPE.$SUBTYPE
A counter for the content type is incremented, e.g. for a JPEG image, the counter psgi.response.content-type.image.jpeg is incremented.
psgi.response.content-type.image.jpeg
psgi.response.status.$CODE
A counter for the HTTP status code is incremented.
psgi.response.time
The response time, in ms.
As of v0.3.1, this is no longer rounded up to an integer. If this causes problems with your statsd daemon, then you may need to use a subclassed version of your statsd client to work around this.
psgi.response.x-sendfile
This counter is incremented when the X-Sendfile header is added.
X-Sendfile
The header is configured using the plack.xsendfile.type environment key, otherwise the HTTP_X_SENDFILE_TYPE environment variable.
plack.xsendfile.type
HTTP_X_SENDFILE_TYPE
See Plack::Middleware::XSendfile for more information.
psgi.worker.pid
The worker PID is added to the set.
Note that this is set after the request is processed. This means that while the set size can be used to indicate the number of active workers, if the workers are busy (i.e. longer request processing times), then this will show a lower number.
This was added in v0.3.10.
psgix.harakiri
This counter is incremented when the harakiri flag is set.
If you want to rename these, or modify sampling rates, then you will need to use a wrapper class for the "client".
You can access the configured statsd client from Catalyst:
sub finalize { my $c = shift; if (my $statsd = $c->req->env->{'psgix.monitor.statsd'}) { ... } $c->next::method(@_); }
Alternatively, you can use Catalyst::Plugin::Statsd.
Plack::Middleware::SizeLimit version 0.11 supports callbacks that allow you to monitor process size information. In your app.psgi:
use Net::Statsd::Tiny; use Try::Tiny; my $statsd = Net::Statsd::Tiny->new( ... ); builder { enable "Statsd", client => $statsd, sample_rate => 1.0; ... enable "SizeLimit", ... callback => sub { my ($size, $shared, $unshared) = @_; try { $statsd->timing_ms('psgi.proc.size', $size); $statsd->timing_ms('psgi.proc.shared', $shared); $statsd->timing_ms('psgi.proc.unshared', $unshared); } catch { warn $_; }; };
If your application is returning a status code that is not handled by HTTP::Status, then the metrics may not be logged for that reponse.
This does not add a wrapper around the psgix.informational callback. If you are making use of it in your code, then you will need to add metrics logging yourself.
psgix.informational
Since v0.6.0, the this module requires Perl v5.14 or later.
Future releases may only support Perl versions released in the last ten years.
If you need this module on Perl v5.10, please use one of the v0.5.x versions of this module. Significant bug or security fixes may be backported to those versions.
Net::Statsd::Client
Net::Statsd::Tiny
PSGI
The development version is on github at https://github.com/robrwo/Plack-Middleware-Statsd and may be cloned from git://github.com/robrwo/Plack-Middleware-Statsd.git
Please report any bugs or feature requests on the bugtracker website https://github.com/robrwo/Plack-Middleware-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.
Robert Rothenberg <rrwo@cpan.org>
The initial development of this module was sponsored by Science Photo Library https://www.sciencephoto.com.
This software is Copyright (c) 2018-2023 by Robert Rothenberg.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
To install Plack::Middleware::Statsd, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Plack::Middleware::Statsd
CPAN shell
perl -MCPAN -e shell install Plack::Middleware::Statsd
For more information on module installation, please visit the detailed CPAN module installation guide.