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>