oracular (3) Metrics::Any::AdapterBase::Stored.3pm.gz

NAME

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

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 "walk" method.

       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 "walk" method.

       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.

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.

       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.

       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.

   clear_values
          $stored->clear_values

       Clears all of the metric storage. Every labelset of every metric is deleted.  The metric definitions
       themselves remain.

REQUIRED METHODS

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

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

       The implementing class must provide these two methods to assist in the management of storage for
       distribution and timer metrics.

       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 "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;
          }

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>