Apache2::Log(3pm)

1docs::api::Apache2::LogU(s3e)r Contributed Perl Documentadtoicosn::api::Apache2::Log(3)
2
3
4

NAME

6       Apache2::Log - Perl API for Apache Logging Methods
7

Synopsis

9         # in startup.pl
10         #--------------
11         use Apache2::Log;
12
13         use Apache2::Const -compile => qw(OK :log);
14         use APR::Const    -compile => qw(:error SUCCESS);
15
16         my $s = Apache2::ServerUtil->server;
17
18         $s->log_error("server: log_error");
19         $s->log_serror(__FILE__, __LINE__, Apache2::Const::LOG_ERR,
20                        APR::Const::SUCCESS, "log_serror logging at err level");
21         $s->log_serror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_DEBUG,
22                        APR::Const::ENOTIME, "debug print");
23         Apache2::ServerRec->log_error("routine warning");
24
25         Apache2::ServerRec::warn("routine warning");
26
27         # in a handler
28         #-------------
29         package Foo;
30
31         use strict;
32         use warnings FATAL => 'all';
33
34         use Apache2::Log;
35
36         use Apache2::Const -compile => qw(OK :log);
37         use APR::Const    -compile => qw(:error SUCCESS);
38
39         sub handler {
40             my $r = shift;
41             $r->log_error("request: log_error");
42
43             my $rlog = $r->log;
44             for my $level qw(emerg alert crit error warn notice info debug) {
45                 no strict 'refs';
46                 $rlog->$level($package, "request: $level log level");
47             }
48
49             # can use server methods as well
50             my $s = $r->server;
51             $s->log_error("server: log_error");
52
53             $r->log_rerror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_DEBUG,
54                            APR::Const::ENOTIME, "in debug");
55
56             $s->log_serror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_INFO,
57                            APR::Const::SUCCESS, "server info");
58
59             $s->log_serror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_ERR,
60                            APR::Const::ENOTIME, "fatal error");
61
62             $r->log_reason("fatal error");
63             $r->warn('routine request warning');
64             $s->warn('routine server warning');
65
66             return Apache2::Const::OK;
67         }
68         1;
69
70         # in a registry script
71         # httpd.conf: PerlOptions +GlobalRequest
72         use Apache2::ServerRec qw(warn); # override warn locally
73         print "Content-type: text/plain\n\n";
74         warn "my warning";
75

Description

77       "Apache2::Log" provides the Perl API for Apache logging methods.
78
79       Depending on the the current "LogLevel" setting, only logging with the
80       same log level or higher will be loaded. For example if the current
81       "LogLevel" is set to warning, only messages with log level of the level
82       warning or higher (err, crit, elert and emerg) will be logged.
83       Therefore this:
84
85         $r->log_rerror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_WARNING,
86                        APR::Const::ENOTIME, "warning!");
87
88       will log the message, but this one won't:
89
90         $r->log_rerror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_INFO,
91                        APR::Const::ENOTIME, "just an info");
92
93       It will be logged only if the server log level is set to info or debug.
94       "LogLevel" is set in the configuration file, but can be changed using
95       the "$s->loglevel()" method.
96
97       The filename and the line number of the caller are logged only if
98       "Apache2::Const::LOG_DEBUG" is used (because that's how Apache 2.0
99       logging mechanism works).
100
101       Note: On Win32 Apache attempts to lock all writes to a file whenever
102       it's opened for append (which is the case with logging functions), as
103       Unix has this behavior built-in, while Win32 does not. Therefore
104       "Apache2::Log" functions could be slower than Perl's print()/warn().
105

Constants

