Net::P...lector(3pm)

💖 Net::Prometheus::PerlCollector 💖

okay bestie, so this is a page from User Contributed Perl Documentation, and it's all about Net::Prometheus::PerlCollector — the little module that puts your Perl interpreter itself on blast 📊✨. It's giving "tell me everything about me" energy, and honestly? Iconic.

---

🌸 NAME 🌸

Net::Prometheus::PerlCollector — obtain statistics about the perl interpreter. That's it, that's the whole job. No cap. 🫶

---

✨ SYNOPSIS ✨

Like, here's the vibe. Look how easy this is:

use Net::Prometheus;
use Net::Prometheus::PerlCollector;

my $client = Net::Prometheus->new;
$client->register( Net::Prometheus::PerlCollector->new );

That's literally it. Register it, you're done, the metrics start flowing 💅

---

🦋 DESCRIPTION 🦋

So this module provides a class that collects metrics about the perl interpreter itself. Not your app, not your database — the interpreter. Main character energy fr fr 👑

🎀 Metrics 🎀

These are the metrics it collects:

• perl_info — an info gauge (i.e. one whose value is always 1) with a version label giving the perl interpreter version ✨

# HELP perl_info Information about the Perl interpreter
# TYPE perl_info gauge
perl_info{version="5.30.0"} 1

Now here's the tea ☕ — if the optional XS module was compiled at build time, you get these extra ones too:

• perl_heap_arenas — a gauge giving the number of arenas the heap is split into 🏟️
• perl_heap_svs — a gauge giving the total number of SVs allocated on the heap 💾

# HELP perl_heap_arenas Number of arenas in the Perl heap
# TYPE perl_heap_arenas gauge
perl_heap_arenas 159
# HELP perl_heap_svs Number of SVs in the Perl heap
# TYPE perl_heap_svs gauge
perl_heap_svs 26732

⚠️ ngl, important caveat: the way these metrics are collected requires counting them all every single time. While this code is relatively efficient, it is still a linear scan, and may itself cause some slowdown of the process at the time it is collected, if the heap has grown very large, containing a great number of SVs. So like… it's fast, but it's not free free, yk? 😭

---

Extra detail can be obtained about the types of heap objects by setting:

$Net::Prometheus::PerlCollector::DETAIL = 1;

This will be slightly more expensive to count, but will yield in addition a detailed breakdown by object type 🔍✨

# HELP perl_heap_svs_by_type Number of SVs classified by type
# TYPE perl_heap_svs_by_type gauge
perl_heap_svs_by_type{type="ARRAY"} 2919
perl_heap_svs_by_type{type="CODE"} 1735
perl_heap_svs_by_type{type="GLOB"} 2647
perl_heap_svs_by_type{type="HASH"} 470
perl_heap_svs_by_type{type="INVLIST"} 68
perl_heap_svs_by_type{type="IO"} 12
perl_heap_svs_by_type{type="NULL"} 8752
perl_heap_svs_by_type{type="REGEXP"} 171
perl_heap_svs_by_type{type="SCALAR"} 9958

Lowkey, this level of detail is unlikely to be useful for most generic production purposes but may be helpful to set in specific processes when investigating specific memory-related issues for a limited time 🕵️♀️

---

For an even greater level of detail, set the value to 2 to additionally obtain another breakdown of blessed objects by class 👑:

# HELP perl_heap_svs_by_class Number of SVs classified by class
# TYPE perl_heap_svs_by_class gauge
...
perl_heap_svs_by_class{class="Net::Prometheus"} 1
perl_heap_svs_by_class{class="Net::Prometheus::PerlCollector"} 1
perl_heap_svs_by_class{class="Net::Prometheus::ProcessCollector::linux"} 1

💀 bestie, heads up: this will yield a large amount of output for any non-trivially sized program, so it should only be enabled under carefully-controlled conditions. Like, do not just leave this on in prod, I'm begging 🙈

---

The value of this variable can be overridden on a per-collection basis by passing the option:

Net::Prometheus->render( { perl_collector_detail => 1 } );  # or 2

This may be more convenient for short-term traces from exporters that parse HTTP query parameters into collector options 🌈:

GET .../metrics?perl_collector_detail=1

See? Chef's kiss 🧑🍳💋

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — we stan, ty for the lore 🫶

---

And that's the whole page, bestie! This was Net::P...lector(3pm), served up from perl v5.42.3, dated 2026-08-20 — slay, periodt, go collect some metrics 💖✨🎀