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 name_prefix
37 Since version 0.05.
38 Optional prefix to prepend to any name provided to the "make_*"
40 functions.
41 If set, this value and the registered names must be given as array
43 references, not simple strings.
44 use Metrics::Any '$metrics', name_prefix => [qw( my_program_name )];
46 $metrics->make_counter( events =>
48 name => [ "events" ],
49 );
50 # Will create a counter named ["my_program_name", "events"] formed by the
52 # adapter.
53 strict
55 Since version 0.05.
56 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 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 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 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 use Metrics::Any::Adapter '$metrics', strict => 1;
83 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
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 if( $metrics ) {
95 $metrics->inc_counter( name => some_expensive_function() );
96 }
97 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
104 $package = $metrics->package
105 Returns the package name that created the collector; the package in
107 which the
108 use Metrics::Any '$metrics';
110 statement was invoked.
112
114 Each type of metric is created by one of the "make_*" methods. They all
115 take the following common arguments:
116 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 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 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 description => STRING
133 Optional human-readable description. May be used for debugging or
134 other purposes.
135 labels => ARRAY[ STRING ]
137 Optional reference to an array of string names to use as label
138 names.
139 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 $metrics->inc_counter( handle => [ labelname => $labelvalue ] );
146 $metrics->inc_counter( handle => { labelname => $labelvalue } );
147 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 $metrics->inc_counter( handle => $labelvalue );
153 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 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 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 bytes
169 Observations give sizes in bytes (perhaps memory buffer or network
171 message sizes), and should be integers.
172 make_counter
174 $collector->make_counter( $handle, %args )
175 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 The following extra arguments may be passed:
182 units => STRING
184 A hint to the adapter about what kind of measurements are being
185 observed, so it might take specific behaviour.
186 inc_counter
188 $collector->inc_counter( $handle, $labels )
189 Reports that the counter metric value be incremented by one. The
191 $handle name must match one earlier created by "make_counter".
192 inc_counter_by
194 $collector->inc_counter_by( $handle, $amount, $labels )
195 Reports that a counter metric value be incremented by some specified
197 value.
198 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 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 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 bytes
215 Observations give sizes in bytes (perhaps memory buffer or network
217 message sizes), and should be integers.
218 seconds
220 Observations give durations in seconds.
222 make_distribution
224 $collector->make_distribution( $handle, %args )
225 Requests the creation of a new distribution metric.
227 The following extra arguments may be passed:
229 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 report_distribution
236 $collector->report_distribution( $handle, $amount, $labels )
237 Since version 0.05.
239 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 This method used to be called "inc_distribution_by" and is currently
246 still available as an alias.
247 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 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 make_gauge
261 $collector->make_gauge( $handle, %args )
262 Requests the creation of a new gauge metric.
264 inc_gauge
266 $collector->inc_gauge( $handle, $labels )
267 dec_gauge
269 $collector->dec_gauge( $handle, $labels )
270 inc_gauge_by
272 $collector->inc_gauge_by( $handle, $amount, $labels )
273 dec_gauge_by
275 $collector->dec_gauge_by( $handle, $amount, $labels )
276 Reports that the observed value of the gauge has increased or decreased
278 by the given amount (or 1).
279 set_gauge_to
281 $collector->set_gauge_to( $handle, $amount, $labels )
282 Reports that the observed value of the gauge is now the given amount.
284 The $handle name must match one earlier created by "make_gauge".
286 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 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 make_timer
297 $collector->make_timer( $handle, %args )
298 Requests the creation of a new timer metric.
300 report_timer
302 $collector->report_timer( $handle, $duration, $labels )
303 Since version 0.05.
305 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 This method used to called "inc_timer_by" and is currently still
311 available as an alias.
312
314 Paul Evans <leonerd@leonerd.org.uk>
315perl v5.32.1 2021-01-27 Metrics::Any::Collector(3)