107       Log level constants can be compiled all at once:
108
109         use Apache2::Const -compile => qw(:log);
110
111       or individually:
112
113         use Apache2::Const -compile => qw(LOG_DEBUG LOG_INFO);
114
115   LogLevel Constants
116       The following constants (sorted from the most severe level to the least
117       severe) are used in logging methods to specify the log level at which
118       the message should be logged:
119
120       "Apache2::Const::LOG_EMERG"
121
122       "Apache2::Const::LOG_ALERT"
123
124       "Apache2::Const::LOG_CRIT"
125
126       "Apache2::Const::LOG_ERR"
127
128       "Apache2::Const::LOG_WARNING"
129
130       "Apache2::Const::LOG_NOTICE"
131
132       "Apache2::Const::LOG_INFO"
133
134       "Apache2::Const::LOG_DEBUG"
135
136   Other Constants
137       Make sure to compile the APR status constants before using them. For
138       example to compile "APR::Const::SUCCESS" and all the APR error status
139       constants do:
140
141         use APR::Const    -compile => qw(:error SUCCESS);
142
143       Here is the rest of the logging related constants:
144
145       "Apache2::Const::LOG_LEVELMASK"
146
147       used to mask off the level value, to make sure that the log level's
148       value is within the proper bits range. e.g.:
149
150         $loglevel &= LOG_LEVELMASK;
151
152       "Apache2::Const::LOG_TOCLIENT"
153
154       used to give content handlers the option of including the error text in
155       the "ErrorDocument" sent back to the client. When
156       "Apache2::Const::LOG_TOCLIENT" is passed to "log_rerror()" the error
157       message will be saved in the $r's notes table, keyed to the string
158       "error-notes", if and only if the severity level of the message is
159       "Apache2::Const::LOG_WARNING" or greater and there are no other "error-
160       notes" entry already set in the request record's notes table. Once the
161       "error-notes" entry is set, it is up to the error handler to determine
162       whether this text should be sent back to the client.  For example:
163
164         use Apache2::Const -compile => qw(:log);
165         use APR::Const    -compile => qw(ENOTIME);
166         $r->log_rerror(Apache2::Log::LOG_MARK,
167                        Apache2::Const::LOG_ERR|Apache2::Const::LOG_TOCLIENT,
168                        APR::Const::ENOTIME,
169                        "request log_rerror");
170
171       now the log message can be retrieved via:
172
173         $r->notes->get("error-notes");
174
175       Remember that client-generated text streams sent back to the client
176       MUST be escaped to prevent CSS attacks.
177
178       "Apache2::Const::LOG_STARTUP"
179
180       is useful for startup message where no timestamps, logging level is
181       wanted. For example:
182
183         use Apache2::Const -compile => qw(:log);
184         use APR::Const    -compile => qw(SUCCESS);
185         $s->log_serror(Apache2::Log::LOG_MARK,
186                        Apache2::Const::LOG_INFO,
187                        APR::Const::SUCCESS,
188                        "This log message comes with a header");
189
190       will print:
191
192         [Wed May 14 16:47:09 2003] [info] This log message comes with a header
193
194       whereas, when "Apache2::Const::LOG_STARTUP" is binary ORed as in:
195
196         use Apache2::Const -compile => qw(:log);
197         use APR::Const    -compile => qw(SUCCESS);
198         $s->log_serror(Apache2::Log::LOG_MARK,
199                        Apache2::Const::LOG_INFO|Apache2::Const::LOG_STARTUP,
200                        APR::Const::SUCCESS,
201                        "This log message comes with no header");
202
203       then the logging will be:
204
205         This log message comes with no header
206

Server Logging Methods

208   "$s->log"
209       get a log handle which can be used to log messages of different levels.
210
211         my $slog = $s->log;
212
213       obj: $s ( "Apache2::ServerRec object" )
214       ret: $slog ( "Apache2::Log::Server" object )
215           "Apache2::Log::Server" object to be used with LogLevel methods.
216
217       since: 2.0.00
218
219   "$s->log_error"
220       just logs the supplied message to error_log
221
222         $s->log_error(@message);
223
224       obj: $s ( "Apache2::ServerRec object" )
225       arg1: @message ( strings ARRAY )
226           what to log
227
228       ret: no return value
229       since: 2.0.00
230
231       For example:
232
233         $s->log_error("running low on memory");
234
235   "$s->log_serror"
236       This function provides a fine control of when the message is logged,
237       gives an access to built-in status codes.
238
239         $s->log_serror($file, $line, $level, $status, @message);
240
241       obj: $s ( "Apache2::ServerRec object" )
242       arg1: $file ( string )
243           The file in which this function is called
244
245       arg2: $line ( number )
246           The line number on which this function is called
247
248       arg3: $level ( "Apache2::LOG_* constant" )
249           The level of this error message
250
251       arg4: $status ( "APR::Const status constant" )
252           The status code from the last command (similar to $! in perl),
253           usually "APR::Const constant" or coming from an exception object.
254
255       arg5: @message ( strings ARRAY )
256           The log message(s)
257
258       ret: no return value
259       since: 2.0.00
260
261       For example:
262
263         use Apache2::Const -compile => qw(:log);
264         use APR::Const    -compile => qw(ENOTIME SUCCESS);
265         $s->log_serror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_ERR,
266                        APR::Const::SUCCESS, "log_serror logging at err level");
267
268         $s->log_serror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_DEBUG,
269                        APR::Const::ENOTIME, "debug print");
270
271   "$s->warn"
272         $s->warn(@warnings);
273
274       is the same as:
275
276         $s->log_serror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_WARNING,
277                        APR::Const::SUCCESS, @warnings)
278
279       obj: $s ( "Apache2::ServerRec object" )
280       arg1: @warnings ( strings ARRAY )
281           array of warning strings
282
283       ret: no return value
284       since: 2.0.00
285
286       For example:
287
288         $s->warn('routine server warning');
289

