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

Server Logging Methods

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

Request Logging Methods

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

Other Logging Methods

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

General Functions

462       "LOG_MARK"
463
464       Though looking like a constant, this is a function, which returns a
465       list of two items: "(__FILE__, __LINE__)", i.e. the file and the line
466       where the function was called from.
467
468         my ($file, $line) = Apache2::Log::LOG_MARK();
469
470       ret1: $file ( string )
471       ret2: $line ( number )
472       since: 2.0.00
473
474       It's mostly useful to be passed as the first argument to those logging
475       methods, expecting the filename and the line number as the first argu‐
476       ments (e.g., "$s->log_serror" and "$r->log_rerror" ).
477

Virtual Hosts

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

Unsupported API

551       "Apache2::Log" also provides auto-generated Perl interface for a few
552       other methods which aren't tested at the moment and therefore their API
553       is a subject to change. These methods will be finalized later as a need
554       arises. If you want to rely on any of the following methods please con‐
555       tact the the mod_perl development mailing list so we can help each
556       other take the steps necessary to shift the method to an officially
557       supported API.
558
559       "log_pid"
560
561       META: what is this method good for? it just calls getpid and logs it.
562       In any case it has nothing to do with the logging API. And it uses
563       static variables, it probably shouldn't be in the Apache public API.
564
565       Log the current pid
566
567         Apache2::Log::log_pid($pool, $fname);
568
569       obj: $p ( "APR::Pool object" )
570           The pool to use for logging
571
572       arg1: $fname ( file path )
573           The name of the file to log to
574
575       ret: no return value
576       since: subject to change
577

Copyright

582       mod_perl 2.0 and its core modules are copyrighted under The Apache
583       Software License, Version 2.0.
584

Authors

586       The mod_perl development team and numerous contributors.
587
588
589
590perl v5.8.8                       2006-11-28        docs::api::Apache2::Log(3)