NAME

       "Net::Prometheus" - export monitoring metrics for prometheus

SYNOPSIS

          use Net::Prometheus;

          my $client = Net::Prometheus->new;

          my $counter = $client->new_counter(
             name => "requests",
             help => "Number of received requests",
          );

          sub handle_request
          {
             $counter->inc;
             ...
          }

          use Plack::Builder;

          builder {
             mount "/metrics" => $client->psgi_app;
             ...
          }

DESCRIPTION

       This module provides the ability for a program to collect monitoring metrics and export
       them to the prometheus.io monitoring server.

       As "prometheus" will expect to collect the metrics by making an HTTP request, facilities
       are provided to yield a PSGI application that the containing program can embed in its own
       structure to provide the results, or the application can generate a plain-text result
       directly and serve them by its own means.

   Metrics::Any
       For more flexibility of metrics reporting, other modules may wish to use Metrics::Any as
       an abstraction interface instead of directly using this API.

       By using "Metrics::Any" instead, the module does not directly depend on "Net::Prometheus",
       and in addition program ultimately using the module gets the flexibility to use Prometheus
       (via Metrics::Any::Adapter::Prometheus) or use another reporting system via a different
       adapter.

CONSTRUCTOR

   new
          $prometheus = Net::Prometheus->new;

       Returns a new "Net::Prometheus" instance.

       Takes the following named arguments:

       disable_process_collector => BOOL
           If present and true, this instance will not load the default process collector from
           Net::Prometheus::ProcessCollector. If absent or false, such a collector will be loaded
           by default.

       disable_perl_collector => BOOL
           If present and true, this instance will not load perl-specific collector from
           Net::Prometheus::PerlCollector. If absent or false this collector is loaded by
           default.

           These two options are provided for testing purposes, or for specific use-cases where
           such features are not required. Usually it's best just to leave these enabled.

