1Catalyst(3)           User Contributed Perl Documentation          Catalyst(3)
2
3
4

NAME

6       Log::Log4perl::Catalyst - Log::Log4perl Catalyst Module
7

SYNOPSIS

9       In your main Catalyst application module:
10
11         use Log::Log4perl::Catalyst;
12
13           # Either make Log4perl act like the Catalyst default logger:
14         __PACKAGE__->log(Log::Log4perl::Catalyst->new());
15
16           # or use a Log4perl configuration file, utilizing the full
17           # functionality of Log4perl
18         __PACKAGE__->log(Log::Log4perl::Catalyst->new('l4p.conf'));
19
20       ... and then sprinkle logging statements all over any code executed by
21       Catalyst:
22
23           $c->log->debug("This is using log4perl!");
24

DESCRIPTION

26       This module provides Log4perl functions to Catalyst applications. It
27       was inspired by Catalyst::Log::Log4perl on CPAN, but has been
28       completely rewritten and uses a different approach to unite Catalyst
29       and Log4perl.
30
31       Log4perl provides loggers, usually associated with the current package,
32       which can then be remote-controlled by a central configuration. This
33       means that if you have a controller function like
34
35           package MyApp::Controller::User;
36
37           sub add : Chained('base'): PathPart('add'): Args(0) {
38               my ( $self, $c ) = @_;
39
40               $c->log->info("Adding a user");
41               # ...
42           }
43
44       Level-based control is available via the following methods:
45
46          $c->log->debug("Reading configuration");
47          $c->log->info("Adding a user");
48          $c->log->warn("Can't read configuration ($!)");
49          $c->log->error("Can't add user ", $user);
50          $c->log->fatal("Database down, aborting request");
51
52       But that's not all, Log4perl is much more powerful.
53
54       The logging statement can be suppressed or activated based on a
55       Log4perl file that looks like
56
57             # All MyApp loggers opened up for DEBUG and above
58           log4perl.logger.MyApp = DEBUG, Screen
59           # ...
60
61       or
62
63             # All loggers block messages below INFO
64           log4perl.logger=INFO, Screen
65           # ...
66
67       respectively. See the Log4perl manpage on how to perform fine-grained
68       log-level and location filtering, and how to forward messages not only
69       to the screen or to log files, but also to databases, email appenders,
70       and much more.
71
72       Also, you can change the message layout. For example if you want to
73       know where a particular statement was logged, turn on file names and
74       line numbers:
75
76           # Log4perl configuration file
77           # ...
78           log4perl.appender.Screen.layout.ConversionPattern = \
79                 %F{1}-%L: %p %m%n
80
81       Messages will then look like
82
83           MyApp.pm-1869: INFO Saving user profile for user "wonko"
84
85       Or want to log a request's IP address with every log statement? No
86       problem with Log4perl, just call
87
88           Log::Log4perl::MDC->put( "ip", $c->req->address() );
89
90       at the beginning of the request cycle and use
91
92           # Log4perl configuration file
93           # ...
94           log4perl.appender.Screen.layout.ConversionPattern = \
95                 [%d]-%X{ip} %F{1}-%L: %p %m%n
96
97       as a Log4perl layout. Messages will look like
98
99           [2010/02/22 23:25:55]-123.122.108.10 MyApp.pm-1953: INFO Reading profile for user "wonko"
100
101       Again, check the Log4perl manual page, there's a plethora of
102       configuration options.
103

METHODS

105       new($config, [%options])
106           If called without parameters, new() initializes Log4perl in a way
107           so that messages are logged similarly to Catalyst's default logging
108           mechanism. If you provide a configuration, either the name of a
109           configuration file or a reference to a scalar string containing the
110           configuration, it will call Log4perl with these parameters.
111
112           The second (optional) parameter is a list of key/value pairs:
113
114             'autoflush'   =>  1   # Log without buffering ('abort' not supported)
115             'watch_delay' => 30   # If set, use L<Log::Log4perl>'s init_and_watch
116
117       _flush()
118           Flushes the cache.
119
120       abort($abort)
121           Clears the logging system's internal buffers without logging
122           anything.
123
124   Using :easy Macros with Catalyst
125       If you're tired of typing
126
127           $c->log->debug("...");
128
129       and would prefer to use Log4perl's convenient :easy mode macros like
130
131           DEBUG "...";
132
133       then just pull those macros in via Log::Log4perl's :easy mode and start
134       cranking:
135
136           use Log::Log4perl qw(:easy);
137
138             # ... use macros later on
139           sub base :Chained('/') :PathPart('apples') :CaptureArgs(0) {
140               my ( $self, $c ) = @_;
141
142               DEBUG "Handling apples";
143           }
144
145       Note the difference between Log4perl's initialization in Catalyst,
146       which uses the Catalyst-specific Log::Log4perl::Catalyst module (top of
147       this page), and making use of Log4perl's loggers with the standard
148       Log::Log4perl loggers and macros. While initialization requires
149       Log4perl to perform dark magic to conform to Catalyst's different
150       logging strategy, obtaining Log4perl's logger objects or calling its
151       macros are unchanged.
152
153       Instead of using Catalyst's way of referencing the "context" object $c
154       to obtain logger references via its log() method, you can just as well
155       use Log4perl's get_logger() or macros to access Log4perl's logger
156       singletons.  The result is the same.
157

LICENSE

159       Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
160       <cpan@goess.org>.
161
162       This library is free software; you can redistribute it and/or modify it
163       under the same terms as Perl itself.
164

AUTHOR

166       Please contribute patches to the project on Github:
167
168           http://github.com/mschilli/log4perl
169
170       Send bug reports or requests for enhancements to the authors via our
171
172       MAILING LIST (questions, bug reports, suggestions/patches):
173       log4perl-devel@lists.sourceforge.net
174
175       Authors (please contact them via the list above, not directly): Mike
176       Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
177
178       Contributors (in alphabetical order): Ateeq Altaf, Cory Bennett, Jens
179       Berthold, Jeremy Bopp, Hutton Davidson, Chris R. Donnelly, Matisse
180       Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon, Carl Franks, Dennis
181       Gregorovic, Andy Grundman, Paul Harrington, Alexander Hartmaier  David
182       Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter,
183       Brett Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, Lars
184       Thegler, David Viner, Mac Yang.
185
186
187
188perl v5.34.0                      2021-07-22                       Catalyst(3)
Impressum