1Metrics::Any::CollectorU(s3e)r Contributed Perl DocumentaMteitornics::Any::Collector(3)
2
3
4

NAME

6       "Metrics::Any::Collector" - module-side of the monitoring metrics
7       reporting API
8

SYNOPSIS

10          use Metrics::Any '$metrics',
11             strict => 0,
12             name_prefix => [ 'my_module_name' ];
13
14          sub do_thing {
15             $metrics->inc_counter( 'things_done' );
16          }
17

DESCRIPTION

19       Instances of this class provide an API for individual modules to
20       declare metadata about metrics they will report, and to report
21       individual values or observations on those metrics. An instance should
22       be obtained for a reporting module by the "use Metrics::Any" statement.
23
24       The collector acts primarily as a proxy for the application's
25       configured Metrics::Any::Adapter instance. The proxy will lazily create
26       an adapter when required to first actually report a metric value, but
27       until then any metadata stored by any of the "make_*" methods will not
28       create one. This lazy deferral allows a certain amount of flexibility
29       with module load order and application startup. By carefully writing
30       module code to not report any values of metrics until the main activity
31       has actually begin, it should be possible to allow programs to
32       configure the metric reporting in a flexible manner during program
33       startup.
34

ENVIRONMENT

36   METRICS_ANY_DISABLE
37       Since version 0.07.
38
39       Provides a list of packages and namespaces in which to disable
40       Metrics::Any reporting entirely.
41
42       This variable gives a comma-separated list of name patterns. Patterns
43       may end with "::*", where they will match any package whose name starts
44       with that prefix, or they may be literal package names. If any code in
45       matching packages attempts to use Metrics::Any::Collector to report
46       metrics, that code will be given a "Null" adapter, and no metrics will
47       be reported from here.
48
49       For example, to disable the metrics that "Net::Async::HTTP::Server"
50       itself creates when exporting Prometheus metrics:
51
52          $ METRICS_ANY_DISABLE=Net::Async::HTTP::Server ./program.pl
53

ARGUMENTS

55   name_prefix
56       Since version 0.05.
57
58       Optional prefix to prepend to any name provided to the "make_*"
59       functions.
60
61       If set, this value and the registered names must be given as array
62       references, not simple strings.
63
64          use Metrics::Any '$metrics', name_prefix => [qw( my_program_name )];
65
66          $metrics->make_counter( events =>
67             name => [ "events" ],
68          );
69
70          # Will create a counter named ["my_program_name", "events"] formed by the
71          # adapter.
72
73   strict
74       Since version 0.05.
75
76       Optional boolean which controls whether metrics must be registered by a
77       "make_" method before they can be used (when true), or whether to
78       attempt lazily registering them when first encountered by a reporting
79       method (when false).
80
81       When strict mode is off and a reporting method (e.g. "inc_counter") is
82       invoked on an unrecognised handle, it will be lazily registered. If the
83       metric is reported with values, an attempt is made to determine what
84       the list of label names is; which will depend on the form the label
85       values are given in.  Labels passed by array reference, or by hash
86       reference for a single label will work fine. If a hash reference is
87       passed with multiple keys, a warning is printed that the order may not
88       be reliable. Finally, for (discouraged) flat lists of values directly
89       it is not possible to recover label name information so an exception is
90       thrown.
91
92       For this reason, when operating with strict mode off, it is recommended
93       always to use the array reference form of supplying labels, to ensure
94       they are registered correctly.
95
96       In the current version this parameter defaults true, and thus all
97       metrics must be registered in advance. This may be changed in a future
98       version for convenience in smaller modules, so paranoid authors should
99       set it explicitly:
100
101          use Metrics::Any::Adapter '$metrics', strict => 1;
102
103       If strict mode is switched off, it is recommended to set a name prefix
104       to ensure that lazily-registered metrics will at least have a useful
105       name.
106

BOOLEAN OVERRIDE

108       Instances of this class override boolean truth testing. They are
109       usually true, except in the case that an adapter has already been
110       created and it is the Null type. This allows modules to efficiently
111       test whether to report metrics at all by using code such as
112
113          if( $metrics ) {
114             $metrics->inc_counter( name => some_expensive_function() );
115          }
116
117       While the Null adapter will simply ignore any of the methods invoked on
118       it, without this conditional test the caller would otherwise still have
119       to calculate the value that won't be used. This structure allows the
120       calculation to be avoided if metrics are not in use.
121

METHODS

123          $package = $metrics->package
124
125       Returns the package name that created the collector; the package in
126       which the
127
128          use Metrics::Any '$metrics';
129
130       statement was invoked.
131

METRIC TYPES

