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

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.

