Commit 2742ec22 authored by Stefan Fritsch's avatar Stefan Fritsch
Browse files

Add new non-default debugging module mod_log_debug 

It allows to log custom debug messages at various phases in the request
processing and is the first consumer of the new string-valued ap_expr API.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1142170 13f79535-47bb-0310-9956-ffa450edef68
parent 471fcda0

CHANGES

+3 −0
Original line number Diff line number Diff line
@@ -2,6 +2,9 @@ 


Changes with Apache 2.3.14



  *) mod_log_debug: New module that allows to log custom messages at various

     phases in the request processing. [Stefan Fritsch]



  *) mod_ssl: Add some debug logging when loading server certificates.

     PR 37912. [Nick Burch <nick burch alfresco com>]

docs/manual/expr.xml

+2 −1
Original line number Diff line number Diff line
@@ -46,6 +46,7 @@ 
<seealso><directive module="mod_filter">FilterProvider</directive></seealso>

<seealso><a href="mod/mod_authz_core.html#reqexpr">Require expr</a></seealso>

<seealso><directive module="mod_ssl">SSLRequire</directive></seealso>

<seealso><directive module="mod_log_debug">LogMessage</directive></seealso>

<seealso><module>mod_include</module></seealso>



  <section id="grammar">
@@ -227,7 +228,7 @@ listfunction ::= listfuncname "<strong>(</strong>" word "<strong>)</strong>" 
        <td>"<code>on</code>" if the connection uses IPv6,

            "<code>off</code>" otherwise</td></tr>

    <tr><td><code>REQUEST_STATUS</code></td>

        <td>The HTTP error status of the request<td></tr>

        <td>The HTTP error status of the request</td></tr>

    <tr><td><code>REQUEST_LOG_ID</code></td>

        <td>The error log id of the request (see

            <directive module="core">ErrorLogFormat</directive>)</td></tr>

docs/manual/mod/mod_log_debug.xml

0 → 100644
+132 −0
Original line number Diff line number Diff line 
<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>

<!-- $LastChangedRevision$ -->



<!--

 Licensed to the Apache Software Foundation (ASF) under one or more

 contributor license agreements.  See the NOTICE file distributed with

 this work for additional information regarding copyright ownership.

 The ASF licenses this file to You under the Apache License, Version 2.0

 (the "License"); you may not use this file except in compliance with

 the License.  You may obtain a copy of the License at



     http://www.apache.org/licenses/LICENSE-2.0



 Unless required by applicable law or agreed to in writing, software

 distributed under the License is distributed on an "AS IS" BASIS,

 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 See the License for the specific language governing permissions and

 limitations under the License.

-->



<modulesynopsis metafile="mod_log_debug.xml.meta">



<name>mod_log_debug</name>

<description>Additional configurable debug logging</description>

<status>Experimental</status>

<sourcefile>mod_log_debug.c</sourcefile>

<identifier>log_debug_module</identifier>

<compatibility>Available in Apache 2.3.14 and later</compatibility>



<section id="examples"><title>Examples</title>



    <ol>

      <li>

        Log message after request to /foo/* is processed:



        <example>

            &lt;Location /foo&gt;<br/>

            &nbsp;&nbsp;LogMessage "/foo has been requested"<br/>

            &lt;/Location&gt;<br/>

        </example>

      </li>



      <li>

        Log message if request to /foo/* is processed in a sub-request:

        <example>

            &lt;Location /foo&gt;<br/>

            &nbsp;&nbsp;LogMessage "subrequest to /foo" hook=type_checker if=%{IS_SUBREQ}<br/>

            &lt;/Location&gt;<br/>

        </example>



        The default log_transaction hook is not executed for sub-requests,

        therefore we have to use a different hook.

      </li>





      <li>

        Log message if an IPv6 client causes a request timeout:

        <example>

            LogMessage "IPv6 timeout from %{REMOTE_ADDR}"

              "if=-T %{IPV6} &amp;&amp; %{REQUEST_STATUS} = 408"

        </example>

        Note the placing of the dobule quotes for the <code>if=</code> argument.

      </li>



      <li>

        Log the value of the "X-Foo" request environment variable in each

        stage of the request:

        <example>

            &lt;Location /&gt;<br/>

            &nbsp;&nbsp;LogMessage "%{reqenv:X-Foo}" hook=all<br/>

            &lt;/Location&gt;<br/>

        </example>

        Together with the microsecond time stamps in the error log, this

        allows to determine the times spent in the different parts of the

        request processing.

      </li>



    </ol>

</section>



<directivesynopsis>

<name>LogMessage</name>

<description>Log userdefined message to error log

</description>

<syntax>LogMessage <var>message</var>

[hook=<var>hook</var>] [if=<var>expression</var>]

</syntax>

<default>Unset</default>

<contextlist><context>directory</context>

</contextlist>



<usage>

    <p>This directive causes a user defined message to be logged to the

    error log. The message can use variables and functions from the

    <a href="../expr.html">ap_expr syntax</a>. The messages are logged at

    loglevel info.</p>



    <p>The hook specifies before which phase of request procesing the message

    will be logged. The following hooks are supported:</p>



    <table border="1" style="zebra">

    <columnspec><column width="1"/></columnspec>

    <tr><th>Name</th></tr>

    <tr><td><code>translate_name</code></td></tr>

    <tr><td><code>type_checker</code></td></tr>

    <tr><td><code>quick_handler</code></td></tr>

    <tr><td><code>map_to_storage</code></td></tr>

    <tr><td><code>check_access</code></td></tr>

    <tr><td><code>check_access_ex</code></td></tr>

    <tr><td><code>insert_filter</code></td></tr>

    <tr><td><code>check_authn</code></td></tr>

    <tr><td><code>check_authz</code></td></tr>

    <tr><td><code>fixups</code></td></tr>

    <tr><td><code>handler</code></td></tr>

    <tr><td><code>log_transaction</code></td></tr>

    </table>



    <p>The default is <code>log_transaction</code>. The special value

    <code>all</code> is also supported, causing a message to be logged at each

    phase. Not all hooks are executed for every request.</p>



    <p>The optional expression allows to restrict the message if a

    condition is met. The details of the expression syntax are described in

    the <a href="../expr.html">ap_expr documentation</a>.</p>



</usage>



</directivesynopsis>



</modulesynopsis>

docs/manual/new_features_2_4.xml

+4 −0
Original line number Diff line number Diff line
@@ -107,6 +107,10 @@ 
      <dt><module>mod_slotmem_shm</module></dt>

      <dd>Provides a Slot-based shared memory provider (ala the scoreboard).</dd>



      <dt><module>mod_log_debug</module></dt>

      <dd>Allows to add customizable debug logging at different phases of the

      request processing.</dd>



    </dl>

  </section>

modules/loggers/config.m4

+1 −0
Original line number Diff line number Diff line
@@ -5,6 +5,7 @@ dnl APACHE_MODULE(name, helptext[, objects[, structname[, default[, config]]]]) 
APACHE_MODPATH_INIT(loggers)

	

APACHE_MODULE(log_config, logging configuration.  You won't be able to log requests to the server without this module., , , yes)

APACHE_MODULE(log_debug, configurable debug logging, , , no)

APACHE_MODULE(log_forensic, forensic logging)



if test "x$enable_log_forensic" != "xno"; then