1Metrics::Any::AdapterBaUssee:r:SCtoonrterdi(b3uptme)d PeMreltrDioccsu:m:eAnntya:t:iAodnapterBase::Stored(3pm)
2
3
4

NAME

6       "Metrics::Any::AdapterBase::Stored" - a base class for metrics adapters
7       which store values
8

DESCRIPTION

10       This base class assists in creating Metrics::Any::Adapter classes which
11       store values of reported metrics directly. These can then be retrieved
12       later by the containing application, or the subclass code, by using the
13       "walk" method.
14
15       This base class internally stores counter and gauge metrics as single
16       scalar values directly. In order to provide flexibility for a variety
17       of use-cases, it requires assistance from the implementing class on how
18       to store distribution and timer metrics. The implementing class should
19       provide these methods, returning whatever values it wishes to implement
20       them with. These values are stored by the base class, and handed back
21       as part of the "walk" method.
22
23       The base class stores a value for each unique set of labels and values
24       on every metric; the subclass does not need to handle this.
25

METHODS

27   walk
28          $stored->walk( $code )
29
30             $code->( $type, $name, $labels, $value )
31
32       Given a CODE reference, this method invokes it once per labelset of
33       every stored metric.
34
35       For each labelset, $type will give the metric type (as a string, either
36       "counter", "distribution", "gauge" or "timer"), $name gives the name it
37       was registered with, $labels will be a reference to an even-sized array
38       containing label names and values.
39
40       For counter and gauge metrics, $value will be a numerical scalar giving
41       the current value. For distribution and timer metrics, $value will be
42       whatever the implementing class's corresponding "store_distribution" or
43       "store_timer" method returns for them.
44
45   clear_values
46          $stored->clear_values
47
48       Clears all of the metric storage. Every labelset of every metric is
49       deleted.  The metric definitions themselves remain.
50

REQUIRED METHODS

52   store_distribution
53   store_timer
54          $storage = $stored->store_distribution( $storage, $amount )
55
56          $storage = $stored->store_timer( $storage, $duration )
57
58       The implementing class must provide these two methods to assist in the
59       management of storage for distribution and timer metrics.
60
61       When a new observation for the metric is required, the method will be
62       invoked, passing in the currently-stored perl value for the given
63       metric and label values, and the new observation. Whatever the method
64       returns is stored by the base class, to be passed in next time or used
65       by the "walk" method.
66
67       The base class stores this value directly and does not otherwise
68       interact with it; letting the implementing class decide what is best.
69       For example, a simple implementation may just store every observation
70       individually by pushing them into an array; so the $storage would be an
71       ARRAY reference:
72
73          sub store_distribution
74          {
75             my $self = shift;
76             my ( $storage, $amount ) = @_;
77
78             push @$storage, $amount;
79
80             return $storage;
81          }
82

AUTHOR

84       Paul Evans <leonerd@leonerd.org.uk>
85
86
87
88perl v5.38.0                      2023-07M-e2t4rics::Any::AdapterBase::Stored(3pm)
Impressum