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

3 files changed, 138 insertions, 1 deletions

diff --git a/docs/manual/expr.xml b/docs/manual/expr.xml
index 07fbb667ac..fc412bfc5c 100644
--- a/docs/manual/expr.xml
+++ b/docs/manual/expr.xml
@@ -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>
diff --git a/docs/manual/mod/mod_log_debug.xml b/docs/manual/mod/mod_log_debug.xml
new file mode 100644
index 0000000000..d4f629dbaf
--- /dev/null
+++ b/docs/manual/mod/mod_log_debug.xml
@@ -0,0 +1,132 @@
+<?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>
diff --git a/docs/manual/new_features_2_4.xml b/docs/manual/new_features_2_4.xml
index 6e30b0f7c6..98967c1a92 100644
--- a/docs/manual/new_features_2_4.xml
+++ b/docs/manual/new_features_2_4.xml
@@ -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>