MojoX::Log::Log4perl(3pm)

1MojoX::Log::Log4perl(3)User Contributed Perl DocumentatioMnojoX::Log::Log4perl(3)
2
3
4

NAME

6       MojoX::Log::Log4perl - Log::Log4perl logging for Mojo/Mojolicious
7

SYNOPSIS

9       In lib/MyApp.pm:
10
11         use MojoX::Log::Log4perl;
12
13         # just create a custom logger object for Mojo/Mojolicious to use
14         # (this is usually done inside the "startup" sub on Mojolicious).
15         # If we dont supply any arguments to new, it will work almost
16         # like the default Mojo logger.
17
18         $self->log( MojoX::Log::Log4perl->new() );
19
20         # But the real power of Log4perl lies in the configuration, so
21         # lets try that. example.conf is included in the distribution.
22
23         $self->log( MojoX::Log::Log4perl->new('example.conf') );
24
25         # you can even make it periodically check for changes in the
26         # configuration file and automatically reload them while your
27         # app is still running!
28
29         # check for changes every 10 seconds
30         $self->log( MojoX::Log::Log4perl->new('example.conf', 10)    );
31
32         # or check for changes only upon receiving SIGHUP
33         $self->log( MojoX::Log::Log4perl->new('example.conf', 'HUP') );
34
35       And later, inside any Mojo/Mojolicious module...
36
37         $c->app->log->debug("This is using log4perl!");
38

DESCRIPTION:

40       This module provides a Mojo::Log implementation that uses Log::Log4perl
41       as the underlying log mechanism. It provides all the methods listed in
42       Mojo::Log (and many more from Log4perl - see below), so, if you already
43       use Mojo::Log in your application, there is no need to change a single
44       line of code!
45
46       There will be a logger component set for the package that called it.
47       For example, if you were in the MyApp::Main package, the following:
48
49         package MyApp::Main;
50         use base 'Mojolicious::Controller';
51
52         sub default {
53             my ( $self, $c ) = @_;
54             my $logger = $c->app->log;
55
56             $logger->debug("Woot!");
57         }
58
59       Would send a message to the "Myapp.Main" Log4perl component. This
60       allows you to seamlessly use Log4perl with Mojo/Mojolicious
61       applications, being able to setup everything from the configuration
62       file. For example, in this case, we could have the following
63       "log4perl.conf" file:
64
65         # setup default log level and appender
66         log4perl.rootLogger = DEBUG, FOO
67         log4perl.appender.FOO = Log::Log4perl::Appender::File
68         log4perl.appender.FOO.layout
69
70         # setup so MyApp::Main only logs fatal errors
71         log4perl.logger.MyApp.Main = FATAL
72
73       See Log::Log4perl and Log::Log4perl::Config for more information on how
74       to configure different logging mechanisms based on the component.
75

INSTANTIATION

77   new
78   new($config)
79       This builds a new MojoX::Log::Log4perl object. If you provide an
80       argument to new(), it will be passed directly to Log::Log4perl::init.
81
82       What you usually do is pass a file name with your Log4perl
83       configuration. But you can also pass a hash reference with keys and
84       values set as Log4perl configuration elements (i.e. left side of '='
85       vs. right side).
86
87       If you don't give it any arguments, the following default configuration
88       is set:
89
90         log4perl.rootLogger = DEBUG, SCREEN
91         log4perl.appender.SCREEN = Log::Log4perl::Appender::Screen
92         log4perl.appender.SCREEN.layout = PatternLayout
93         log4perl.appender.SCREEN.layout.ConversionPattern = [%d] [mojo] [%p] %m%n
94
95   new( $config, $delay )
96       As an optional second argument to new(), you can set a delay in seconds
97       that will be passed directly to Log::Log4perl::init_and_watch. This
98       makes Log4perl check every $delay seconds for changes in the
99       configuration file, and reload it if the file modification time is
100       different.
101
102       You can also define a signal to watch and Log4perl will setup a signal
103       handler to check the configuration file again only when that particular
104       signal is received by the application, for example via the "kill"
105       command:
106
107         kill -HUP pid
108

LOG LEVELS

110         $logger->warn("something's wrong");
111
112       Below are all log levels from MojoX::Log::Log4perl, in descending
113       priority:
114
115   "fatal"
116   "error"
117   "warn"
118   "info"
119   "debug"
120   "trace"
121       Just like "Log::Log4perl": "If your configured logging level is WARN,
122       then messages logged with info(), debug(), and trace() will be
123       suppressed. fatal(), error() and warn() will make their way through,
124       because their priority is higher or equal than the configured setting."
125
126       The return value is the log object itself, to allow method chaining and
127       further manipulation.
128
129   "log"
130       You can also use the log() method just like in "Mojo::Log":
131
132         $logger->log( info => 'I can haz cheezburger');
133
134       But nobody does that, really.
135
136       As with the regular logging methods, the return value is the log object
137       itself.
138

