Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Metrics::Any::CollectoUser Contributed Perl DocumentMetrics::Any::Collector(3)

NAME
       "Metrics::Any::Collector" - module-side of the monitoring metrics
       reporting API

SYNOPSIS
	  use Metrics::Any '$metrics',
	     strict => 0,
	     name_prefix => [ 'my_module_name' ];

	  sub do_thing {
	     $metrics->inc_counter( 'things_done' );
	  }

DESCRIPTION
       Instances of this class provide an API for individual modules to
       declare metadata	about metrics they will	report,	and to report
       individual values or observations on those metrics. An instance should
       be obtained for a reporting module by the "use Metrics::Any" statement.

       The collector acts primarily as a proxy for the application's
       configured Metrics::Any::Adapter	instance. The proxy will lazily	create
       an adapter when required	to first actually report a metric value, but
       until then any metadata stored by any of	the "make_*" methods will not
       create one. This	lazy deferral allows a certain amount of flexibility
       with module load	order and application startup. By carefully writing
       module code to not report any values of metrics until the main activity
       has actually begin, it should be	possible to allow programs to
       configure the metric reporting in a flexible manner during program
       startup.

ARGUMENTS
   name_prefix
       Since version 0.05.

       Optional	prefix to prepend to any name provided to the "make_*"
       functions.

       If set, this value and the registered names must	be given as array
       references, not simple strings.

	  use Metrics::Any '$metrics', name_prefix => [qw( my_program_name )];

	  $metrics->make_counter( events =>
	     name => [ "events"	],
	  );

	  # Will create	a counter named	["my_program_name", "events"] formed by	the
	  # adapter.

   strict
       Since version 0.05.

       Optional	boolean	which controls whether metrics must be registered by a
       "make_" method before they can be used (when true), or whether to
       attempt lazily registering them when first encountered by a reporting
       method (when false).

       When strict mode	is off and a reporting method (e.g. "inc_counter") is
       invoked on an unrecognised handle, it will be lazily registered.	If the
       metric is reported with values, an attempt is made to determine what
       the list	of label names is; which will depend on	the form the label
       values are given	in.  Labels passed by array reference, or by hash
       reference for a single label will work fine. If a hash reference	is
       passed with multiple keys, a warning is printed that the	order may not
       be reliable. Finally, for (discouraged) flat lists of values directly
       it is not possible to recover label name	information so an exception is
       thrown.

       For this	reason,	when operating with strict mode	off, it	is recommended
       always to use the array reference form of supplying labels, to ensure
       they are	registered correctly.

       In the current version this parameter defaults true, and	thus all
       metrics must be registered in advance. This may be changed in a future
       version for convenience in smaller modules, so paranoid authors should
       set it explicitly:

	  use Metrics::Any::Adapter '$metrics',	strict => 1;

       If strict mode is switched off, it is recommended to set	a name prefix
       to ensure that lazily-registered	metrics	will at	least have a useful
       name.

BOOLEAN	OVERRIDE
       Instances of this class override	boolean	truth testing. They are
       usually true, except in the case	that an	adapter	has already been
       created and it is the Null type.	This allows modules to efficiently
       test whether to report metrics at all by	using code such	as

	  if( $metrics ) {
	     $metrics->inc_counter( name => some_expensive_function() );
	  }

       While the Null adapter will simply ignore any of	the methods invoked on
       it, without this	conditional test the caller would otherwise still have
       to calculate the	value that won't be used. This structure allows	the
       calculation to be avoided if metrics are	not in use.

METHODS
	  $package = $metrics->package

       Returns the package name	that created the collector; the	package	in
       which the

	  use Metrics::Any '$metrics';

       statement was invoked.

