1Metrics::Any::CollectorU(s3e)r Contributed Perl DocumentaMteitornics::Any::Collector(3)
2
6 "Metrics::Any::Collector" - module-side of the monitoring metrics
7 reporting API
8
10 use Metrics::Any '$metrics',
11 strict => 0,
12 name_prefix => [ 'my_module_name' ];
13 sub do_thing {
15 $metrics->inc_counter( 'things_done' );
16 }
17
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 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
36 METRICS_ANY_DISABLE
37 Since version 0.07.
38 Provides a list of packages and namespaces in which to disable
40 Metrics::Any reporting entirely.
41 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 For example, to disable the metrics that "Net::Async::HTTP::Server"
50 itself creates when exporting Prometheus metrics:
51 $ METRICS_ANY_DISABLE=Net::Async::HTTP::Server ./program.pl
53
55 name_prefix
56 Since version 0.05.
57 Optional prefix to prepend to any name provided to the "make_*"
59 functions.
60 If set, this value and the registered names must be given as array
62 references, not simple strings.
63 use Metrics::Any '$metrics', name_prefix => [qw( my_program_name )];
65 $metrics->make_counter( events =>
67 name => [ "events" ],
68 );
69 # Will create a counter named ["my_program_name", "events"] formed by the
71 # adapter.
72 strict
74 Since version 0.05.
75 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 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 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 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 use Metrics::Any::Adapter '$metrics', strict => 1;
102 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
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 if( $metrics ) {
114 $metrics->inc_counter( name => some_expensive_function() );
115 }
116 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
123 $package = $metrics->package
124 Returns the package name that created the collector; the package in
126 which the
127 use Metrics::Any '$metrics';
129 statement was invoked.
131
133 Each type of metric is created by one of the "make_*" methods. They all
134 take the following common arguments:
135 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 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 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 description => STRING
152 Optional human-readable description. May be used for debugging or
153 other purposes.
154 labels => ARRAY[ STRING ]
156 Optional reference to an array of string names to use as label
157 names.
158 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 $metrics->inc_counter( handle => [ labelname => $labelvalue ] );
165 $metrics->inc_counter( handle => { labelname => $labelvalue } );
166 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 $metrics->inc_counter( handle => $labelvalue );
172 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 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 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 bytes
188 Observations give sizes in bytes (perhaps memory buffer or network
190 message sizes), and should be integers.
191 make_counter
193 $collector->make_counter( $handle, %args )
194 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 The following extra arguments may be passed:
201 units => STRING
203 A hint to the adapter about what kind of measurements are being
204 observed, so it might take specific behaviour.
205 inc_counter
207 $collector->inc_counter( $handle, $labels )
208 Reports that the counter metric value be incremented by one. The
210 $handle name must match one earlier created by "make_counter".
211 inc_counter_by
213 $collector->inc_counter_by( $handle, $amount, $labels )
214 Reports that a counter metric value be incremented by some specified
216 value.
217 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 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 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 bytes
234 Observations give sizes in bytes (perhaps memory buffer or network
236 message sizes), and should be integers.
237 seconds
239 Observations give durations in seconds.
241 make_distribution
243 $collector->make_distribution( $handle, %args )
244 Requests the creation of a new distribution metric.
246 The following extra arguments may be passed:
248 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 report_distribution
255 $collector->report_distribution( $handle, $amount, $labels )
256 Since version 0.05.
258 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 This method used to be called "inc_distribution_by" and is currently
265 still available as an alias.
266 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 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 make_gauge
280 $collector->make_gauge( $handle, %args )
281 Requests the creation of a new gauge metric.
283 inc_gauge
285 $collector->inc_gauge( $handle, $labels )
286 dec_gauge
288 $collector->dec_gauge( $handle, $labels )
289 inc_gauge_by
291 $collector->inc_gauge_by( $handle, $amount, $labels )
292 dec_gauge_by
294 $collector->dec_gauge_by( $handle, $amount, $labels )
295 Reports that the observed value of the gauge has increased or decreased
297 by the given amount (or 1).
298 set_gauge_to
300 $collector->set_gauge_to( $handle, $amount, $labels )
301 Reports that the observed value of the gauge is now the given amount.
303 The $handle name must match one earlier created by "make_gauge".
305 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 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 make_timer
316 $collector->make_timer( $handle, %args )
317 Requests the creation of a new timer metric.
319 report_timer
321 $collector->report_timer( $handle, $duration, $labels )
322 Since version 0.05.
324 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 This method used to called "inc_timer_by" and is currently still
330 available as an alias.
331
333 Paul Evans <leonerd@leonerd.org.uk>
334perl v5.34.0 2022-01-21 Metrics::Any::Collector(3)