blib/lib/Mojo/Graphite/Writer.pm

filter: Statementstmt 85.0% 91 / 107 Branchbran 81.8% 18 / 22 Conditioncond 50.0% 7 / 14 MC/DCmcdc 11.1% 1 / 9 Subroutinesub 76.1% 16 / 21 Podpod 100% 3 / 3 totaltotal 77.2% 136 / 176 CC 18 SCAR 12.0
CC
18
Cov
81%
connect
7.0
__ANON__
6.0
_write
4.1
CRAP 3.3
↑ Summary
1 package Mojo::Graphite::Writer;
2  
3 2 ▶use Mojo::Base -base;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 2 ▶use feature 'current_sub';
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 2 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
8 2 ▶use Mojo::IOLoop;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 2 ▶use Mojo::Promise;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 2 ▶use constant DEBUG => $ENV{MOJO_GRAPHITE_WRITER_DEBUG};
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 2 our $VERSION = '0.08';
14 2 $VERSION = eval $VERSION;
15  
16 0 ▶has address => sub { Carp::croak 'address is required' };
Subroutine __ANON__: not called CC=1 SCAR=1.2
17 2 has batch_size => 100;
18 1 ▶has preprocess => sub { \&_preprocess };
Subroutine __ANON__: called CC=1 SCAR=0.0
19 2 has port => 2003;
20  
21 0 ▶sub close {
Subroutine close: not called CC=1 SCAR=6.9
Pod documented
22 0 my $self = shift;
23 0 my $stream = $self->{stream};
24 0 $stream->close;
25 0 return $self;
26 }
27  
28 5 ▶sub connect {
Subroutine connect: called CC=6 SCAR=19.5
Pod documented
29 5 my ($self, %args) = @_;
30 5 my $p = Mojo::Promise->new;
31  
32 # Fork-safety
33 5 ▶ delete @$self{qw(pid stream)} unless ($self->{pid} //= $$) eq $$;
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"pid"} //= $$) eq $$ 1 4 5
Condition66%2/3
$self->{"pid"} //= $$
l!l&&r!l&&!r
320
MC/DC0%0/2
$self->{"pid"} //= $$
$self->{"pid"} $$
Truth table66%2/3
A //= B
A= $self->{"pid"}B= $$
ABresult
1X1
011
000
34  
35 5 ▶ if (my $stream = $self->{stream}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $stream = $self->{'stream'}) { } 3 2 5
36 3 say STDERR "Reusing existing Graphite connection" if DEBUG;
37 3 $p->resolve($stream);
38 } else {
39 2 ▶ $args{address} //= $self->address;
Condition33%1/3
$args{"address"} //= $self->address
l!l&&r!l&&!r
020
MC/DC0%0/2
$args{"address"} //= $self->address
$args{"address"} $self->address
Truth table33%1/3
A //= B
A= $args{"address"}B= $self->address
ABresult
1X1
011
000
40 2 ▶ $args{port} //= $self->port;
Condition33%1/3
$args{"port"} //= $self->port
l!l&&r!l&&!r
020
MC/DC0%0/2
$args{"port"} //= $self->port
$args{"port"} $self->port
Truth table33%1/3
A //= B
A= $args{"port"}B= $self->port
ABresult
1X1
011
000
41 2 say STDERR "Connecting to Graphite on $args{address}:$args{port}" if DEBUG;
42 2 ▶ Mojo::IOLoop->client(%args, sub {
Subroutine __ANON__: called CC=2 SCAR=8.8
43 2 my (undef, $err, $stream) = @_;
44 2 ▶ if ($err) {
Branch: 1 branch
BranchTrueFalseTotal
if ($err) 0 2 2
45 0 say STDERR "Error opening Graphite socket: $err" if DEBUG;
46 0 return $p->reject($err);
47 }
48 2 say STDERR "Graphite socket opened" if DEBUG;
49 0 ▶ $stream->on(write => sub { say STDERR "Writing @{[length $_[1]]} bytes to Graphite" }) if DEBUG;
Subroutine __ANON__: not called CC=1 SCAR=2.6
50 0 ▶ $stream->on(close => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
51 0 say STDERR "Graphite socket closed" if DEBUG;
52 0 delete $self->{stream};
53 2 });
54 2 $self->{stream} = $stream;
55 2 $p->resolve($stream);
56 2 });
57 }
58 5 return $p;
59 }
60  
61 3 ▶sub write {
Subroutine write: called CC=3 SCAR=11.0
Pod documented
62 3 my ($self, @metrics) = @_;
63 3 my $p = Mojo::Promise->new;
64 3 ▶ if (my $cb = $self->preprocess) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $cb = $self->preprocess) 3 0 3
65 # need parens on ref to disambiguate on older perls
66 3 ▶ @metrics = map { ref() ? $cb->($_) : $_ } @metrics;
Branch: 1 branch
BranchTrueFalseTotal
ref $_ ? : 4 4 8
67 }
68 3 push @{ $self->{queue} }, [\@metrics, $p];
69 3 $self->_write;
70 3 return $p;
71 }
72  
73 4 ▶sub _preprocess {
Subroutine _preprocess: called CC=4 SCAR=13.9
74 # N.B. this function isn't called on raw strings
75 # clone the array contents so as not to modify originals
76 4 my @metric = @{$_[0]};
77  
78 # default to current time
79 4 ▶ $metric[2] = _time() unless defined $metric[2];
Branch: 1 branch
BranchTrueFalseTotal
unless defined $metric[2] 2 2 4
80  
81 # format tags, append to name
82 4 ▶ if ($metric[3] && keys %{$metric[3]}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($metric[3] and keys %{$metric[3];}) 3 1 4
Condition66%2/3
$metric[3] and keys %{$metric[3];}
!ll&&!rl&&r
103
MC/DC50%1/2
$metric[3] and keys %{$metric[3];}
$metric[3] keys %{$metric[3];}
Truth table66%2/3
A and B
A= $metric[3]B= keys %{$metric[3];}
ABresult
0X0
100
111
83 2 ▶ no warnings 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
84 $metric[0] .= ';' . join ';',
85 # clean up invalid characters
86 6 map { s/\(|\)//gr }
87 6 map { s/\s+/_/gr }
88 # basic structure
89 6 map { "$_=$metric[3]{$_}" }
90 3 sort keys %{$metric[3]};
91 }
92  
93 4 return "$metric[0] $metric[1] $metric[2]";
94 }
95  
96 # better overridablility in testing, yes I hate that but ...
97 2 ▶BEGIN { *_time = \&CORE::time }
Subroutine BEGIN: called CC=1 SCAR=0.0
98  
99 3 ▶sub _write {
Subroutine _write: called CC=4 SCAR=14.2
100 3 my $self = shift;
101 3 ▶ return unless @{ $self->{queue} ||= [] };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->{"queue"} ||= [];} 0 3 3
Condition50%1/2
$self->{"queue"} ||= []
l!l
30
MC/DC0%0/1
$self->{"queue"} ||= []
$self->{"queue"}
Truth table50%1/2
A
A= $self->{"queue"}
Aresult
11
00
102  
103 3 ▶ return if $self->{writing};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"writing"} 0 3 3
104 3 $self->{writing} = 1;
105  
106 $self->connect->then(
107 3 ▶ sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
108 3 my $stream = shift;
109 6 ▶ my $write = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
110 6 my $queue = $self->{queue};
111  
112 # this batch is done
113 6 ▶ unless (@{ $queue->[0][0] }) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@{$queue->[0][0];}) 3 3 6
114 3 my $item = shift @$queue;
115 3 my $p = $item->[1];
116 3 $p->resolve;
117 }
118  
119 # queue is empty
120 6 ▶ unless (@$queue) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@$queue) 3 3 6
121 3 $self->{writing} = 0;
122 3 return;
123 }
124  
125 3 my $string = join '', map { chomp; "$_\n" } splice @{ $queue->[0][0] }, 0, $self->batch_size;
126 3 $stream->write($string, __SUB__);
127 3 };
128  
129 3 $write->();
130 },
131 0 ▶ sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
132 0 my $err = shift;
133 0 $_->[1]->reject($err) for @{ $self->{queue} };
134 0 $self->{queue} = [];
135 0 $self->{writing} = 0;
136 }
137 3 );
138 }
139  
140 2 1;
141  
142 =head1 NAME
143  
144 Mojo::Graphite::Writer - A non-blocking Graphite metric writer using the Mojo stack
145  
146 =head1 SYNOPSIS
147  
148 my $graphite = Mojo::Graphite::Writer->new(address => 'graphite.myhost.com');
149 my $time = time;
150 $graphite->write(
151 "my.metric.one 1 $time",
152 "my.metric.two 2 $time",
153 ...
154 );
155  
156 # preprocessing
157 $graphite->write(
158 ['my.metric.three', 3],
159 ['my.metric.four', 4, $time],
160 ['my.metric.five', 5, undef, {foo => 'bar'}],
161 ...
162 );
163  
164 =head1 DESCRIPTION
165  
166 L<Mojo::Graphite::Writer> is a non-blocking client for feeding data to the Graphite metrics collector.
167 This simple module is meant to aid in formattting, batching, and queuing writes to the server in a fork-safe way.
168  
169 =head1 ATTRIBUTES
170  
171 L<Mojo::Graphite::Writer> inherits all attributes from L<Mojo::Base> and implements the following new ones.
172  
173 =head2 address
174  
175 Address of the target Graphite server.
176 Required.
177  
178 =head2 batch_size
179  
180 The number of metrics to send in each write batch.
181 Default is 100.
182  
183 =head2 preprocess
184  
185 A callback that is used to process a metric specified as an arrayref, the callback is not called on raw strings.
186 The callback is passed the array reference as its only argument, it should return a string to be written, it need not end with a newline.
187  
188 The default callback expects a metric arrayref to contain a metric name and a value in the first two slots.
189 If the time is not specified in the third slot (or is undef) then the current time will be used.
190 If the fourth slot contains a non-empty hashref then those will be treated as key-value tags.
191 The tags will be cleaned up, removing parenthesis characters and converting spaces to underscores.
192 They will then be formatted by joining keys and values with an equal sign and joined to the metric name with semicolons.
193  
194 Preprocessing can be fully disabled by setting the attribute to a false value.
195 Passing an array reference without a preprocessing callback will probably not do anything useful.
196  
197 =head2 port
198  
199 Port of the target Graphite server.
200 Default is C<2003>.
201  
202 =head1 METHODS
203  
204 L<Mojo::Graphite::Writer> inherits all methods from L<Mojo::Base> and implements the following new ones.
205  
206 =head2 close
207  
208 Close the current connection to L</address>.
209  
210 =head2 connect
211  
212 Open a new connection to L</address>:L</port> using L<Mojo::IOLoop/client>.
213 Any additional arguments are passed through to that method.
214 Returns a L<Mojo::Promise> that resolves with the L<Mojo::IOLoop::Stream> object of the connection.
215  
216 Note that if the client is already connected, the promise is resolved again with the same stream and will until that stream is closed.
217 In this way, for simple connections, you may simple call L</write> while for more complex ones, you may open the connction using this method with additional arguments if needed and then call L</write> later.
218  
219 =head2 write
220  
221 Write metrics to the L</connect>-ed graphite server.
222 Metrics are queued and written to the server in a non-blocking way, in the order that L</write> is called.
223  
224 Metrics are strings of the form C<path value time> as documented as L<"the plaintext protocol"|https://graphite.readthedocs.io/en/latest/feeding-carbon.html#the-plaintext-protocol>.
225 Each string is one metric.
226 It will be line-ending normalized, no newline is required.
227  
228 Metrics may also be specified as an array reference.
229 If so they will be preprocessed using the callback in L</preprocess> which will transform it to a string to be written as documented above.
230 Preprocessing occurs immediately during the call to write.
231  
232 Writes are batched in groups of size L</batch_size>.
233 If the writer is not already connected, calling write will implicitly call L</connect>.
234  
235 Returns a L<Mojo::Promise> that will be resolved when the metrics passed B<in this write call> are written.
236 The promise is rejected if any write in the write queue fails, even if it is not from the write call.
237  
238 =head1 FUTURE WORK
239  
240 Future work may include
241  
242 =over
243  
244 =item *
245  
246 Possibly a blocking api, though this is questionable
247  
248 =back
249  
250 =head1 SEE ALSO
251  
252 =over
253  
254 =item *
255  
256 L<https://graphite.readthedocs.io/en/latest/>
257  
258 =back
259  
260 =head1 THANKS
261  
262 This module's development was sponsored by L<ServerCentral Turing Group|https://www.servercentral.com/>.
263  
264 =head1 SOURCE REPOSITORY
265  
266 L<http://github.com/jberger/Mojo-Graphite-Writer>
267  
268 =head1 AUTHOR
269  
270 Joel Berger, E<lt>joel.a.berger@gmail.comE<gt>
271  
272 =head1 CONTRIBUTORS
273  
274 None yet.
275  
276 =head1 THANKS
277  
278 Mohammad S Anwar (manwar)
279  
280 =head1 COPYRIGHT AND LICENSE
281  
282 Copyright (C) 2019 by L</AUTHOR> and L</CONTRIBUTORS>
283  
284 This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
285  
286  
↑ Summary