File Coverage

blib/lib/Net/Prometheus/Gauge.pm
Criterion Covered Total %
statement 41 41 100.0
branch 7 8 87.5
condition n/a
subroutine 11 11 100.0
pod 2 2 100.0
total 61 62 98.3


line stmt bran cond sub pod time code
1             # You may distribute under the terms of either the GNU General Public License
2             # or the Artistic License (the same terms as Perl itself)
3             #
4             # (C) Paul Evans, 2016,2018 -- leonerd@leonerd.org.uk
5              
6             package Net::Prometheus::Gauge;
7              
8 11     11   74860 use strict;
  11         32  
  11         328  
9 11     11   57 use warnings;
  11         24  
  11         299  
10 11     11   56 use base qw( Net::Prometheus::Metric );
  11         20  
  11         5093  
11              
12             our $VERSION = '0.12';
13              
14 11     11   83 use Carp;
  11         77  
  11         649  
15              
16 11     11   82 use constant _type => "gauge";
  11         20  
  11         5383  
17              
18             __PACKAGE__->MAKE_child_class;
19              
20             =head1 NAME
21              
22             C - a snapshot value-reporting metric
23              
24             =head1 SYNOPSIS
25              
26             use Net::Prometheus;
27              
28             my $client = Net::Prometheus->new;
29              
30             my $gauge = $client->new_gauge(
31             name => "users",
32             help => "Number of current users",
33             );
34              
35             my %users;
36             ...
37              
38             $gauge->set( scalar keys %users );
39              
40             =head1 DESCRIPTION
41              
42             This class provides a gauge metric - an arbitrary value that observes some
43             snapshot of state at some instant in time. This is often used to report on the
44             current usage of resources by the instrumented program, in a way that can
45             decrease as well as increase. It is a subclass of L.
46              
47             =head2 Value-Reporting Functions
48              
49             As an alternative to using the C method to update the value of the gauge,
50             a callback function can be used instead which should return the current value
51             to report for that gauge. This function is invoked at collection time, meaning
52             the reported value is up-to-date.
53              
54             These functions are invoked inline as part of the collection process, so they
55             should be as small and lightweight as possible. Typical applications involve
56             reporting the size of an array or hash within the implementation's code.
57              
58             $gauge->set_function( sub { scalar @items } );
59              
60             $gauge->set_function( sub { scalar keys %things } );
61              
62             =cut
63              
64             =head1 CONSTRUCTOR
65              
66             Instances of this class are not usually constructed directly, but instead via
67             the L object that will serve it:
68              
69             $gauge = $prometheus->new_gauge( %args )
70              
71             This takes the same constructor arguments as documented in
72             L.
73              
74             =cut
75              
76             sub new
77             {
78 12     12 1 3368 my $class = shift;
79              
80 12         71 my $self = $class->SUPER::new( @_ );
81              
82 12         42 $self->{values} = {};
83 12         25 $self->{functions} = {};
84              
85 12 100       43 $self->inc( 0 ) if !$self->labelcount;
86              
87 12         56 return $self;
88             }
89              
90             =head1 METHODS
91              
92             =cut
93              
94             =head2 set
95              
96             $gauge->set( @label_values, $value )
97             $gauge->set( \%labels, $value )
98              
99             $child->set( $value )
100              
101             Sets the current value for the gauge.
102              
103             If the gauge has any labels defined, the values for them must be given first.
104              
105             =cut
106              
107             __PACKAGE__->MAKE_child_method( 'set' );
108             sub _set_child
109             {
110 13     13   28 my $self = shift;
111 13         27 my ( $labelkey, $value ) = @_;
112              
113 13         39 $self->{values}{$labelkey} = $value;
114             }
115              
116             =head2 set_function
117              
118             $gauge->set_function( @label_values, $func )
119             $gauge->set_function( \%labels, $func )
120              
121             $child->set_function( $func )
122              
123             Sets a value-returning callback function for the gauge. If the gauge is
124             labeled, each label combination requires its own function.
125              
126             When invoked, the function will be passed no arguments and is expected to
127             return a single value
128              
129             $value = $func->()
130              
131             =cut
132              
133             __PACKAGE__->MAKE_child_method( 'set_function' );
134             sub _set_function_child
135             {
136 2     2   5 my $self = shift;
137 2         5 my ( $labelkey, $func ) = @_;
138              
139             # Need to store some sort of value so we still iterate on this labelkey
140             # during ->samples
141 2         8 $self->{values}{$labelkey} = undef;
142 2         7 $self->{functions}{$labelkey} = $func;
143             }
144              
145             =head2 inc
146              
147             $gauge->inc( @label_values, $delta )
148             $gauge->inc( \%labels, $delta )
149              
150             $child->inc( $delta )
151              
152             Increment the current value for the gauge. C<$delta> will default to 1 if not
153             supplied.
154              
155             =cut
156              
157             __PACKAGE__->MAKE_child_method( 'inc' );
158             sub _inc_child
159             {
160 11     11   23 my $self = shift;
161 11         24 my ( $labelkey, $delta ) = @_;
162 11 100       39 defined $delta or $delta = 1;
163              
164 11         35 $self->{values}{$labelkey} += $delta;
165             }
166              
167             =head2 dec
168              
169             $gauge->dec( @label_values, $delta )
170             $gauge->dec( \%labels, $delta )
171              
172             $child->dec( $delta )
173              
174             Decrement the current value for the gauge. C<$delta> will default to 1 if not
175             supplied.
176              
177             =cut
178              
179             __PACKAGE__->MAKE_child_method( 'dec' );
180             sub _dec_child
181             {
182 1     1   3 my $self = shift;
183 1         3 my ( $labelkey, $delta ) = @_;
184 1 50       4 defined $delta or $delta = 1;
185              
186 1         4 $self->{values}{$labelkey} -= $delta;
187             }
188              
189             sub samples
190             {
191 17     17 1 1335 my $self = shift;
192              
193 17         33 my $values = $self->{values};
194 17         156 my $functions = $self->{functions};
195              
196             return map {
197 17         87 $self->make_sample( undef, $_,
198 22 100       122 $functions->{$_} ? $functions->{$_}->() : $values->{$_}
199             )
200             } sort keys %$values;
201             }
202              
203             =head1 AUTHOR
204              
205             Paul Evans
206              
207             =cut
208              
209             0x55AA;