NAME

Catalyst::Plugin::PrometheusTiny - use Prometheus::Tiny with Catalyst

SYNOPSIS

Use the plugin in your application class:

            

              
              
package MyApp;
use Catalyst 'PrometheusTiny';
MyApp->setup;
            
          

Add more metrics:

            

              
              
MyApp->config('Plugin::PrometheusTiny' => {
    metrics => {
        myapp_thing_to_measure => {
            help    => 'Some thing we want to measure',
            type    => 'histogram',
            buckets => [ 1, 50, 100, 1_000, 50_000, 500_000, 1_000_000 ],
        },
        myapp_something_else_to_measure => {
            help    => 'Some other thing we want to measure',
            type    => 'counter',
        },
    },
});
            
          

And somewhere in your controller classes:

            

              
              
$c->prometheus->observe_histogram(
    'myapp_thing_to_measure', $value, { label1 => 'foo' }
);
$c->prometheus->inc(
    'myapp_something_else_to_measure', $value, { label2 => 'bar' }
);
            
          

Once your app has served from requests you can fetch request/response metrics:

            

              
              
curl http://$myappaddress/metrics
            
          

DESCRIPTION

This plugin integrates Prometheus::Tiny::Shared with your Catalyst app, providing some default metrics for requests and responses, with the ability to easily add further metrics to your app. A default controller is included which makes the metrics available via the configured "endpoint", though this can be disabled if you prefer to add your own controller action.

See Prometheus::Tiny for more details of the kind of metrics supported.

The following metrics are included by default:

            

              
              
http_request_duration_seconds => {
    help => 'Request durations in seconds',
    type => 'histogram',
},
http_request_size_bytes => {
    help    => 'Request sizes in bytes',
    type    => 'histogram',
    buckets => [ 1, 50, 100, 1_000, 50_000, 500_000, 1_000_000 ],
},
http_requests_total => {
    help => 'Total number of http requests processed',
    type => 'counter',
},
http_response_size_bytes => {
    help    => 'Response sizes in bytes',
    type    => 'histogram',
    buckets => [ 1, 50, 100, 1_000, 50_000, 500_000, 1_000_000 ],
}
            
          

METHODS

prometheus

            

              
              
sub my_action {
    my ( $self, $c ) = @_;
    $c->prometheus->inc(...);
}
            
          

Returns the Prometheus::Tiny::Shared instance.

CONFIGURATION

endpoint

The endpoint from which metrics are served. Defaults to /metrics.

filename

It is recommended that this is set to a directory on a memory-backed filesystem. See "filename" in Prometheus::Tiny::Shared for details and default value.

ignore_path_regex

            

              
              
ignore_path_regex => '^(healthcheck|foobar)'
            
          

A regular expression against which $c->request->path is checked, and if there is a match then the request is not added to default request/response metrics.

include_action_labels

            

              
              
include_action_labels => 0      # default
            
          

If set to a true value, adds controller and action labels to the default metrics, in addition to the code and method labels.

metrics

            

              
              
metrics => {
    $metric_name => {
        help => $metric_help_text,
        type => $metric_type,
    },
    # more...
}
            
          

See "declare" in Prometheus::Tiny. Declare extra metrics to be added to those included with the plugin.

no_default_controller

            

              
              
no_default_controller => 0      # default
            
          

If set to a true value then the default "endpoint" will not be added, and you will need to add your own controller action for exporting the metrics. Something like:

            

              
              
package MyApp::Controller::Stats;
sub begin : Private { }
sub end  : Private  { }
sub index : Path Args(0) {
    my ( $self, $c ) = @_;
    my $res = $c->res;
    $res->content_type("text/plain");
    $res->output( $c->prometheus->format );
}
            
          

AUTHOR

Peter Mottram (SysPete) <peter@sysnix.com>

CONTRIBUTORS

Curtis "Ovid" Poe

Graham Christensen <graham@grahamc.com>

COPYRIGHT

Copyright (c) 2021 the Catalyst::Plugin::PrometheusTiny "AUTHOR" and "CONTRIBUTORS" as listed above.

LICENSE

This library is free software and may be distributed under the same terms as perl itself.

cpanm Catalyst::Plugin::PrometheusTiny

perl -MCPAN -e shell
install Catalyst::Plugin::PrometheusTiny