METHODS

   register
          $collector = $prometheus->register( $collector )

       Registers a new collector to be collected from by the "render" method. The collector
       instance itself is returned, for convenience.

   unregister
          $prometheus->unregister( $collector )

       Removes a previously-registered collector.

   new_gauge
          $gauge = $prometheus->new_gauge( %args )

       Constructs a new Net::Prometheus::Gauge using the arguments given and registers it with
       the exporter. The newly-constructed gauge is returned.

   new_counter
          $counter = $prometheus->new_counter( %args )

       Constructs a new Net::Prometheus::Counter using the arguments given and registers it with
       the exporter. The newly-constructed counter is returned.

   new_summary
          $summary = $prometheus->new_summary( %args )

       Constructs a new Net::Prometheus::Summary using the arguments given and registers it with
       the exporter. The newly-constructed summary is returned.

   new_histogram
          $histogram = $prometheus->new_histogram( %args )

       Constructs a new Net::Prometheus::Histogram using the arguments given and registers it
       with the exporter. The newly-constructed histogram is returned.

   new_metricgroup
          $group = $prometheus->new_metricgroup( %args )

       Returns a new Metric Group instance as a convenience for registering multiple metrics
       using the same "namespace" and "subsystem" arguments. Takes the following named arguments:

       namespace => STR
       subsystem => STR
           String values to pass by default into new metrics the group will construct.

       Once constructed, the group acts as a proxy to the other "new_*" methods, passing in these
       values as overrides.

          $gauge = $group->new_gauge( ... )
          $counter = $group->new_counter( ... )
          $summary = $group->new_summary( ... )
          $histogram = $group->new_histogram( ... )

   collect
          @metricsamples = $prometheus->collect( $opts )

       Returns a list of "MetricSamples" in Net::Prometheus::Types obtained from all of the
       currently-registered collectors.

   render
          $str = $prometheus->render

       Returns a string in the Prometheus text exposition format containing the current values of
       all the registered metrics.

          $str = $prometheus->render( { options => "for collectors" } )

       An optional HASH reference may be provided; if so it will be passed into the "collect"
       method of every registered collector.

       Values that are set to "undef" will be absent from the output (this usually applies to
       gauges). Values set to NaN will be rendered as "NaN".

   handle
          $response = $prometheus->handle( $request )

       Given an HTTP request in an HTTP::Request instance, renders the metrics in response to it
       and returns an HTTP::Response instance.

       This application will respond to any "GET" request, and reject requests for any other
       method. If a query string is present on the URI it will be parsed for collector options to
       pass into the "render" method.

       This method is useful for integrating metrics into an existing HTTP server application
       which uses these objects. For example:

          my $prometheus = Net::Prometheus->new;

          sub serve_request
          {
             my ( $request ) = @_;

             if( $request->uri->path eq "/metrics" ) {
                return $prometheus->handle( $request );
             }

             ...
          }

   psgi_app
          $app = $prometheus->psgi_app

       Returns a new PSGI application as a "CODE" reference. This application will render the
       metrics in the Prometheus text exposition format, suitable for scraping by the Prometheus
       collector.

       This application will respond to any "GET" request, and reject requests for any other
       method. If a "QUERY_STRING" is present in the environment it will be parsed for collector
       options to pass into the "render" method.

       This method is useful for integrating metrics into an existing HTTP server application
       which is uses or is based on PSGI. For example:

          use Plack::Builder;

          my $prometheus = Net::Prometheus::->new;

          builder {
             mount "/metrics" => $prometheus->psgi_app;
             ...
          }

   export_to_Future_IO
          $f = $prometheus->export_to_Future_IO( %args )

       Performs the necessary steps to create a minimal HTTP server for exporting metrics over
       HTTP, by using Future::IO directly. This requires "Future::IO" version 0.11 or above, and
       a containing process that has already loaded a non-default loop implementation that
       supports multiple filehandles.

       This new server will listen on its own port number for any incoming request, and will
       serve metrics regardless of path.

       This server is a very small, minimal implementation just sufficient to support
       "prometheus" itself, or simple tools like "wget", "curl" or perhaps a web-browser for
       manual inspection. It is not intended to be a fully-featured HTTP server and certainly
       does not support many HTTP features at all.

       Takes the following named arguments:

       port => INT
           Port number on which to listen for incoming HTTP requests.

       The returned Future instance will remain pending for the entire lifetime of the process.
       If the containing program has nothing else to do it can call the "await" method on it, or
       else combine it with other toplevel event futures it is using for its own purposes.

   export_to_IO_Async
          $prometheus->export_to_IO_Async( $loop, %args )

       Performs the necessary steps to create an HTTP server for exporting metrics over HTTP via
       IO::Async. This will involve creating a new Net::Async::HTTP::Server instance added to the
       loop.

       This new server will listen on its own port number for any incoming request, and will
       serve metrics regardless of path.

       Note this should only be used in applications that don't otherwise have an HTTP server,
       such as self-contained monitoring exporters or exporting metrics as a side-effect of other
       activity. For existing HTTP server applications it is better to integrate with the
       existing request/response processing of the application, such as by using the "handle" or
       "psgi_app" methods.

       Takes the following named arguments:

       port => INT
           Port number on which to listen for incoming HTTP requests.

COLLECTORS

       The toplevel "Net::Prometheus" object stores a list of "collector" instances, which are
       used to generate the values that will be made visible via the "render" method. A collector
       can be any object instance that has a method called "collect", which when invoked is
       passed no arguments and expected to return a list of "MetricSamples" in
       Net::Prometheus::Types structures.

          @metricsamples = $collector->collect( $opts )

       The Net::Prometheus::Metric class is already a valid collector (and hence, so too are the
       individual metric type subclasses). This interface allows the creation of new custom
       collector objects, that more directly collect information to be exported.

       Collectors might choose to behave differently in the presence of some specifically-named
       option; typically to provide extra detail not normally provided (maybe at the expense of
       extra processing time to calculate it).  Collectors must not complain about the presence
       of unrecognised options; the hash is shared among all potential collectors.

TODO

       •       Histogram/Summary 'start_timer' support

       •       Add other "export_to_*" methods for other event systems and HTTP-serving
               frameworks, e.g. Mojo.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>