CHECKING LOG LEVELS

140         if ($logger->is_debug) {
141             # expensive debug here
142         }
143
144       As usual, you can (and should) avoid doing expensive log calls by
145       checking the current log level:
146
147   "is_fatal"
148   "is_error"
149   "is_warn"
150   "is_info"
151   "is_debug"
152   "is_trace"
153   "is_level"
154       You can also use the is_level() method just like in "Mojo::Log":
155
156         $logger->is_level( 'warn' );
157
158       But nobody does that, really.
159

ADDITIONAL LOGGING METHODS

161       The following log4perl methods are also available for direct usage:
162
163   "logwarn"
164          $logger->logwarn($message);
165
166       This will behave just like:
167
168          $logger->warn($message)
169              && warn $message;
170
171   "logdie"
172          $logger->logdie($message);
173
174       This will behave just like:
175
176          $logger->fatal($message)
177              && die $message;
178
179       If you also wish to use the ERROR log level with warn() and die(), you
180       can:
181
182   "error_warn"
183          $logger->error_warn($message);
184
185       This will behave just like:
186
187          $logger->error($message)
188              && warn $message;
189
190   "error_die"
191          $logger->error_die($message);
192
193       This will behave just like:
194
195          $logger->error($message)
196              && die $message;
197
198       Finally, there's the Carp functions that do just what the Carp
199       functions do, but with logging:
200
201   "logcarp"
202           $logger->logcarp();        # warn w/ 1-level stack trace
203
204   "logcluck"
205           $logger->logcluck();       # warn w/ full stack trace
206
207   "logcroak"
208           $logger->logcroak();       # die w/ 1-level stack trace
209
210   "logconfess"
211           $logger->logconfess();     # die w/ full stack trace
212

ATTRIBUTES

214   Differences from Mojo::Log
215       The original "handle" and "path" attributes from "Mojo::Log" are not
216       implemented as they make little sense in a Log4perl environment, and
217       will trigger a warning if you try to use them.
218
219       The "format" attribute is also not implemented, and will trigger a
220       warning when used. For compatibility with Mojolicious' current 404
221       development page, this attribute will work returning a basic formatted
222       message as "[ date ] [ level ] message". We do not recommend you to
223       rely on this as we may remove it in the future. Please use Log4perl's
224       layout formatters instead.
225
226       The following attributes are still available:
227
228   "level"
229         my $level = $logger->level();
230
231       This will return an UPPERCASED string with the current log level
232       ('DEBUG', 'INFO', ...).
233
234       Note: You can also use this to force a level of your choosing:
235
236         $logger->level('warn');  # forces 'warn' level (case-insensitive)
237
238       But you really shouldn't do that at all, as it breaks log4perl's
239       configuration structure. The whole point of Log4perl is letting you
240       setup your logging from outside your code. So, once again: don't do
241       this.
242
243   "history"
244       This returns the last few logged messages as an array reference in the
245       format:
246
247           [
248               [ 'timestamp', 'level', 'message' ], # older first
249               [ 'timestamp', 'level', 'message' ],
250               ...
251           ]
252
253   "max_history_size"
254       Maximum number of messages to be kept in the history buffer (see
255       above). Defaults to 10.
256

AUTHOR

258       Breno G. de Oliveira, "<garu at cpan.org>"
259

BUGS

261       Please report any bugs or feature requests to "bug-mojo-log-log4perl at
262       rt.cpan.org", or through the web interface at
263       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MojoX-Log-Log4perl>.  I
264       will be notified, and then you'll automatically be notified of progress
265       on your bug as I make changes.
266

SUPPORT

268       You can find documentation for this module with the perldoc command.
269
270           perldoc MojoX::Log::Log4perl
271
272       You can also look for information at:
273
274       •   RT: CPAN's request tracker
275
276           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=MojoX-Log-Log4perl>
277
278       •   AnnoCPAN: Annotated CPAN documentation
279
280           <http://annocpan.org/dist/MojoX-Log-Log4perl>
281
282       •   CPAN Ratings
283
284           <http://cpanratings.perl.org/d/MojoX-Log-Log4perl>
285
286       •   Search CPAN
287
288           <http://search.cpan.org/dist/MojoX-Log-Log4perl/>
289

ACKNOWLEDGEMENTS

291       This module was heavily inspired by Catalyst::Log::Log4perl. A lot of
292       the documentation and specifications were taken almost verbatim from
293       it.
294
295       Also, this is just a minor work. Credit is really due to Michael
296       Schilli and Sebastian Riedel, creators and maintainers of Log::Log4perl
297       and Mojo, respectively.
298

COPYRIGHT & LICENSE

303       Copyright 2009-2019 Breno G. de Oliveira, all rights reserved.
304
305       This program is free software; you can redistribute it and/or modify it
306       under the same terms as Perl itself.
307
308
309
310perl v5.36.0                      2023-01-20           MojoX::Log::Log4perl(3)