File Coverage

blib/lib/Pye.pm
Criterion Covered Total %
statement 6 14 42.8
branch 0 6 0.0
condition n/a
subroutine 2 3 66.6
pod 1 1 100.0
total 9 24 37.5


line stmt bran cond sub pod time code
1             package Pye;
2              
3             # ABSTRACT: Session-based logging platform on top of SQL/NoSQL databases
4              
5 1     1   15153 use Carp;
  1         1  
  1         67  
6 1     1   1399459 use Role::Tiny;
  1         3423  
  1         6  
7              
8             our $VERSION = "2.001001";
9             $VERSION = eval $VERSION;
10              
11             =head1 NAME
12              
13             Pye - Session-based logging platform on top of SQL/NoSQL databases
14              
15             =head1 SYNOPSIS
16              
17             use Pye;
18              
19             # start logging on top of a certain backend, say Pye::MongoDB
20             # (you can also call new() directly on the backend class, check
21             # out the documentation of the specific backend)
22              
23             my $pye = Pye->new('MongoDB',
24             host => 'mongodb://logserver:27017',
25             database => 'log_db',
26             collection => 'myapp_log'
27             );
28              
29             # if you've created your own backend, prefix it with a plus sign
30             my $pye = Pye->new('+My::Pye::Backend', \%options);
31              
32             # now start logging
33             $pye->log($session_id, "Some log message", { data => 'example data' });
34              
35             =head1 DESCRIPTION
36              
37             C is a dead-simple, session-based logging platform where all logs are stored
38             in a database. Log messages in C include a date, a text message, and possibly
39             a data structure (hash/array-ref) that "illustrates" the text.
40              
41             I built C due to my frustration with file-based loggers that generate logs that
42             are extremely difficult to read, analyze and maintain.
43              
44             C is most useful for services (e.g. web apps) that handle requests,
45             or otherwise work in sessions, but can be useful in virtually any application,
46             including automatic (e.g. cron) scripts.
47              
48             In order to use C, your program must define an ID for every session. "Session"
49             can really mean anything here: a client session in a web service, a request to your
50             web service, an execution of a script, whatever. As long as a unique ID can be generated,
51             C can handle logging for you.
52              
53             Main features:
54              
55             =over
56              
57             =item * B
58              
59             With C, any complex data structure (i.e. hash/array) can be attached to any log message,
60             enabling you to illustrate a situation, display complex data, etc.
61              
62             =item * B
63              
64             Yeah, I consider this a feature. Log levels are a bother, and I don't need them. All log
65             messages in C are saved into the database, nothing gets lost.
66              
67             =item * B
68              
69             C comes with a command line utility, L, that offers quick inspection of the log.
70             You can easily view a list of current/latest sessions and read the log of a specific session.
71             No more mucking about through endless log files, trying to understand which lines belong to which
72             session, or trying to find that area of the file with messages from that certain date your software
73             died on.
74              
75             =item * B
76              
77             C supports several database backends. Currently, L supports MongoDB, and
78             L supports MySQL, PostgreSQL and SQLite.
79              
80             =back
81              
82             This package provides two purposes. It provides a constructor that dynamically loads the
83             requested backend class and creates an object of it. It is also a role (with L)
84             detailing methods backend classes are required to implement.
85              
86             =head2 UPGRADING TO v2.0.0 AND UP
87              
88             Originally, C was purely a MongoDB logging system, and this module provided the
89             MongoDB functionality. Since v2.0.0, C became a system with pluggable backends, and
90             the MongoDB functionality was moved to L (not provided by this distribution,
91             so you should install that too if you've been using Pye before v2.0.0).
92              
93             An improvement over v1.*.* was also introduced: before, every application had two collections
94             in the database - a log collection and a session collection. The session collection is not
95             needed anymore. You can remove these session collections from your current database with no
96             repercussions.
97              
98             Unfortunately, the API for v2.0.0 is not backwards compatible with previous versions (but
99             previous I is). You will probably need to make two changes:
100              
101             =over
102              
103             =item *
104              
105             In your applications, change the lines instantiating a C object to include
106             the name of the backend:
107              
108             my $pye = Pye->new('MongoDB', %options);
109              
110             Alternatively, replace C with C and call:
111              
112             my $pye = Pye::MongoDB->new(%options);
113              
114             Also, in C<%options>, the C option was renamed C, and C was
115             renamed C (or C, both are supported).
116              
117             =item *
118              
119             The options for the L command line utility have changed. You will now need to provide
120             a C<-b|--backend> option (with "MongoDB" as the value), and instead of C<-l|--log_coll>
121             you need to provide C<-c|--collection>. Since the session collection
122             has been deprecated, the C<-s|--session_coll> option has been removed, and now C<-s>
123             is an alias for C<-S|--session_id>.
124              
125             =back
126              
127             Also note the following dependency changes:
128              
129             =over
130              
131             =item * L instead of L
132              
133             =item * L instead of L
134              
135             =back
136              
137             =cut
138              
139             =head1 CONSTRUCTOR
140              
141             =head2 new( $backend, [ %options ] )
142              
143             This is a convenience constructor to easily load a C backend and
144             create a new instance of it. C will load the C<$backend> supplied,
145             and pass C<%options> (if any) to its own constructor.
146              
147             If you're writing your own backend which is not under the C namespace,
148             prefix it with a plus sign, otherwise C will not find it.
149              
150             =cut
151              
152              
153             sub new {
154 0     0 1   my ($self, $backend, %options) = @_;
155              
156 0 0         if ($backend =~ m/^\+/) {
    0          
157 0           $backend = $';
158             } elsif ($backend !~ m/^Pye::/) {
159 0           $backend = 'Pye::'.$backend;
160             }
161              
162 0           eval "require $backend";
163              
164 0 0         if ($@) {
165 0           croak "Can't load Pye backend $backend: $@";
166             }
167              
168 0           return $backend->new(%options);
169             }
170              
171             =head1 REQUIRED METHODS
172              
173             The following methods must be implemented by consuming classes:
174              
175             =head2 log( $session_id, $text, [ \%data ] )
176              
177             Log a new message, with text C<$text>, under session ID C<$session_id>.
178             An optional reference can also be supplied and stored with the message.
179              
180             =head2 session_log( $session_id )
181              
182             Returns a list of all messages stored under session ID C<$session_id>.
183             Every item in the array is a hash-ref with the following keys: C,
184             C in (YYYY-MM-DD format), C
185             and possibly C.
186              
187             =head2 list_sessions( [ \%options ] )
188              
189             Returns a list of sessions in the log, based on the provided options. If no
190             options are provided, the latest 10 sessions should be returned. The following options
191             are supported:
192              
193             =over
194              
195             =item * sort - how to sort sessions (every backend will accept a different value;
196             defaults to descending order by C)
197              
198             =item * skip - after sorting, skip a number of sessions (defaults to 0)
199              
200             =item * limit - limit the number of sessions returned (defaults to 10)
201              
202             =back
203              
204             Every item (i.e. session) in the list should be a hash-ref with the keys C,
205             C (in YYYY-MM-DD format) and C
206              
207             =head2 _remove_session_logs( $session_id )
208              
209             Removes all messages for a specific session.
210              
211             =cut
212              
213             requires qw/log session_log list_sessions _remove_session_logs/;
214              
215             =head1 CONFIGURATION AND ENVIRONMENT
216            
217             C requires no configuration files or environment variables.
218              
219             =head1 DEPENDENCIES
220              
221             C depends on the following CPAN modules:
222              
223             =over
224              
225             =item * L
226              
227             =item * L
228              
229             =back
230              
231             The command line utility, L, depends on:
232              
233             =over
234              
235             =item * L
236              
237             =item * L
238              
239             =item * L
240              
241             =item * L
242              
243             =back
244              
245             It is recommended to install L is recommended
246             for fast JSON (de)serialization.
247              
248             =head1 BUGS AND LIMITATIONS
249              
250             Please report any bugs or feature requests to
251             C, or through the web interface at
252             L.
253              
254             =head1 SUPPORT
255              
256             You can find documentation for this module with the perldoc command.
257              
258             perldoc Pye
259              
260             You can also look for information at:
261              
262             =over 4
263            
264             =item * RT: CPAN's request tracker
265            
266             L
267            
268             =item * AnnoCPAN: Annotated CPAN documentation
269            
270             L
271            
272             =item * CPAN Ratings
273            
274             L
275            
276             =item * Search CPAN
277            
278             L
279            
280             =back
281            
282             =head1 AUTHOR
283            
284             Ido Perlmuter
285            
286             =head1 LICENSE AND COPYRIGHT
287            
288             Copyright (c) 2013-2015, Ido Perlmuter C<< ido@ido50.net >>.
289              
290             This module is free software; you can redistribute it and/or
291             modify it under the same terms as Perl itself, either version
292             5.8.1 or any later version. See L
293             and L.
294            
295             The full text of the license can be found in the
296             LICENSE file included with this module.
297            
298             =head1 DISCLAIMER OF WARRANTY
299            
300             BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
301             FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
302             OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
303             PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
304             EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
305             WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
306             ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
307             YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
308             NECESSARY SERVICING, REPAIR, OR CORRECTION.
309            
310             IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
311             WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
312             REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
313             LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
314             OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
315             THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
316             RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
317             FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
318             SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
319             SUCH DAMAGES.
320              
321             =cut
322              
323             1;
324             __END__