1Catalyst(3) User Contributed Perl Documentation Catalyst(3)
2
6 Log::Log4perl::Catalyst - Log::Log4perl Catalyst Module
7
9 In your main Catalyst application module:
10 use Log::Log4perl::Catalyst;
12 # Either make Log4perl act like the Catalyst default logger:
14 __PACKAGE__->log(Log::Log4perl::Catalyst->new());
15 # or use a Log4perl configuration file, utilizing the full
17 # functionality of Log4perl
18 __PACKAGE__->log(Log::Log4perl::Catalyst->new('l4p.conf'));
19 ... and then sprinkle logging statements all over any code executed by
21 Catalyst:
22 $c->log->debug("This is using log4perl!");
24
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 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 package MyApp::Controller::User;
36 sub add : Chained('base'): PathPart('add'): Args(0) {
38 my ( $self, $c ) = @_;
39 $c->log->info("Adding a user");
41 # ...
42 }
43 Level-based control is available via the following methods:
45 $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 But that's not all, Log4perl is much more powerful.
53 The logging statement can be suppressed or activated based on a
55 Log4perl file that looks like
56 # All MyApp loggers opened up for DEBUG and above
58 log4perl.logger.MyApp = DEBUG, Screen
59 # ...
60 or
62 # All loggers block messages below INFO
64 log4perl.logger=INFO, Screen
65 # ...
66 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 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 # Log4perl configuration file
77 # ...
78 log4perl.appender.Screen.layout.ConversionPattern = \
79 %F{1}-%L: %p %m%n
80 Messages will then look like
82 MyApp.pm-1869: INFO Saving user profile for user "wonko"
84 Or want to log a request's IP address with every log statement? No
86 problem with Log4perl, just call
87 Log::Log4perl::MDC->put( "ip", $c->req->address() );
89 at the beginning of the request cycle and use
91 # Log4perl configuration file
93 # ...
94 log4perl.appender.Screen.layout.ConversionPattern = \
95 [%d]-%X{ip} %F{1}-%L: %p %m%n
96 as a Log4perl layout. Messages will look like
98 [2010/02/22 23:25:55]-123.122.108.10 MyApp.pm-1953: INFO Reading profile for user "wonko"
100 Again, check the Log4perl manual page, there's a plethora of
102 configuration options.
103
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 The second (optional) parameter is a list of key/value pairs:
113 'autoflush' => 1 # Log without buffering ('abort' not supported)
115 'watch_delay' => 30 # If set, use L<Log::Log4perl>'s init_and_watch
116 _flush()
118 Flushes the cache.
119 abort($abort)
121 Clears the logging system's internal buffers without logging
122 anything.
123 Using :easy Macros with Catalyst
125 If you're tired of typing
126 $c->log->debug("...");
128 and would prefer to use Log4perl's convenient :easy mode macros like
130 DEBUG "...";
132 then just pull those macros in via Log::Log4perl's :easy mode and start
134 cranking:
135 use Log::Log4perl qw(:easy);
137 # ... use macros later on
139 sub base :Chained('/') :PathPart('apples') :CaptureArgs(0) {
140 my ( $self, $c ) = @_;
141 DEBUG "Handling apples";
143 }
144 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 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
159 Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
160 <cpan@goess.org>.
161 This library is free software; you can redistribute it and/or modify it
163 under the same terms as Perl itself.
164
166 Please contribute patches to the project on Github:
167 http://github.com/mschilli/log4perl
169 Send bug reports or requests for enhancements to the authors via our
171 MAILING LIST (questions, bug reports, suggestions/patches):
173 log4perl-devel@lists.sourceforge.net
174 Authors (please contact them via the list above, not directly): Mike
176 Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
177 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.
185perl v5.32.0 2020-09-07 Catalyst(3)