1Metrics::Any(3)       User Contributed Perl Documentation      Metrics::Any(3)
2
3
4

NAME

6       "Metrics::Any" - abstract collection of monitoring metrics
7

SYNOPSIS

9       In a module:
10
11          use Metrics::Any '$metrics',
12             strict => 0,
13             name_prefix => [ 'my_module_name' ];
14
15          sub do_thing {
16             $metrics->inc_counter( 'things_done' );
17          }
18
19       In a program or top-level program-like module:
20
21          use Metrics::Any::Adapter 'Prometheus';
22

DESCRIPTION

24       Provides a central location for modules to report monitoring metrics,
25       such as counters of the number of times interesting events have
26       happened, and programs to collect up and send those metrics to
27       monitoring services.
28
29       Inspired by Log::Any, this module splits the overall problem into two
30       sides. Modules wishing to provide metrics for monitoring purposes can
31       use the "use Metrics::Any" statement to obtain a collector into which
32       they can report metric events. By default this collector doesn't
33       actually do anything, so modules can easily use it without adding extra
34       specific dependencies for specific reporting.
35
36       A program using one or more such modules can apply a different policy
37       and request a particular adapter implementation in order to actually
38       report these metrics to some external system, by using the "use
39       Metrics::Any::Adapter" statement.
40
41       This separation of concerns allows module authors to write code which
42       will report metrics without needing to care about the exact mechanism
43       of that reporting (as well as to write code which does not itself
44       depend on the code required to perform that reporting).
45
46   Future Direction
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

USE STATEMENT

57       For a module to use this facility, the "use" statement importing it
58       should give the name of a variable (as a plain string) to store the
59       collector for that package.
60
61          use Metrics::Any '$metrics';
62
63       This variable will be created in the calling package and populated with
64       an instance of Metrics::Any::Collector. The module can then use the
65       collector API to declare new metrics, and eventually report values into
66       them.
67
68       Note that the variable is created at the package level; any other
69       packages within the same file will not see it and will have to declare
70       their own.
71

SEE ALSO

73       •   The name and overall concept of this module is heavily influenced
74           by a similar module for logging, Log::Any.
75
76       •   For reporting metrics to one specific target collector, there are
77           specific modules for systems like statsd (Net::Statsd,
78           Net::Async::Statsd) or prometheus (Prometheus::Tiny,
79           Net::Prometheus).
80
81       •   There is also a similar concept in Measure::Everything.
82

AUTHOR

84       Paul Evans <leonerd@leonerd.org.uk>
85
86
87
88perl v5.36.0                      2023-01-20                   Metrics::Any(3)
Impressum