File Coverage

blib/lib/Monitor/MetricsAPI/Metric.pm
Criterion Covered Total %
statement 17 17 100.0
branch 2 2 100.0
condition n/a
subroutine 6 6 100.0
pod 2 2 100.0
total 27 27 100.0


line stmt bran cond sub pod time code
1 13     13   64 use strict;
  13         22  
  13         451  
2 13     13   1143 use warnings;
  13         26  
  13         734  
3              
4             package Monitor::MetricsAPI::Metric;
5             $Monitor::MetricsAPI::Metric::VERSION = '0.900';
6 13     13   64 use namespace::autoclean;
  13         20  
  13         118  
7 13     13   1034 use Moose;
  13         27  
  13         91  
8              
9             =head1 NAME
10              
11             Monitor::MetricsAPI::Metric - Base class for Monitor::MetricsAPI metrics.
12              
13             =head1 SYNOPSIS
14              
15             You should not interact with this module directly in your code. Please refer to
16             L<Monitor::MetricsAPI> for how to integrate this service with your application.
17              
18             =head1 DESCRIPTION
19              
20             =cut
21              
22             =head1 METRIC TYPES
23              
24             Several different types of metrics are offered, to allow for tracking many
25             unique and varying bits of information in your applications. Each metric type
26             behaves slightly different, permits its own limited range of values, and
27             exposes its own set of methods for manipulating the metric value.
28              
29             It is important that you choose the proper type of metric for whatever it is
30             you are attempting to track. Using a boolean metric, for instance, to monitor
31             your memory usage is utter nonsense, as is using a string metric for your API
32             requests counter.
33              
34             =over
35              
36             =item * L<string|Monitor::MetricsAPI::Metric::String>
37              
38             The simplest of metric types. Any arbitrary string value may be stored in the
39             metric and it will be echoed back in reporting output. Application names,
40             version numbers, build numbers, and so on make sense for String metrics.
41              
42             =item * L<boolean|Monitor::MetricsAPI::Metric::Boolean>
43              
44             Boolean metrics allow you to monitor the true/false/unknown state of something.
45              
46             =item * L<counter|Monitor::MetricsAPI::Metric::Counter>
47              
48             =item * L<gauge|Monitor::MetricsAPI::Metric::Gauge>
49              
50             =item * L<timestamp|Monitor::MetricsAPI::Metric::Timestamp>
51              
52             Timestamp metrics allow you to update a timestamp when a particular event
53             occurs. Useful for ensuring that it hasn't been too long since an expected
54             event has been triggered.
55              
56             =item * L<callback|Monitor::MetricsAPI::Metric::Callback>
57              
58             Callback metrics allow you to supply a subroutine to invoke any time the metric
59             is included in reporting output. Useful when the metric requires additional
60             computation (e.g. avg-events-over-time), or the use of an external resource
61             such as a database (e.g. total registered users).
62              
63             =back
64              
65             =cut
66              
67             has 'name' => (
68             is => 'ro',
69             isa => 'Str',
70             required => 1,
71             );
72              
73             has 'type' => (
74             is => 'ro',
75             isa => 'Str',
76             required => 1,
77             );
78              
79             has '_value' => (
80             is => 'ro',
81             predicate => '_has_value',
82             writer => '_set_value',
83             clearer => '_clear_value',
84             );
85              
86             =head1 BASE METHODS
87              
88             The following methods are provided for all types of metrics. Additional methods
89             may be provided by individual metric types.
90              
91             =head2 value
92              
93             Returns the current value of the metric.
94              
95             =cut
96              
97             sub value {
98 25     25 1 40 my ($self) = @_;
99              
100 25 100       1032 return unless $self->_has_value;
101 22         1194 return $self->_value;
102             }
103              
104             =head2 set ($value)
105              
106             Updates the current value of the metric to $value. Individual metric types may
107             perform validation on the value.
108              
109             =cut
110              
111             sub set {
112 4     4 1 9 my ($self, $value) = @_;
113              
114 4         210 return $self->_set_value($value);
115             }
116              
117             =head1 AUTHORS
118              
119             Jon Sime <jonsime@gmail.com>
120              
121             =head1 LICENSE AND COPYRIGHT
122              
123             This software is copyright (c) 2015 by OmniTI Computer Consulting, Inc.
124              
125             This module is free software; you can redistribute it and/or
126             modify it under the same terms as Perl itself. See L<perlartistic>.
127              
128             This program is distributed in the hope that it will be useful,
129             but WITHOUT ANY WARRANTY; without even the implied warranty of
130             MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
131              
132             =cut
133              
134             __PACKAGE__->meta->make_immutable;
135             1;