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 proxy instance. The proxy gathers metrics during the request cycle, but does not submit them to Prometheus::Tiny::Shared until after "finalize" in Catalyst. Using the proxy reduces response time of the request, especially for calls to historgram_observe.

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.