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

package Pye;

# ABSTRACT: Session-based logging platform on top of SQL/NoSQL databases

14928

use Carp;

1307

use Role::Tiny;

4744

our $VERSION = "2.000001";

$VERSION = eval $VERSION;

=head1 NAME

Pye - Session-based logging platform on top of SQL/NoSQL databases

=head1 SYNOPSIS

use Pye;

# start logging on top of a certain backend, say Pye::MongoDB

# (you can also call new() directly on the backend class, check

# out the documentation of the specific backend)

my $pye = Pye->new('MongoDB',

host => 'mongodb://logserver:27017',

database => 'log_db',

collection => 'myapp_log'

);

# if you've created your own backend, prefix it with a plus sign

my $pye = Pye->new('+My::Pye::Backend', \%options);

# now start logging

$pye->log($session_id, "Some log message", { data => 'example data' });

=head1 DESCRIPTION

C is a dead-simple, session-based logging platform where all logs are stored

in a database. Log messages in C include a date, a text message, and possibly

a data structure (hash/array-ref) that "illustrates" the text.

I built C due to my frustration with file-based loggers that generate logs that

are extremely difficult to read, analyze and maintain.

C is most useful for services (e.g. web apps) that handle requests,

or otherwise work in sessions, but can be useful in virtually any application,

including automatic (e.g. cron) scripts.

In order to use C, your program must define an ID for every session. "Session"

can really mean anything here: a client session in a web service, a request to your

web service, an execution of a script, whatever. As long as a unique ID can be generated,

C can handle logging for you.

Main features:

=over

=item * B

With C, any complex data structure (i.e. hash/array) can be attached to any log message,

enabling you to illustrate a situation, display complex data, etc.

=item * B

Yeah, I consider this a feature. Log levels are a bother, and I don't need them. All log

messages in C are saved into the database, nothing gets lost.

=item * B

C comes with a command line utility, L, that offers quick inspection of the log.

You can easily view a list of current/latest sessions and read the log of a specific session.

No more mucking about through endless log files, trying to understand which lines belong to which

session, or trying to find that area of the file with messages from that certain date your software

died on.

=item * B

C supports several database backends. Currently, L supports MongoDB, and

L supports MySQL, PostgreSQL and SQLite.

=back

This package provides two purposes. It provides a constructor that dynamically loads the

requested backend class and creates an object of it. It is also a role (with L)

detailing methods backend classes are required to implement.

=head2 UPGRADING TO v2.0.0 AND UP

Originally, C was purely a MongoDB logging system, and this module provided the

MongoDB functionality. Since v2.0.0, C became a system with pluggable backends, and

the MongoDB functionality was moved to L (not provided by this distribution,

so you should install that too if you've been using Pye before v2.0.0).

An improvement over v1.*.* was also introduced: before, every application had two collections

in the database - a log collection and a session collection. The session collection is not

needed anymore. You can remove these session collections from your current database with no

repercussions.

Unfortunately, the API for v2.0.0 is not backwards compatible with previous versions (but

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 (in HH:MM:SS.SSS 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 (in HH:MM:SS.SSS format).
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__