File Coverage

blib/lib/Log/UDP/Client.pm
Criterion Covered Total %
statement 24 31 77.4
branch 3 10 30.0
condition 1 3 33.3
subroutine 7 7 100.0
pod 1 1 100.0
total 36 52 69.2


line stmt bran cond sub pod time code
1 5     5   68323 use strict;
  5         9  
  5         157  
2 5     5   17 use warnings;
  5         7  
  5         96  
3 5     5   68 use 5.006; # Found with Perl::MinimumVersion
  5         12  
4              
5             package Log::UDP::Client;
6             $Log::UDP::Client::VERSION = '0.20.1';
7 5     5   2377 use Moose;
  5         1503131  
  5         26  
8             with 'Data::Serializable' => { -version => '0.40.0' };
9              
10             # ABSTRACT: A simple way to send structured log messages via UDP
11              
12 5     5   26974 use IO::Socket::INET ();
  5         78721  
  5         110  
13 5     5   30 use Carp qw(carp croak);
  5         7  
  5         1172  
14              
15              
16             has "server_address" => (
17             is => 'rw',
18             isa => 'Str',
19             default => sub { "127.0.0.1"; },
20             );
21              
22              
23             has "server_port" => (
24             is => 'rw',
25             isa => 'Int',
26             default => sub { 9999; }
27             );
28              
29              
30             has "throws_exception" => (
31             is => 'rw',
32             isa => 'Bool',
33             default => 0,
34             );
35              
36              
37             has "socket" => (
38             is => 'ro',
39             isa => 'IO::Socket::INET',
40             lazy => 1,
41             default => sub { IO::Socket::INET->new( Proto => 'udp' ); }
42             );
43              
44              
45             # Perl::Critic bug: Subroutines::RequireArgUnpacking shouldn't be needed here
46             ## no critic qw(Subroutines::ProhibitBuiltinHomonyms Subroutines::RequireArgUnpacking)
47             sub send {
48 11003     11003 1 33195 my ($self, $message) = @_;
49              
50             # Make sure message was specified
51 11003 50       15406 if ( @_ < 2 ) {
52 0 0       0 croak("Please specify message") if $self->throws_exception;
53 0         0 return; # FAIL
54             }
55              
56             # Use the specified serializer to encode the message in a binary format
57 11003         17963 my $serialized_message = $self->serialize( $message );
58              
59             # Trap failure in serialization when not emitting exceptions
60 11003 50 33     707138 if ( not $self->throws_exception and not defined($serialized_message) ) {
61 0         0 return; # FAIL
62             }
63              
64             # Send UDP message
65 11003         215211 my $length = CORE::send(
66             $self->socket,
67             $serialized_message,
68             0,
69             IO::Socket::INET::pack_sockaddr_in(
70             $self->server_port,
71             IO::Socket::INET::inet_aton( $self->server_address )
72             )
73             );
74              
75             # Check for transmission error
76 11003 50       24028 if ( $length != length($serialized_message) ) {
77 0         0 my $error = "Couldn't send message: $!\n";
78 0 0       0 croak($error) if $self->throws_exception;
79 0         0 carp($error);
80 0         0 return 0;
81             }
82              
83             # Everything OK
84 11003         24133 return 1;
85              
86             }
87              
88             1;
89              
90             __END__
91              
92             =pod
93              
94             =encoding UTF-8
95              
96             =head1 NAME
97              
98             Log::UDP::Client - A simple way to send structured log messages via UDP
99              
100             =head1 VERSION
101              
102             version 0.20.1
103              
104             =head1 SYNOPSIS
105              
106             use Log::UDP::Client;
107              
108             # Send the simple scalar to the server
109             Log::UDP::Client->new->send("Hi");
110              
111             # Log lots of messages
112             my $logger = Log::UDP::Client->new(server_port => 15000);
113             my $counter=0;
114             while(++$counter) {
115             $logger->send($counter);
116             last if $counter >= 1000;
117             }
118              
119             # Send some debugging info
120             $logger->send({
121             pid => $$,
122             program => $0,
123             args => \@ARGV,
124             });
125              
126             # Use of JSON serializer
127             my $logger = Log::UDP::Client->new( serializer_module => 'JSON' );
128              
129             # Will emit { "message" => "Hi" } because JSON want to wrap stuff into a hashref
130             $logger->send("Hi");
131              
132             # Use of custom serializer
133             use Storable qw(freeze);
134             my $logger = Log::UDP::Client->new (
135             serializer => sub {
136             return nfreeze( \( $_[0] ) );
137             },
138             );
139              
140             =head1 DESCRIPTION
141              
142             This module enables you to send a message (simple string or complicated object)
143             over an UDP socket to a listening server. The message will be encoded with a
144             serializer module (default is L<Storable>).
145              
146             =head1 ATTRIBUTES
147              
148             =head2 server_address : Str
149              
150             IP address or hostname for the server you want to send the messages to.
151             This field can be changed after instantiation. Default is 127.0.0.1.
152              
153             =head2 server_port : Int
154              
155             Port for the server you plan to send the messages to.
156             This field can be changed after instantiation. Default is port 9999.
157              
158             =head2 throws_exception : Bool
159              
160             If errors are encountered, should we throw exception or just return?
161             Default is return. Set to true for exceptions. You can change this flag
162             after instantiation.
163              
164             =head2 socket : IO::Socket::INET
165              
166             Read-only field that contains the socket used to send the messages.
167              
168             =head1 METHODS
169              
170             =head2 send($message)
171              
172             Instance method that actually encodes and transmits the specified message
173             over UDP to the listening server. Will die if throw_exception is set to true
174             and some kind of transmission error occurs. The message will be serialized by
175             the instance-defined serializer. Returns true on success.
176              
177             =head1 INHERITED METHODS
178              
179             =over 4
180              
181             =item *
182              
183             deserialize
184              
185             =item *
186              
187             deserializer
188              
189             =item *
190              
191             serialize
192              
193             =item *
194              
195             serializer
196              
197             =item *
198              
199             serializer_module
200              
201             =back
202              
203             All of these methods are inherited from L<Data::Serializable>. Read more about them there.
204              
205             =head1 SEE ALSO
206              
207             =over 4
208              
209             =item *
210              
211             L<Moose>
212              
213             =item *
214              
215             L<Storable>
216              
217             =item *
218              
219             L<JSON::XS>
220              
221             =item *
222              
223             L<IO::Socket::INET>
224              
225             =back
226              
227             =for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan
228              
229             =head1 SUPPORT
230              
231             =head2 Perldoc
232              
233             You can find documentation for this module with the perldoc command.
234              
235             perldoc Log::UDP::Client
236              
237             =head2 Websites
238              
239             The following websites have more information about this module, and may be of help to you. As always,
240             in addition to those websites please use your favorite search engine to discover more resources.
241              
242             =over 4
243              
244             =item *
245              
246             MetaCPAN
247              
248             A modern, open-source CPAN search engine, useful to view POD in HTML format.
249              
250             L<http://metacpan.org/release/Log-UDP-Client>
251              
252             =item *
253              
254             Search CPAN
255              
256             The default CPAN search engine, useful to view POD in HTML format.
257              
258             L<http://search.cpan.org/dist/Log-UDP-Client>
259              
260             =item *
261              
262             RT: CPAN's Bug Tracker
263              
264             The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.
265              
266             L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Log-UDP-Client>
267              
268             =item *
269              
270             AnnoCPAN
271              
272             The AnnoCPAN is a website that allows community annotations of Perl module documentation.
273              
274             L<http://annocpan.org/dist/Log-UDP-Client>
275              
276             =item *
277              
278             CPAN Ratings
279              
280             The CPAN Ratings is a website that allows community ratings and reviews of Perl modules.
281              
282             L<http://cpanratings.perl.org/d/Log-UDP-Client>
283              
284             =item *
285              
286             CPAN Forum
287              
288             The CPAN Forum is a web forum for discussing Perl modules.
289              
290             L<http://cpanforum.com/dist/Log-UDP-Client>
291              
292             =item *
293              
294             CPANTS
295              
296             The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.
297              
298             L<http://cpants.perl.org/dist/overview/Log-UDP-Client>
299              
300             =item *
301              
302             CPAN Testers
303              
304             The CPAN Testers is a network of smokers who run automated tests on uploaded CPAN distributions.
305              
306             L<http://www.cpantesters.org/distro/L/Log-UDP-Client>
307              
308             =item *
309              
310             CPAN Testers Matrix
311              
312             The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.
313              
314             L<http://matrix.cpantesters.org/?dist=Log-UDP-Client>
315              
316             =item *
317              
318             CPAN Testers Dependencies
319              
320             The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.
321              
322             L<http://deps.cpantesters.org/?module=Log::UDP::Client>
323              
324             =back
325              
326             =head2 Bugs / Feature Requests
327              
328             Please report any bugs or feature requests by email to C<bug-log-udp-client at rt.cpan.org>, or through
329             the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Log-UDP-Client>. You will be automatically notified of any
330             progress on the request by the system.
331              
332             =head2 Source Code
333              
334             The code is open to the world, and available for you to hack on. Please feel free to browse it and play
335             with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull
336             from your repository :)
337              
338             L<http://github.com/robinsmidsrod/Log-UDP-Client>
339              
340             git clone git://github.com/robinsmidsrod/Log-UDP-Client.git
341              
342             =head1 AUTHOR
343              
344             Robin Smidsrød <robin@smidsrod.no>
345              
346             =head1 COPYRIGHT AND LICENSE
347              
348             This software is copyright (c) 2017 by Robin Smidsrød.
349              
350             This is free software; you can redistribute it and/or modify it under
351             the same terms as the Perl 5 programming language system itself.
352              
353             =cut