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

ARGUMENTS

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

BOOLEAN OVERRIDE

89       Instances of this class override boolean truth testing. They are
90       usually true, except in the case that an adapter has already been
91       created and it is the Null type. This allows modules to efficiently
92       test whether to report metrics at all by using code such as
93
94          if( $metrics ) {
95             $metrics->inc_counter( name => some_expensive_function() );
96          }
97
98       While the Null adapter will simply ignore any of the methods invoked on
99       it, without this conditional test the caller would otherwise still have
100       to calculate the value that won't be used. This structure allows the
101       calculation to be avoided if metrics are not in use.
102

METHODS

104          $package = $metrics->package
105
106       Returns the package name that created the collector; the package in
107       which the
108
109          use Metrics::Any '$metrics';
110
111       statement was invoked.
112

METRIC TYPES

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

AUTHOR

314       Paul Evans <leonerd@leonerd.org.uk>
315
316
317
318perl v5.32.1                      2021-01-27        Metrics::Any::Collector(3)
Impressum