Request Logging Methods

291   "$r->log"
292       get a log handle which can be used to log messages of different levels.
293
294         $rlog = $r->log;
295
296       obj: $r ( "Apache2::RequestRec object" )
297       ret: $rlog ( "Apache2::Log::Request" object )
298           "Apache2::Log::Request" object to be used with LogLevel methods.
299
300       since: 2.0.00
301
302   "$r->log_error"
303       just logs the supplied message (similar to "$s->log_error" ).
304
305         $r->log_error(@message);
306
307       obj: $r ( "Apache2::RequestRec object" )
308       arg1: @message ( strings ARRAY )
309           what to log
310
311       ret: no return value
312       since: 2.0.00
313
314       For example:
315
316         $r->log_error("the request is about to end");
317
318   "$r->log_reason"
319       This function provides a convenient way to log errors in a preformatted
320       way:
321
322         $r->log_reason($message);
323         $r->log_reason($message, $filename);
324
325       obj: $r ( "Apache2::RequestRec object" )
326       arg1: $message ( string )
327           the message to log
328
329       opt arg2: $filename ( string )
330           where to report the error as coming from (e.g. "__FILE__")
331
332       ret: no return value
333       since: 2.0.00
334
335       For example:
336
337         $r->log_reason("There is no enough data");
338
339       will generate a log entry similar to the following:
340
341         [Fri Sep 24 11:58:36 2004] [error] access to /someuri
342         failed for 127.0.0.1, reason: There is no enough data.
343
344   "$r->log_rerror"
345       This function provides a fine control of when the message is logged,
346       gives an access to built-in status codes.
347
348         $r->log_rerror($file, $line, $level, $status, @message);
349
350       arguments are identical to "$s->log_serror".
351
352       since: 2.0.00
353
354       For example:
355
356         use Apache2::Const -compile => qw(:log);
357         use APR::Const    -compile => qw(ENOTIME SUCCESS);
358         $r->log_rerror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_ERR,
359                        APR::Const::SUCCESS, "log_rerror logging at err level");
360
361         $r->log_rerror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_DEBUG,
362                        APR::Const::ENOTIME, "debug print");
363
364   "$r->warn"
365         $r->warn(@warnings);
366
367       is the same as:
368
369         $r->log_rerror(Apache2::Log::LOG_MARK, Apache2::Const::LOG_WARNING,
370                        APR::Const::SUCCESS, @warnings)
371
372       obj: $r ( "Apache2::RequestRec object" )
373       arg1: @warnings ( strings ARRAY )
374           array of warning strings
375
376       ret: no return value
377       since: 2.0.00
378
379       For example:
380
381         $r->warn('routine server warning');
382

Other Logging Methods

384   LogLevel Methods
385       after getting the log handle with "$s->log" or "$r->log", use one of
386       the following methods (corresponding to the "LogLevel" levels):
387
388         emerg(), alert(), crit(), error(), warn(), notice(), info(), debug()
389
390       to control when messages should be logged:
391
392         $s->log->emerg(@message);
393         $r->log->emerg(@message);
394
395       obj: $slog ( server or request log handle )
396       arg1: @message ( strings ARRAY )
397       ret: no return value
398       since: 2.0.00
399
400       For example if the "LogLevel" is "error" and the following code is
401       executed:
402
403         my $slog = $s->log;
404         $slog->debug("just ", "some debug info");
405         $slog->warn(@warnings);
406         $slog->crit("dying");
407
408       only the last command's logging will be performed. This is because
409       warn, debug and other logging command which are listed right to error
410       will be disabled.
411
412   "alert"
413       See LogLevel Methods.
414
415   "crit"
416       See LogLevel Methods.
417
418   "debug"
419       See LogLevel Methods.
420
421   "emerg"
422       See LogLevel Methods.
423
424   "error"
425       See LogLevel Methods.
426
427   "info"
428       See LogLevel Methods.
429
430   "notice"
431       See LogLevel Methods.
432
433       Though Apache treats "notice()" calls as special. The message is always
434       logged regardless the value of "ErrorLog", unless the error log is set
435       to use syslog. (For details see httpd-2.0/server/log.c.)
436
437   "warn"
438       See LogLevel Methods.
439

