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