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 sprinkly 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 no 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 vary the layout of each message. For example if you want
73       to 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 similiarly to Catalyst's default
108           logging mechanism. If you provide configuration, either the name of
109           a configuration file or a reference to 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

159       Copyright 2002-2010 by Mike Schilli <m@perlmeister.com>
160
161       This library is free software; you can redistribute it and/or modify it
162       under the same terms as Perl itself.
163
164
165
166perl v5.12.2                      2010-08-31                       Catalyst(3)
Impressum