General Functions

441   "LOG_MARK"
442       Though looking like a constant, this is a function, which returns a
443       list of two items: "(__FILE__, __LINE__)", i.e. the file and the line
444       where the function was called from.
445
446         my ($file, $line) = Apache2::Log::LOG_MARK();
447
448       ret1: $file ( string )
449       ret2: $line ( number )
450       since: 2.0.00
451
452       It's mostly useful to be passed as the first argument to those logging
453       methods, expecting the filename and the line number as the first
454       arguments (e.g., "$s->log_serror" and "$r->log_rerror" ).
455

Virtual Hosts

457       Code running from within a virtual host needs to be able to log into
458       its "ErrorLog" file, if different from the main log. Calling any of the
459       logging methods on the $r and $s objects will do the logging correctly.
460
461       If the core "warn()" is called, it'll be always logged to the main log
462       file. Here is how to make it log into the vhost error_log file.  Let's
463       say that we start with the following code:
464
465         warn "the code is smoking";
466
467       1.  First, we need to use mod_perl's logging function, instead of
468           "CORE::warn"
469
470           Either replace "warn" with "Apache2::ServerRec::warn":
471
472             use Apache2::Log ();
473             Apache2::ServerRec::warn("the code is smoking");
474
475           or import it into your code:
476
477             use Apache2::ServerRec qw(warn); # override warn locally
478             warn "the code is smoking";
479
480           or override "CORE::warn":
481
482             use Apache2::Log ();
483             *CORE::GLOBAL::warn = \&Apache2::ServerRec::warn;
484             warn "the code is smoking";
485
486           Avoid using the latter suggestion, since it'll affect all the code
487           running on the server, which may break things. Of course you can
488           localize that as well:
489
490             use Apache2::Log ();
491             local *CORE::GLOBAL::warn = \&Apache2::ServerRec::warn;
492             warn "the code is smoking";
493
494           Chances are that you need to make the internal Perl warnings go
495           into the vhost's error_log file as well. Here is how to do that:
496
497             use Apache2::Log ();
498             local $SIG{__WARN__} = \&Apache2::ServerRec::warn;
499             eval q[my $x = "aaa" + 1;]; # this issues a warning
500
501           Notice that it'll override any previous setting you may have had,
502           disabling modules like "CGI::Carp" which also use $SIG{__WARN__}
503
504       2.  Next we need to figure out how to get hold of the vhost's server
505           object.
506
507           Inside HTTP request handlers this is possible via
508           "Apache2->request".  Which requires either "PerlOptions
509           +GlobalRequest" setting or can be also done at runtime if $r is
510           available:
511
512             use Apache2::RequestUtil ();
513             sub handler {
514                 my $r = shift;
515                 Apache2::RequestUtil->request($r);
516                 ...
517
518           Outside HTTP handlers at the moment it is not possible, to get hold
519           of the vhost's error_log file. This shouldn't be a problem for the
520           code that runs only under mod_perl, since the always available $s
521           object can invoke a plethora of methods supplied by "Apache2::Log".
522           This is only a problem for modules, which are supposed to run
523           outside mod_perl as well.
524
525           META: To solve this we think to introduce 'PerlOptions
526           +GlobalServer', a big brother for 'PerlOptions +GlobalRequest',
527           which will be set in modperl_hook_pre_connection.
528

Unsupported API

530       "Apache2::Log" also provides auto-generated Perl interface for a few
531       other methods which aren't tested at the moment and therefore their API
532       is a subject to change. These methods will be finalized later as a need
533       arises. If you want to rely on any of the following methods please
534       contact the the mod_perl development mailing list so we can help each
535       other take the steps necessary to shift the method to an officially
536       supported API.
537
538   "log_pid"
539       META: what is this method good for? it just calls getpid and logs it.
540       In any case it has nothing to do with the logging API. And it uses
541       static variables, it probably shouldn't be in the Apache public API.
542
543       Log the current pid
544
545         Apache2::Log::log_pid($pool, $fname);
546
547       obj: $p ( "APR::Pool object" )
548           The pool to use for logging
549
550       arg1: $fname ( file path )
551           The name of the file to log to
552
553       ret: no return value
554       since: subject to change
555

Copyright

560       mod_perl 2.0 and its core modules are copyrighted under The Apache
561       Software License, Version 2.0.
562

Authors

564       The mod_perl development team and numerous contributors.
565
566
567
568perl v5.12.0                      2007-11-12        docs::api::Apache2::Log(3)