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>