| 1 |
NAME |
| 2 |
|
| 3 |
Metrics::Any - abstract collection of monitoring metrics |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
|
| 7 |
In a module: |
| 8 |
|
| 9 |
use Metrics::Any '$metrics', |
| 10 |
strict => 0, |
| 11 |
name_prefix => [ 'my_module_name' ]; |
| 12 |
|
| 13 |
sub do_thing { |
| 14 |
$metrics->inc_counter( 'things_done' ); |
| 15 |
} |
| 16 |
|
| 17 |
In a program or top-level program-like module: |
| 18 |
|
| 19 |
use Metrics::Any::Adapter 'Prometheus'; |
| 20 |
|
| 21 |
DESCRIPTION |
| 22 |
|
| 23 |
Provides a central location for modules to report monitoring metrics, |
| 24 |
such as counters of the number of times interesting events have |
| 25 |
happened, and programs to collect up and send those metrics to |
| 26 |
monitoring services. |
| 27 |
|
| 28 |
Inspired by Log::Any, this module splits the overall problem into two |
| 29 |
sides. Modules wishing to provide metrics for monitoring purposes can |
| 30 |
use the use Metrics::Any statement to obtain a collector into which |
| 31 |
they can report metric events. By default this collector doesn't |
| 32 |
actually do anything, so modules can easily use it without adding extra |
| 33 |
specific dependencies for specific reporting. |
| 34 |
|
| 35 |
A program using one or more such modules can apply a different policy |
| 36 |
and request a particular adapter implementation in order to actually |
| 37 |
report these metrics to some external system, by using the use |
| 38 |
Metrics::Any::Adapter statement. |
| 39 |
|
| 40 |
This separation of concerns allows module authors to write code which |
| 41 |
will report metrics without needing to care about the exact mechanism |
| 42 |
of that reporting (as well as to write code which does not itself |
| 43 |
depend on the code required to perform that reporting). |
| 44 |
|
| 45 |
Future Direction |
| 46 |
|
| 47 |
At present this interface is in an early state of experimentation. The |
| 48 |
API is fairly specifically-shaped for Net::Prometheus at present, but |
| 49 |
it is hoped with more adapter implementations (such as for statsd or |
| 50 |
OpenTelemetry) the API shapes can be expanded and made more generic to |
| 51 |
support a wider variety of reporting mechanisms. |
| 52 |
|
| 53 |
As a result, any API details for now should be considered experimental |
| 54 |
and subject to change in later versions. |
| 55 |
|
| 56 |
USE STATEMENT |
| 57 |
|
| 58 |
For a module to use this facility, the use statement importing it |
| 59 |
should give the name of a variable (as a plain string) to store the |
| 60 |
collector for that package. |
| 61 |
|
| 62 |
use Metrics::Any '$metrics'; |
| 63 |
|
| 64 |
This variable will be created in the calling package and populated with |
| 65 |
an instance of Metrics::Any::Collector. The module can then use the |
| 66 |
collector API to declare new metrics, and eventually report values into |
| 67 |
them. |
| 68 |
|
| 69 |
Note that the variable is created at the package level; any other |
| 70 |
packages within the same file will not see it and will have to declare |
| 71 |
their own. |
| 72 |
|
| 73 |
SEE ALSO |
| 74 |
|
| 75 |
* The name and overall concept of this module is heavily influenced |
| 76 |
by a similar module for logging, Log::Any. |
| 77 |
|
| 78 |
* For reporting metrics to one specific target collector, there are |
| 79 |
specific modules for systems like statsd (Net::Statsd, |
| 80 |
Net::Async::Statsd) or prometheus (Prometheus::Tiny, |
| 81 |
Net::Prometheus). |
| 82 |
|
| 83 |
* There is also a similar concept in Measure::Everything. |
| 84 |
|
| 85 |
AUTHOR |
| 86 |
|
| 87 |
Paul Evans <[email protected]> |
| 88 |
|