133       Each type of metric is created by one of the "make_*" methods. They all
134       take the following common arguments:
135
136       name => ARRAY[ STRING ] | STRING
137           Optional. An array of string parts, or a plain string name to use
138           for reporting this metric to its upstream service.
139
140           Modules should preferrably use an array of string parts to specify
141           their metric names, as different adapter types may have different
142           ways to represent this hierarchially. Base-level parts of the name
143           should come first, followed by more specific parts. It is common
144           for related metrics to be grouped by name having identical prefixes
145           but differing only in the final part.
146
147           The name is optional; if unspecified then the handle will be used
148           to form the name, combined with a "name_prefix" argument if one was
149           set for the package.
150
151       description => STRING
152           Optional human-readable description. May be used for debugging or
153           other purposes.
154
155       labels => ARRAY[ STRING ]
156           Optional reference to an array of string names to use as label
157           names.
158
159           A labelled metric will expect to receive additional information in
160           its reporting method to give values for these labels. This
161           information should be in either an even-length array reference of
162           name/value pairs, or a hash reference. E.g.
163
164              $metrics->inc_counter( handle => [ labelname => $labelvalue ] );
165              $metrics->inc_counter( handle => { labelname => $labelvalue } );
166
167           A legacy form where a plain list of values is passed, each
168           corresponding to a named label in the same order, is currently
169           accepted but discouraged in favour of the above forms.
170
171              $metrics->inc_counter( handle => $labelvalue );
172
173           Note that not all metric reporting adapters may be able to
174           represent all of the labels. Each should document what its
175           behaviour will be.
176
177   Counter
178       The "make_counter" method creates a new metric which counts occurances
179       of some event within the application. Its value begins at zero, and can
180       be incremented by "inc_counter" whenever the event occurs.
181
182       Some counters may simple count occurances of events, while others may
183       count in other units, for example counts of bytes. Adapters may make
184       use of the "units" parameter of the distribution to perform some kind
185       of adapter-specific behaviour. The following units are suggested:
186
187       bytes
188
189       Observations give sizes in bytes (perhaps memory buffer or network
190       message sizes), and should be integers.
191
192   make_counter
193          $collector->make_counter( $handle, %args )
194
195       Requests the creation of a new counter metric. The $handle name should
196       be unique within the collector instance, though does not need to be
197       unique across the entire program, as it will be namespaced by the
198       collector instance.
199
200       The following extra arguments may be passed:
201
202       units => STRING
203           A hint to the adapter about what kind of measurements are being
204           observed, so it might take specific behaviour.
205
206   inc_counter
207          $collector->inc_counter( $handle, $labels )
208
209       Reports that the counter metric value be incremented by one. The
210       $handle name must match one earlier created by "make_counter".
211
212   inc_counter_by
213          $collector->inc_counter_by( $handle, $amount, $labels )
214
215       Reports that a counter metric value be incremented by some specified
216       value.
217
218   Distribution
219       The "make_distribution" method creates a new metric which counts
220       individual observations of some numerical quantity (which may or may
221       not be integral).  New observations can be added by the
222       "report_distribution" method.
223
224       Some adapter types may only store an aggregated total; others may store
225       some sort of statistical breakdown, either total + count, or a bucketed
226       histogram.  The specific adapter documentation should explain how it
227       handles distributions.
228
229       Adapters may make use of the "units" parameter of the distribution to
230       perform some kind of adapter-specific behaviour. The following units
231       are suggested:
232
233       bytes
234
235       Observations give sizes in bytes (perhaps memory buffer or network
236       message sizes), and should be integers.
237
238       seconds
239
240       Observations give durations in seconds.
241
242   make_distribution
243          $collector->make_distribution( $handle, %args )
244
245       Requests the creation of a new distribution metric.
246
247       The following extra arguments may be passed:
248
249       units => STRING
250           A hint to the adapter about what kind of measurements are being
251           observed, so it might take specific behaviour. If unspecified, a
252           default of "bytes" will apply.
253
254   report_distribution
255          $collector->report_distribution( $handle, $amount, $labels )
256
257       Since version 0.05.
258
259       Reports a new observation for the distribution metric. The $handle name
260       must match one earlier created by "make_distribution". The $amount may
261       be interpreted by the adapter depending on the defined "units" type for
262       the distribution.
263
264       This method used to be called "inc_distribution_by" and is currently
265       still available as an alias.
266
267   Gauge
268       The "make_gauge" method creates a new metric which reports on the
269       instantaneous value of some measurable quantity. Unlike the other
270       metric types this does not have to only increment forwards when certain
271       events occur, but can measure a quantity that may both increase and
272       decrease over time; such as the number some kind of object in memory,
273       or the size of some data structure.
274
275       As an alternative to incrementing or decrementing the value when
276       particular events occur, the absolute value of the gauge can also be
277       set directly.
278
279   make_gauge
280          $collector->make_gauge( $handle, %args )
281
282       Requests the creation of a new gauge metric.
283
284   inc_gauge
285          $collector->inc_gauge( $handle, $labels )
286
287   dec_gauge
288          $collector->dec_gauge( $handle, $labels )
289
290   inc_gauge_by
291          $collector->inc_gauge_by( $handle, $amount, $labels )
292
293   dec_gauge_by
294          $collector->dec_gauge_by( $handle, $amount, $labels )
295
296       Reports that the observed value of the gauge has increased or decreased
297       by the given amount (or 1).
298
299   set_gauge_to
300          $collector->set_gauge_to( $handle, $amount, $labels )
301
302       Reports that the observed value of the gauge is now the given amount.
303
304       The $handle name must match one earlier created by "make_gauge".
305
306   Timer
307       The "make_timer" method creates a new metric which measures durations
308       of time consumed by the application. New observations of durations can
309       be added by the "report_timer" method.
310
311       Timer metrics may be handled by the adapter similarly to distribution
312       metrics.  Moreover, adapters may choose to implement timers as
313       distributions with units of "seconds".
314
315   make_timer
316          $collector->make_timer( $handle, %args )
317
318       Requests the creation of a new timer metric.
319
320   report_timer
321          $collector->report_timer( $handle, $duration, $labels )
322
323       Since version 0.05.
324
325       Reports a new duration for the timer metric. The $handle name must
326       match one earlier created by "make_timer". The $duration gives a time
327       measured in seconds, and may be fractional.
328
329       This method used to called "inc_timer_by" and is currently still
330       available as an alias.
331

AUTHOR

333       Paul Evans <leonerd@leonerd.org.uk>
334
335
336
337perl v5.34.0                      2021-07-25        Metrics::Any::Collector(3)
Impressum