NAME

    Mojolicious::Plugin::PrometheusTiny - Export metrics using
    Prometheus::Tiny::Shared

SYNOPSIS

        # Mojolicious
        $self->plugin('PrometheusTiny');
    
        # Mojolicious::Lite
        plugin 'PrometheusTiny';
    
        # Mojolicious::Lite, with custom response buckets (seconds)
        plugin 'PrometheusTiny' => { response_buckets => [qw/4 5 6/] };
    
        # You can add your own route to do access control
        my $under = app->routes->under('/secret' =>sub {
          my $c = shift;
          return 1 if $c->req->url->to_abs->userinfo eq 'Bender:rocks';
          $c->res->headers->www_authenticate('Basic');
          $c->render(text => 'Authentication required!', status => 401);
          return undef;
        });
        plugin PrometheusTiny => {
            route  => $under,
            # You may declare additional metrics with their own TYPE and HELP...
            setup  => sub($app, $p) {
                $p->declare('mojo_random',
                    type => 'gauge',
                    help => "Custom prometheus gauge"
                );
            },
            # ...and set up a callback to update them right before exporting them
            update => sub($c, $p) {
                $p->set(mojo_random => rand(100));
            },
        };

DESCRIPTION

    Mojolicious::Plugin::PrometheusTiny is a Mojolicious plugin that
    exports Prometheus metrics from Mojolicious. It's based on
    Mojolicious::Plugin::Prometheus but uses Prometheus::Tiny::Shared
    instead of Net::Prometheus.

    Default hooks are installed to measure requests response time and count
    requests by HTTP return code, with optional labeling of worker PID and
    HTTP method. It is easy to add custom metrics and update them right
    before the metrics are exported.

    There is no support for namespaces, subsystems or any other fancy
    Net::Prometheus features.

CODE QUALITY NOTICE

    This is BETA code =head1 HELPERS

 prometheus

    Create further instrumentation into your application by using this
    helper which gives access to the Prometheus::Tiny::Shared object. See
    Prometheus::Tiny for usage.

METHODS

    Mojolicious::Plugin::PrometheusTiny inherits all methods from
    Mojolicious::Plugin and implements the following new ones.

 register

      $plugin->register($app, \%config);

    Register plugin in Mojolicious application.

    %config can have:

      * route

      Mojolicious::Routes::Route object to attach the metrics to, defaults
      to generating a new one for '/'.

      Default: /

      * path

      The path to mount the exporter.

      Default: /metrics

      * prometheus

      Override the Prometheus::Tiny::Shared object. The default is a new
      singleton instance of Prometheus::Tiny::Shared.

      * request_buckets

      Override buckets for request sizes histogram.

      Default: [ 1, 10, 100, 1_000, 10_000, 50_000, 100_000, 500_000,
      1_000_000 ]

      * response_buckets

      Override buckets for response sizes histogram.

      Default: [ 1, 10, 100, 1_000, 10_000, 50_000, 100_000, 500_000,
      1_000_000 ]

      * duration_buckets

      Override buckets for request duration setup => sub($app, $p) {
      $p->declare('mojo_random', type => 'gauge', help => "Custom
      prometheus gauge" ); }histogram.

      Default: [1..10, 20, 30, 60, 120, 300, 600, 1_200, 3_600, 6_000,
      12_000]

      * worker_label

      Label metrics by worker PID, which might increase significantly the
      number of Prometheus time series.

      Default: true

      * method_label

      Label metrics by HTTP method, which might increase significantly the
      number of Prometheus time series.

      Default: true

      * setup

      Coderef to be executed during setup. Receives as arguments
      Application and Prometheus instances. Can be used to declare and/or
      initialize new metrics. Though it is trivial to use $app->prometheus
      to declare metrics after plugin setup, code is more readable and
      easier to maintain when actions are listed in their natural order.

      * update

      Coderef to be executed right before invoking exporter action
      configured in path. Receives as arguments Controller and Prometheus
      instances.

METRICS

    This plugin exposes

      * http_requests_total, request counter partitioned over HTTP method
      and HTTP response code

      * http_request_duration_seconds, request duration histogram
      partitioned over HTTP method

      * http_request_size_bytes, request size histogram partitioned over
      HTTP method

      * http_response_size_bytes, response size histogram partitioned over
      HTTP method

TO DO

      * Add optional Net::Prometheus::ProcessCollector-like process
      metrics.

AUTHOR

    Javier Arturo Rodriguez

    A significant part of this code has been ripped off
    Mojolicious::Plugin::Prometheus written by Vidar Tyldum

COPYRIGHT AND LICENSE

    Copyright (c) 2023 by Javier Arturo Rodriguez.

    This program is free software, you can redistribute it and/or modify it
    under the terms of the Artistic License version 2.0.

SEE ALSO

    Mojolicious, Mojolicious::Guides, https://mojolicious.org,
    Mojolicious::Plugin::Prometheus, Prometheus::Tiny,
    Prometheus::Tiny::Shared.