NAME

Metrics::Any::Collector - module-side of the monitoring metrics reporting API

SYNOPSIS

use Metrics::Any '$metrics';

$metrics->make_counter( thing =>
   name => "things_done",
);

sub do_thing {
   $metrics->inc_counter( 'thing' );
}

DESCRIPTION

Instances of this class provide an API for individual modules to declare metadata about metrics they will report, and to report individual values or observations on those metrics. An instance should be obtained for a reporting module by the use Metrics::Any statement.

The collector acts primarily as a proxy for the application's configured Metrics::Any::Adapter instance. The proxy will lazily create an adapter when required to first actually report a metric value, but until then any metadata stored by any of the make_* methods will not create one. This lazy deferral allows a certain amount of flexibility with module load order and application startup. By carefully writing module code to not report any values of metrics until the main activity has actually begin, it should be possible to allow programs to configure the metric reporting in a flexible manner during program startup.

METRIC TYPES

Counter

The "make_counter" method creates a new metric which counts occurances of some event within the application. Its value begins at zero, and can be incremented by "inc_counter" whenever the event occurs.

Distribution

The "make_distribution" method creates a new metric which counts individual observations of some numerical quantity (which may or may not be integral). New observations can be added by the "inc_distribution_by" method.

Some adapter types may only store an aggregated total; others may store some sort of statistical breakdown, either total + count, or a bucketed histogram. The specific adapter documentation should explain how it handles distributions.

Adapters may make use of the units parameter of the distribution to perform some kind of adapter-specific behaviour. The following units are suggested:

bytes

Observations give sizes in bytes (perhaps memory buffer or network message sizes), and should be integers.

seconds

Observations give durations in seconds.

Gauge

The "make_gauge" method creates a new metric which reports on the instantaneous value of some measurable quantity. Unlike the other metric types this does not have to only increment forwards when certain events occur, but can measure a quantity that may both increase and decrease over time; such as the number some kind of object in memory, or the size of some data structure.

As an alternative to incrementing or decrementing the value when particular events occur, the absolute value of the gauge can also be set directly.

Timer

The "make_timer" method creates a new metric which measures durations of time consumed by the application. New observations of duractions can be added by the "inc_timer" method.

Timer metrics may be handled by the adapter similarly to distribution metrics. Moreover, adapters may choose to implement timers as distributions with units of seconds.

METHODS

make_counter

$collector->make_counter( $handle, %args )

Requests the creation of a new counter metric. The $handle name should be unique within the collector instance, though does not need to be unique across the entire program, as it will be namespaced by the collector instance.

The remaining %args are passed through to the same method on the adapter instance once it is available.

The following named arguments are recognised:

name => STRING

A string name to use for reporting this metric to its upstream service.

description => STRING

Optional human-readable description. May be used for debugging or other purposes.

labels => ARRAY[ STRING ]

Optional reference to an array of string names to use as label names.

A labelled metric will expect to receive as many additional values to its "inc_counter" call as there are label names. Each additional value will be associated with the corresponding label.

Note that not all metric reporting adapters may be able to represent all of the labels. Each should document what its behaviour will be.

inc_counter

$collector->inc_counter( $handle )
$collector->inc_counter( $handle, @labelvalues )

Reports that the counter metric value be incremented by one. The $handle name must match one earlier created by "make_counter".

The remaining @labelvalues if present are passed through to the same method on the adapter instance, and should correspond to the label names given when the counter was created.

$collector->inc_counter_by( $handle, $amount, @labelvalues )

Reports that a counter metric value be incremented by some specified value.

make_distribution

$collector->make_distribution( $handle, %args )

Requests the creation of a new distribution metric. The arguments are interpreted the same as for "make_counter".

The following extra arguments may be passed:

units => STRING: A hint to the adapter about what kind of measurements are being observed, so it might take specific behaviour. If unspecified, a default of bytes will apply.

inc_distribution_by

$collector->inc_distribution_by( $handle, $amount, @labelvalues )

Reports a new observation for the distribution metric. The $handle name must match one earlier created by "make_distribution". The $amount may be interpreted by the adapter depending on the defined units type for the distribution.

The remaining @labelvalues are handled the same as for "inc_counter".

make_gauge

$collector->make_gauge( $handle, %args )

Requests the creation of a new gauge metric. The arguments are interpreted the same as for "make_counter".

inc_gauge

$collector->inc_gauge( $handle, @labelvalues )

dec_gauge

$collector->dec_gauge( $handle, @labelvalues )

inc_gauge_by

$collector->inc_gauge_by( $handle, $amount, @labelvalues )

dec_gauge_by

$collector->dec_gauge_by( $handle, $amount, @labelvalues )

Reports that the observed value of the gauge has increased or decreased by the given amount (or 1).

set_gauge_to

$collector->set_gauge_to( $handle, $amount, @labelvalues )

Reports that the observed value of the gauge is now the given amount.

The $handle name must match one earlier created by "make_gauge".

The remaining @labelvalues are interpreted the same as for "inc_counter".

make_timer

$collector->make_timer( $handle, %args )

Requests the creation of a new timer metric. The arguments are interpreted the same as for "make_counter".

inc_timer_by

$collector->inc_timer_by( $handle, $duration )
$collector->inc_timer_by( $handle, $duration, @labelvalues )

Reports a new duration for the timer metric. The $handle name must match one earlier created by "make_timer". The $duration gives a time measured in seconds, and may be fractional.