Metric...:Stored(3pm)

🌸 "Metrics::Any::AdapterBase::Stored" — the Perl manpage, but make it cute 🌸

okay bestie, you found the manual page for Metrics::Any::AdapterBase::Stored (3pm), from the User Contributed Perl Documentation, and honestly? it's giving base class energy in the best way. let's get into it 💅

---

✨ NAME ✨

"Metrics::Any::AdapterBase::Stored" — a base class for metrics adapters which store values. that's it, that's the whole name, she's straightforward and we respect her 🫶

---

🦋 DESCRIPTION 🦋

so this base class? she's the little helper that assists you in creating Metrics::Any::Adapter classes which store values of reported metrics directly. like, right there. no detours, no drama 💖

and then those stored values can be retrieved later — either by the containing application, or by the subclass code itself — by using the "walk" method. iconic.

here's the tea tho: this base class internally stores counter and gauge metrics as single scalar values directly. simple, clean, slay. but because she wants to provide flexibility for a whole variety of use-cases, she requires assistance from the implementing class on how to store distribution and timer metrics. so the implementing class should provide these methods, returning whatever values it wishes to implement them with. those values get stored by the base class, and handed back as part of the "walk" method. teamwork, fr fr 🤝

and the base class stores a value for each unique set of labels and values on every metric — the subclass does not need to handle this. thank u base class, doing the absolute most so ur subclass doesn't have to 👑

---

🎀 METHODS 🎀

💫 walk

$stored->walk( $code )

   $code->( $type, $name, $labels, $value )

given a CODE reference, this method invokes it once per labelset of every stored metric. no labelset left behind, periodt.

for each labelset:

• $type will give the metric type (as a string, either "counter", "distribution", "gauge" or "timer")
• $name gives the name it was registered with
• $labels will be a reference to an even-sized array containing label names and values

and for the value:

• for counter and gauge metrics, $value will be a numerical scalar giving the current value
• for distribution and timer metrics, $value will be whatever the implementing class's corresponding "store_distribution" or "store_timer" method returns for them

it's giving ✨ delegation ✨ and honestly? correct.

🧹 clear_values

$stored->clear_values

clears all of the metric storage. every labelset of every metric is deleted. poof. gone. but here's the important bit bestie — the metric definitions themselves remain 🌈

---

🔥 REQUIRED METHODS 🔥

🍓 store_distribution and store_timer

$storage = $stored->store_distribution( $storage, $amount )

$storage = $stored->store_timer( $storage, $duration )

⚠️ the implementing class must provide these two methods — this is not optional, bestie. they assist in the management of storage for distribution and timer metrics.

so when a new observation for the metric is required, the method will be invoked, passing in:

1. the currently-stored perl value for the given metric and label values
2. the new observation

and whatever the method returns is stored by the base class — to be passed in next time, or used by the "walk" method. the base class stores this value directly and does not otherwise interact with it, letting the implementing class decide what is best 💜

for example, a simple implementation may just store every observation individually by pushing them into an array — so the $storage would be an ARRAY reference:

sub store_distribution
{
   my $self = shift;
   my ( $storage, $amount ) = @_;

   push @$storage, $amount;

   return $storage;
}

look at that. clean, simple, no notes. ate and left no crumbs 🎀

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — we stan a legend 💖

---

okay that's the whole page bestie, go forth and store those metrics responsibly 💅✨

this was perl v5.36.0 from 2023-09-29 and yeah, the footer said Metric...:Stored(3pm) so like, that's the vibe 🦋 bye ily