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 the "make_counter" method 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.

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, @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.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>