METRIC TYPES
       Each type of metric is created by one of	the "make_*" methods. They all
       take the	following common arguments:

       name => ARRAY[ STRING ] | STRING
	   Optional. An	array of string	parts, or a plain string name to use
	   for reporting this metric to	its upstream service.

	   Modules should preferrably use an array of string parts to specify
	   their metric	names, as different adapter types may have different
	   ways	to represent this hierarchially. Base-level parts of the name
	   should come first, followed by more specific	parts. It is common
	   for related metrics to be grouped by	name having identical prefixes
	   but differing only in the final part.

	   The name is optional; if unspecified	then the handle	will be	used
	   to form the name, combined with a "name_prefix" argument if one was
	   set for the package.

       description => STRING
	   Optional human-readable description.	May be used for	debugging or
	   other purposes.

       labels => ARRAY[	STRING ]
	   Optional reference to an array of string names to use as label
	   names.

	   A labelled metric will expect to receive additional information in
	   its reporting method	to give	values for these labels. This
	   information should be in either an even-length array	reference of
	   name/value pairs, or	a hash reference. E.g.

	      $metrics->inc_counter( handle => [ labelname => $labelvalue ] );
	      $metrics->inc_counter( handle => { labelname => $labelvalue } );

	   A legacy form where a plain list of values is passed, each
	   corresponding to a named label in the same order, is	currently
	   accepted but	discouraged in favour of the above forms.

	      $metrics->inc_counter( handle => $labelvalue );

	   Note	that not all metric reporting adapters may be able to
	   represent all of the	labels.	Each should document what its
	   behaviour will be.

   Counter
       The "make_counter" method creates a new metric which counts occurances
       of some event within the	application. Its value begins at zero, and can
       be incremented by "inc_counter" whenever	the event occurs.

       Some counters may simple	count occurances of events, while others may
       count in	other units, for example counts	of bytes. Adapters may make
       use of the "units" parameter of the distribution	to perform some	kind
       of adapter-specific behaviour. The following units are suggested:

       bytes

       Observations give sizes in bytes	(perhaps memory	buffer or network
       message sizes), and should be integers.

   make_counter
	  $collector->make_counter( $handle, %args )

       Requests	the creation of	a new counter metric. The $handle name should
       be unique within	the collector instance,	though does not	need to	be
       unique across the entire	program, as it will be namespaced by the
       collector instance.

       The following extra arguments may be passed:

       units =>	STRING
	   A hint to the adapter about what kind of measurements are being
	   observed, so	it might take specific behaviour.

   inc_counter
	  $collector->inc_counter( $handle, $labels )

       Reports that the	counter	metric value be	incremented by one. The
       $handle name must match one earlier created by "make_counter".

   inc_counter_by
	  $collector->inc_counter_by( $handle, $amount,	$labels	)

       Reports that a counter metric value be incremented by some specified
       value.

   Distribution
       The "make_distribution" method creates a	new metric which counts
       individual observations of some numerical quantity (which may or	may
       not be integral).  New observations can be added	by the
       "report_distribution" method.

       Some adapter types may only store an aggregated total; others may store
       some sort of statistical	breakdown, either total	+ count, or a bucketed
       histogram.  The specific	adapter	documentation should explain how it
       handles distributions.

       Adapters	may make use of	the "units" parameter of the distribution to
       perform some kind of adapter-specific behaviour.	The following units
       are suggested:

       bytes

       Observations give sizes in bytes	(perhaps memory	buffer or network
       message sizes), and should be integers.

       seconds

       Observations give durations in seconds.

   make_distribution
	  $collector->make_distribution( $handle, %args	)

       Requests	the creation of	a new distribution metric.

       The following extra arguments may be passed:

       units =>	STRING
	   A hint to the adapter about what kind of measurements are being
	   observed, so	it might take specific behaviour. If unspecified, a
	   default of "bytes" will apply.

   report_distribution
	  $collector->report_distribution( $handle, $amount, $labels )

       Since version 0.05.

       Reports a new observation for the distribution metric. The $handle name
       must match one earlier created by "make_distribution". The $amount may
       be interpreted by the adapter depending on the defined "units" type for
       the distribution.

       This method used	to be called "inc_distribution_by" and is currently
       still available as an alias.

   Gauge
       The "make_gauge"	method creates a new metric which reports on the
       instantaneous value of some measurable quantity.	Unlike the other
       metric types this does not have to only increment forwards when certain
       events occur, but can measure a quantity	that may both increase and
       decrease	over time; such	as the number some kind	of object in memory,
       or the size of some data	structure.

       As an alternative to incrementing or decrementing the value when
       particular events occur,	the absolute value of the gauge	can also be
       set directly.

   make_gauge
	  $collector->make_gauge( $handle, %args )

       Requests	the creation of	a new gauge metric.

   inc_gauge
	  $collector->inc_gauge( $handle, $labels )

   dec_gauge
	  $collector->dec_gauge( $handle, $labels )

   inc_gauge_by
	  $collector->inc_gauge_by( $handle, $amount, $labels )

   dec_gauge_by
	  $collector->dec_gauge_by( $handle, $amount, $labels )

       Reports that the	observed value of the gauge has	increased or decreased
       by the given amount (or 1).

   set_gauge_to
	  $collector->set_gauge_to( $handle, $amount, $labels )

       Reports that the	observed value of the gauge is now the given amount.

       The $handle name	must match one earlier created by "make_gauge".

   Timer
       The "make_timer"	method creates a new metric which measures durations
       of time consumed	by the application. New	observations of	durations can
       be added	by the "report_timer" method.

       Timer metrics may be handled by the adapter similarly to	distribution
       metrics.	 Moreover, adapters may	choose to implement timers as
       distributions with units	of "seconds".

   make_timer
	  $collector->make_timer( $handle, %args )

       Requests	the creation of	a new timer metric.

   report_timer
	  $collector->report_timer( $handle, $duration,	$labels	)

       Since version 0.05.

       Reports a new duration for the timer metric. The	$handle	name must
       match one earlier created by "make_timer". The $duration	gives a	time
       measured	in seconds, and	may be fractional.

       This method used	to called "inc_timer_by" and is	currently still
       available as an alias.

AUTHOR
       Paul Evans <leonerd@leonerd.org.uk>

perl v5.32.0			  2020-08-09	    Metrics::Any::Collector(3)

NAME | SYNOPSIS | DESCRIPTION | ARGUMENTS | BOOLEAN OVERRIDE | METHODS | METRIC TYPES | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Metrics::Any::Collector&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help