.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Metrics::Any 3pm" .TH Metrics::Any 3pm "2022-12-30" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Metrics::Any" \- abstract collection of monitoring metrics .SH "SYNOPSIS" .IX Header "SYNOPSIS" In a module: .PP .Vb 3 \& use Metrics::Any \*(Aq$metrics\*(Aq, \& strict => 0, \& name_prefix => [ \*(Aqmy_module_name\*(Aq ]; \& \& sub do_thing { \& $metrics\->inc_counter( \*(Aqthings_done\*(Aq ); \& } .Ve .PP In a program or top-level program-like module: .PP .Vb 1 \& use Metrics::Any::Adapter \*(AqPrometheus\*(Aq; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Provides a central location for modules to report monitoring metrics, such as counters of the number of times interesting events have happened, and programs to collect up and send those metrics to monitoring services. .PP Inspired by Log::Any, this module splits the overall problem into two sides. Modules wishing to provide metrics for monitoring purposes can use the \&\f(CW\*(C`use Metrics::Any\*(C'\fR statement to obtain a \fIcollector\fR into which they can report metric events. By default this collector doesn't actually do anything, so modules can easily use it without adding extra specific dependencies for specific reporting. .PP A program using one or more such modules can apply a different policy and request a particular \fIadapter\fR implementation in order to actually report these metrics to some external system, by using the \&\f(CW\*(C`use Metrics::Any::Adapter\*(C'\fR statement. .PP This separation of concerns allows module authors to write code which will report metrics without needing to care about the exact mechanism of that reporting (as well as to write code which does not itself depend on the code required to perform that reporting). .SS "Future Direction" .IX Subsection "Future Direction" At present this interface is in an early state of experimentation. The \s-1API\s0 is fairly specifically-shaped for Net::Prometheus at present, but it is hoped with more adapter implementations (such as for statsd or OpenTelemetry) the \s-1API\s0 shapes can be expanded and made more generic to support a wider variety of reporting mechanisms. .PP As a result, any \s-1API\s0 details for now should be considered experimental and subject to change in later versions. .SH "USE STATEMENT" .IX Header "USE STATEMENT" For a module to use this facility, the \f(CW\*(C`use\*(C'\fR statement importing it should give the name of a variable (as a plain string) to store the collector for that package. .PP .Vb 1 \& use Metrics::Any \*(Aq$metrics\*(Aq; .Ve .PP This variable will be created in the calling package and populated with an instance of Metrics::Any::Collector. The module can then use the collector \&\s-1API\s0 to declare new metrics, and eventually report values into them. .PP Note that the variable is created at the package level; any other packages within the same file will not see it and will have to declare their own. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 The name and overall concept of this module is heavily influenced by a similar module for logging, Log::Any. .IP "\(bu" 4 For reporting metrics to one specific target collector, there are specific modules for systems like \fIstatsd\fR (Net::Statsd, Net::Async::Statsd) or \&\fIprometheus\fR (Prometheus::Tiny, Net::Prometheus). .IP "\(bu" 4 There is also a similar concept in Measure::Everything. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans