perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/api/Apache Log.pod
Date Fri, 17 Sep 2004 00:00:34 GMT
stas        2004/09/16 17:00:34

  Modified:    src/docs/2.0/api/Apache Log.pod
  Log:
  logging API sync
  
  Revision  Changes    Path
  1.15      +138 -14   modperl-docs/src/docs/2.0/api/Apache/Log.pod
  
  Index: Log.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Log.pod,v
  retrieving revision 1.14
  retrieving revision 1.15
  diff -u -u -r1.14 -r1.15
  --- Log.pod	23 Aug 2004 18:51:49 -0000	1.14
  +++ Log.pod	17 Sep 2004 00:00:34 -0000	1.15
  @@ -23,9 +23,7 @@
                    APR::ENOTIME, "debug print");
     Apache::ServerRec->log_error("routine warning");
     
  -  Apache->warn("routine warning");
  -  Apache::warn("routine warning");
  -  Apache::ServerRec->warn("routine warning");
  +  Apache::ServerRec::warn("routine warning");
   
     #in a handler
     #------------
  @@ -62,6 +60,7 @@
         $s->log_serror(Apache::Log::LOG_MARK, Apache::LOG_ERR,
                        APR::ENOTIME, "fatal error");
   
  +      $r->warn('routine request warning');
         $s->warn('routine server warning');
   
         return Apache::OK;
  @@ -338,9 +337,38 @@
   
   =item since: 1.99_12
   
  +=back
  +
  +
  +
  +=head2 C<$s-E<gt>warn>
  +
  +  $s->warn(@warnings);
  +
  +is the same as:
  +
  +  $s->log_error(Apache::Log::LOG_MARK, Apache::LOG_WARNING,
  +                APR::SUCCESS, @warnings)
  +
  +=over 4
  +
  +=item obj: C<$s>
  +( C<L<Apache::ServerRec object|docs::2.0::api::Apache::ServerRec>> )
  +
  +=item arg1: C<@warnings> ( strings ARRAY )
  +
  +array of warning strings
  +
  +=item ret: no return value
  +
  +=item since: 1.99_12
   
   =back
   
  +For example:
  +
  +  $s->warn('routine server warning');
  +
   
   
   
  @@ -438,6 +466,37 @@
   
   
   
  +=head2 C<$r-E<gt>warn>
  +
  +  $r->warn(@warnings);
  +
  +is the same as:
  +
  +  $r->log_error(Apache::Log::LOG_MARK, Apache::LOG_WARNING,
  +                APR::SUCCESS, @warnings)
  +
  +=over 4
  +
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
  +
  +=item arg1: C<@warnings> ( strings ARRAY )
  +
  +array of warning strings
  +
  +=item ret: no return value
  +
  +=item since: 1.99_17
  +
  +=back
  +
  +For example:
  +
  +  $r->warn('routine server warning');
  +
  +
  +
  +
   
   
   
  @@ -565,28 +624,93 @@
   
   
   
  +=head1 Virtual Hosts
   
  +Code running from within a virtual host needs to be able to log into
  +its C<ErrorLog> file, if different from the main log. Calling any of
  +the logging methods on the C<$r> and C<$s> objects will do the logging
  +correctly.
   
  -=head1 Aliases
  +If the core C<warn()> is called, it'll be always logged to the main
  +log file. Here is how to make it log into the vhost F<error_log> file.
  +Let's say that we start with the following code:
   
  -=head2 C<$s-E<gt>warn>
  +  warn "the code is smoking";
   
  -  $s->warn(@warnings);
  +=over
   
  -is the same as:
  +=item 1
   
  -  $s->log_error(Apache::Log::LOG_MARK, Apache::LOG_WARNING,
  -                APR::SUCCESS, @warnings)
  +First, we need to use mod_perl's logging function, instead of
  +C<CORE::warn>
   
  -For example:
  +Either replace C<warn> with C<Apache::ServerRec::warn>:
   
  -  $s->warn('routine server warning');
  +  use Apache::Log ();
  +  Apache::ServerRec::warn("the code is smoking");
  +
  +or import it into your code:
  +
  +  use Apache::ServerRec qw(warn); # override warn locally
  +  warn "the code is smoking";
  +
  +or override C<CORE::warn>:
  +
  +  use Apache::Log ();
  +  *CORE::GLOBAL::warn = \&Apache::ServerRec::warn;
  +  warn "the code is smoking";
  +
  +Avoid using the latter suggestion, since it'll affect all the code
  +running on the server, which may break things. Of course you can
  +localize that as well:
  +
  +  use Apache::Log ();
  +  local *CORE::GLOBAL::warn = \&Apache::ServerRec::warn;
  +  warn "the code is smoking";
  +
  +Chances are that you need to make the internal Perl warnings go into
  +the vhost's F<error_log> file as well. Here is how to do that:
  +
  +  use Apache::Log ();
  +  local $SIG{__WARN__} = \&Apache::ServerRec::warn;
  +  eval q[my $x = "aaa" + 1;]; # this issues a warning
  +
  +Notice that it'll override any previous setting you may have had,
  +disabling modules like C<CGI::Carp> which also use C<$SIG{__WARN__}>
  +
  +=item 2
  +
  +Next we need to figure out how to get hold of the vhost's server
  +object.
  +
  +Inside HTTP request handlers this is possible via
  +C<Apache-E<gt>request|docs::2.0::api::Apache::RequestUtil/C_request_>. Which
  +requires either C<L<PerlOptions
  ++GlobalRequest|docs::2.0::user::config::config/C_GlobalRequest_>>
  +setting or can be also done at runtime if C<$r> is available:
  +
  +  use Apache::RequestUtil ();
  +  sub handler {
  +      my $r = shift;
  +      Apache->request($r);
  +      ...
  +
  +Outside HTTP handlers at the moment it is not possible, to get hold of
  +the vhost's F<error_log> file. This shouldn't be a problem for the
  +code that runs only under mod_perl, since the always available C<$s>
  +object can invoke a plethora of methods supplied by
  +C<Apache::Log>. This is only a problem for modules, which are supposed
  +to run outside mod_perl as well.
  +
  +META: To solve this we think to introduce 'PerlOptions +GlobalServer',
  +a big brother for 'PerlOptions +GlobalRequest', which will be set in
  +modperl_hook_pre_connection.
  +
  +
  +=back
   
  -=head2 C<Apache-E<gt>warn>
   
  -=head2 C<Apache::warn>
   
  -  Apache->warn(@warnings);
   
   
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message