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

💅 Net::Prometheus::Gauge 💅

okay bestie, gather round, because this module (from the User Contributed Perl Documentation, no less) is literally the glow-up your metrics needed 🫶

Net::Prometheus::Gauge — a snapshot value-reporting metric ✨

---

✨ NAME ✨

"Net::Prometheus::Gauge" — a snapshot value-reporting metric 🌸

---

🎀 SYNOPSIS 🎀

use Net::Prometheus;

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

my $gauge = $client->new_gauge(
   name => "users",
   help => "Number of current users",
);

my %users;
...

$gauge->set( scalar keys %users );

like… that's it. that's the whole vibe. 💖

---

🦋 DESCRIPTION 🦋

So this class hands you a gauge metric, which is just an arbitrary value that's observing some snapshot of state at some single instant in time. Think of it like a selfie for your program's internals 📸 — it captures right now, not a running total.

It's usually used to report on how much of a resource the instrumented program is currently using, and here's the iconic part: it can go down as well as up. not like a counter, which only knows how to climb. a gauge is flexible, fluid, main character energy 👑

Also, important lore: it's a subclass of Net::Prometheus::Metric. 💜

✨ Value-Reporting Functions ✨

Okay so instead of using the set method to update the gauge's value, you could use a callback function instead — and that callback should return the current value to report for that gauge. The slay part? This function gets invoked at collection time, which means the value you report is always up-to-date. no stale data here, bestie 💅

heads up though: these functions get invoked inline as part of the collection process, so keep them as small and lightweight as possible. like, tiny. microscopic. don't be out here doing a whole database migration inside a callback.

Typical applications involve reporting the size of an array or hash somewhere inside the implementation's code:

$gauge->set_function( sub { scalar @items } );

$gauge->set_function( sub { scalar keys %things } );

---

🌈 CONSTRUCTOR 🌈

ngl, you don't usually construct these bad boys directly. instead you go through the Net::Prometheus object that's gonna serve it:

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

It takes the exact same constructor arguments as documented over in Net::Prometheus::Metric — so go check that page, iykyk 📚

---

💖 METHODS 💖

🔥 set

$gauge->set( @label_values, $value );
$gauge->set( \%labels, $value );

$child->set( $value );

Sets the current value for the gauge. periodt. ✨

And if your gauge has any labels defined, then the values for those labels have to be given first. order matters, bestie 🫶

🍓 set_function

$gauge->set_function( @label_values, $func );
$gauge->set_function( \%labels, $func );

$child->set_function( $func );

Sets a value-returning callback function for the gauge. And if the gauge is labeled, then each label combination needs its own function — yeah, every single one. no sharing 😭

When the function gets invoked it'll be passed no arguments, and it's expected to return a single value:

$value = $func->();

⭐ inc

$gauge->inc( @label_values, $delta );
$gauge->inc( \%labels, $delta );

$child->inc( $delta );

Increments the current value for the gauge 📈 and $delta defaults to 1 if you don't supply one. so if you're feeling lazy, it just goes up by one. adorable.

🌸 dec

$gauge->dec( @label_values, $delta );
$gauge->dec( \%labels, $delta );

$child->dec( $delta );

Decrements the current value for the gauge 📉 and yep, $delta also defaults to 1 if you don't supply one. so it just drops by one. bye girl 👋

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — absolute legend, we stan 🫶

---

okay and for the cute sign-off moment: this whole page is Net::P...:Gauge(3pm) from perl v5.42.3, dated 2026-08-20, living under User Contributed Perl Documentation. so go forth and gauge your little heart out 💖✨🎀