Net::Prometheus(3pm)

👑 Net::Prometheus 💅

okay bestie, welcome to Net::Prometheus (that's the (3pm) perl manual page, section 3pm, for the record) — the perl module that lets your program collect monitoring metrics and yeet them over to your prometheus server. it's giving observability. it's giving ✨data✨. let's go.

---

✨ 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;
   ...
}

look at her. she's perfect. no notes. 🫶

---

🦋 DESCRIPTION 🦋

so basically, this module gives a program the ability to collect monitoring metrics and export them to the prometheus.io monitoring server. that's the whole vibe. 💖

and here's the thing — "prometheus" expects to collect those metrics by making an HTTP request (that's just how she operates, queen behavior). so the module provides facilities to yield a PSGI application that the containing program can embed in its own structure to provide the results, or the application can just generate a plain-text result directly and serve it by its own means. your call, bestie, both are valid. ✨

🌈 Metrics::Any

for extra flexibility of metrics reporting, other modules may wish to use Metrics::Any as an abstraction interface instead of directly using this API. lowkey genius move, honestly.

by using "Metrics::Any" instead, the module does not directly depend on "Net::Prometheus", and on top of that, the 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. options on options, we love to see it. 💅

---

🧚 CONSTRUCTOR 🧚

🌸 new

$prometheus = Net::Prometheus->new;

returns a new "Net::Prometheus" instance. brand new, fresh out of the box, main character energy. 💖

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 the 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, bestie. don't disable them unless you know exactly why. 🙈

---

💜 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. you're welcome. 😌

⭐ unregister

$prometheus->unregister( $collector );

removes a previously-registered collector. she's out. goodbye. 💀

🌟 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. it's the group chat of metrics, honestly. takes the following named arguments:

• namespace => STR — string value to pass by default into new metrics the group will construct.
• subsystem => STR — string value 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. so handy. so iconic.

$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. the whole squad reporting in. 🫶

💖 render

$str = $prometheus->render;

returns a string in the Prometheus text exposition format containing the current values of all the registered metrics. the glow-up in text form.

$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". no cap.

💖 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. she's ready for her close-up. ✨

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. (yes, that's a real requirement, don't @ me, it's literally in the docs. 💀)

this new server will listen on its own port number for any incoming request, and will serve metrics regardless of path. she doesn't care where you knock, she's answering.

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. set your expectations accordingly, bestie. 🙈

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. she's in it for the long haul. 🫶

🌈 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. slay.

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. read that again, bestie, it matters. ⚠️

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. literally any object. go feral. 🦋

@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. build your own, icon. ✨

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. sharing is caring. 💖

---

🎀 TODO 🎀

• Histogram/Summary 'start_timer' support
• Add other "export_to_*" methods for other event systems and HTTP-serving frameworks, e.g. Mojo.

(it's on the list. the list is real. manifesting. 🙏)

---

🌟 AUTHOR 🌟

Paul Evans <leonerd@leonerd.org.uk>

---

okay that's the whole page bestie, you're officially certified in Net::Prometheus 💅 periodt. this was documented for perl v5.42.3, dated 2026-08-20, and it's part of the User Contributed Perl Documentation — go forth and export those metrics, queen. 👑✨