NAME

    Net::Prometheus::PerlCollector - obtain statistics about the perl
    interpreter

SYNOPSIS

       use Net::Prometheus;
       use Net::Prometheus::PerlCollector;
    
       my $client = Net::Prometheus->new;
       $client->register( Net::Prometheus::PerlCollector->new );

DESCRIPTION

    This module provides a class that collects metrics about the perl
    interpreter itself.

 Metrics

    The following metrics are collected:

      * perl_heap_arenas

      A gauge giving the number of arenas the heap is split into.

      * perl_heap_svs

      A gauge giving the total number of SVs allocated on the heap.

       # HELP perl_heap_arenas Number of arenas in the Perl heap
       # TYPE perl_heap_arenas gauge
       perl_heap_arenas 159
       # HELP perl_heap_svs Number of SVs in the Perl heap
       # TYPE perl_heap_svs gauge
       perl_heap_svs 26732

    Note that the way these metrics are collected requires counting them
    all every time. While this code is relatively efficient, it is still a
    linear scan, and may itself cause some slowdown of the process at the
    time it is collected, if the heap has grown very large, containing a
    great number of SVs.

    Extra detail can be obtained about the types of heap objects by setting

       $Net::Prometheus::PerlCollector::DETAIL = 1;

    This will be slightly more expensive to count, but will yield in
    addition a detailed breakdown by object type.

       # HELP perl_heap_svs_by_type Number of SVs classified by type
       # TYPE perl_heap_svs_by_type gauge
       perl_heap_svs_by_type{type="ARRAY"} 2919
       perl_heap_svs_by_type{type="CODE"} 1735
       perl_heap_svs_by_type{type="GLOB"} 2647
       perl_heap_svs_by_type{type="HASH"} 470
       perl_heap_svs_by_type{type="INVLIST"} 68
       perl_heap_svs_by_type{type="IO"} 12
       perl_heap_svs_by_type{type="NULL"} 8752
       perl_heap_svs_by_type{type="REGEXP"} 171
       perl_heap_svs_by_type{type="SCALAR"} 9958

    This level of detail is unlikely to be useful for most generic
    production purposes but may be helpful to set in specific processes
    when investigating specific memory-related issues for a limited time.

    For an even greater level of detail, set the value to 2 to additionally
    obtain another breakdown of blessed objects by class:

       # HELP perl_heap_svs_by_class Number of SVs classified by class
       # TYPE perl_heap_svs_by_class gauge
       ...
       perl_heap_svs_by_class{class="Net::Prometheus"} 1
       perl_heap_svs_by_class{class="Net::Prometheus::PerlCollector"} 1
       perl_heap_svs_by_class{class="Net::Prometheus::ProcessCollector::linux"} 1

    Note that this will yield a large amount of output for any
    non-trivially sized program, so should only be enabled under
    carefully-controlled conditions.

    The value of this variable can be overridden on a per-collection basis
    by passing the option

       Net::Prometheus->render( { perl_collector_detail => 1 } );  # or 2

    This may be more convenient for short-term traces from exporters that
    parse HTTP query parameters into collector options.

       GET .../metrics?perl_collector_detail=1

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>

