=head1 NAME

Leyland::Manual::Logging - How to use a log in Leyland applications

=head1 VERSION

version 0.001007

=head1 LOGGING

Logging is an important aspect of any web application, at least in my
opinion. There are quite a lot of options on CPAN for logging, such as
L<Log::Dispatch>, L<Log::Handler> (my favorite), L<Log::Log4perl> and many
others (not to mention plain old C<print STDERR $log_msg>).

Leyland gives you the ability to choose which logging platform to use.
Currently, Log::Dispatch and Log::Handler are supported, plus a default
platform that simply logs to the standard error output.

=head1 SELECTING A LOG CLASS

You tell Leyland which platform to use with the "logger" option in your
application's C<$config> variable (see L<Leyland::Manual::Applications/"CONFIGURING LEYLAND APPLICATIONS">
for more info). The "logger" option is expected to be a hash-ref with
two keys: "class", which defines the log class to use, and "opts", which
is a hash-ref of options that are specific to the log class chosen.

The three current log classes are L<LogDispatch|Leyland::Logger::LogDispatch>,
L<LogHandler|Leyland::Logger::LogHandler> and L<STDERR|Leyland::Logger::STDERR>
(the latter takes no arguments and is the default, so there's no need
to define it if you want to use it). Refer to the documentation of the
log class of your choice to learn about how to configure it. Here's a
Log::Dispatch example:

	# in app.psgi
	my $config = {
		...
		logger => {
			class => 'LogDispatch',
			opts => {
				outputs => [
					[ 'File',   min_level => 'debug', filename => "myapp.$ENV{PLACK_ENV}.log", newline => 1 ],
					[ 'Screen', min_level => 'warning', newline => 1 ],
				],
			}
		},
		...
	};

As you can see, we are telling leyland that our log class is going to be
L<Leyland::Logger::LogDispatch>, and that we want our log messages to be
printed to the screen, and also to a file.

=head1 PRINTING LOG MESSAGES

As you may already know, when using logging platforms, every log message
you print is assigned a log level, which denotes the severity of the message.
Common levels are "info", "warn" and "error". Unfortunately, different
log classes have different log levels, so Leyland only supports levels
which are common to all classes. These are "info", "warn", "error" and
"debug".

Once initialized, a log object will be available both to your application
object and also to every context object:

	get '^/$' {
		$c->log->info("Got a request to display the index page");
		$c->template('index.html');
	}

And that's pretty much it.

=head1 BUT WAIT, WHY NOT USE PLACK'S LOG MIDDLEWARES?

See L<Leyland::Manual::FAQ/"WHY AREN'T YOU USING PLACK'S LOGGING MIDDLEWARES?">
for the answer.

=head1 WHAT'S NEXT?

Read L<Leyland::Manual::Exceptions> to learn how to return proper HTTP
exceptions or L<return to the table of contents|Leyland::Manual/"TABLE OF CONTENTS">.

=head1 AUTHOR

Ido Perlmuter, C<< <ido at ido50.net> >>

=head1 BUGS

Please report any bugs or feature requests to C<bug-Leyland at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Leyland>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

	perldoc Leyland::Manual::Views

You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Leyland>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Leyland>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Leyland>

=item * Search CPAN

L<http://search.cpan.org/dist/Leyland/>

=back

=head1 LICENSE AND COPYRIGHT

Copyright 2010-2011 Ido Perlmuter.

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

=cut
