.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Metrics::Any::AdapterBase::Stored 3pm"
.TH Metrics::Any::AdapterBase::Stored 3pm "2022-12-30" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"Metrics::Any::AdapterBase::Stored" \- a base class for metrics adapters which store values
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This base class assists in creating Metrics::Any::Adapter classes which
store values of reported metrics directly. These can then be retrieved later
by the containing application, or the subclass code, by using the \*(L"walk\*(R"
method.
.PP
This base class internally stores counter and gauge metrics as single scalar
values directly. In order to provide flexibility for a variety of
use-cases, it requires assistance from the implementing class on how to store
distribution and timer metrics. The implementing class should provide these
methods, returning whatever values it wishes to implement them with. These
values are stored by the base class, and handed back as part of the \*(L"walk\*(R"
method.
.PP
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.
.SH "METHODS"
.IX Header "METHODS"
.SS "walk"
.IX Subsection "walk"
.Vb 1
\&   $stored\->walk( $code )
\&
\&      $code\->( $type, $name, $labels, $value )
.Ve
.PP
Given a \s-1CODE\s0 reference, this method invokes it once per labelset of every
stored metric.
.PP
For each labelset, \f(CW$type\fR will give the metric type (as a string, either
\&\f(CW\*(C`counter\*(C'\fR, \f(CW\*(C`distribution\*(C'\fR, \f(CW\*(C`gauge\*(C'\fR or \f(CW\*(C`timer\*(C'\fR), \f(CW$name\fR gives the name
it was registered with, \f(CW$labels\fR will be a reference to an even-sized array
containing label names and values.
.PP
For counter and gauge metrics, \f(CW$value\fR will be a numerical scalar giving the
current value. For distribution and timer metrics, \f(CW$value\fR will be whatever
the implementing class's corresponding \f(CW\*(C`store_distribution\*(C'\fR or \f(CW\*(C`store_timer\*(C'\fR
method returns for them.
.SS "clear_values"
.IX Subsection "clear_values"
.Vb 1
\&   $stored\->clear_values
.Ve
.PP
Clears all of the metric storage. Every labelset of every metric is deleted.
The metric definitions themselves remain.
.SH "REQUIRED METHODS"
.IX Header "REQUIRED METHODS"
.SS "store_distribution"
.IX Subsection "store_distribution"
.SS "store_timer"
.IX Subsection "store_timer"
.Vb 1
\&   $storage = $stored\->store_distribution( $storage, $amount )
\&
\&   $storage = $stored\->store_timer( $storage, $duration )
.Ve
.PP
The implementing class must provide these two methods to assist in the
management of storage for distribution and timer metrics.
.PP
When a new observation for the metric is required, the method will be invoked,
passing in the currently-stored perl value for the given metric and label
values, and the new observation. Whatever the method returns is stored by the
base class, to be passed in next time or used by the \*(L"walk\*(R" method.
.PP
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 \f(CW$storage\fR would be an \s-1ARRAY\s0 reference:
.PP
.Vb 4
\&   sub store_distribution
\&   {
\&      my $self = shift;
\&      my ( $storage, $amount ) = @_;
\&
\&      push @$storage, $amount;
\&
\&      return $storage;
\&   }
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>