Commit 8e710f14 authored by Joshua Slive's avatar Joshua Slive
Browse files

Clean up the notes to the logformat section of the mod_log config docs. 

These have been growing using the "here's something else we should
say" technique, without any serious thought for readability.

In particular:

- Remove the "..." in all the format strings, since almost nobody
uses this and it can be confusing.  It is still documented, just
not included in the definitions.

- Create three sections: modifiers, examples, and a "notes" section
for stuff that doesn't go any place else.

- Remove the discussion of %v being the canonical name.  I think
that it is quite clear since the addition of %V what the difference
is.


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

docs/manual/mod/mod_log_config.xml

+107 −107
Original line number Diff line number Diff line
@@ -70,110 +70,110 @@ 
    <tr><td><code>%%</code></td>

        <td>The percent sign</td></tr>



    <tr><td><code>%...a</code></td>

    <tr><td><code>%a</code></td>

        <td>Remote IP-address</td></tr>



    <tr><td><code>%...A</code></td>

    <tr><td><code>%A</code></td>

        <td>Local IP-address</td></tr>



    <tr><td><code>%...B</code></td>

    <tr><td><code>%B</code></td>

        <td>Size of response in bytes, excluding HTTP headers.</td></tr>



    <tr><td><code>%...b</code></td>

    <tr><td><code>%b</code></td>

        <td>Size of response in bytes, excluding HTTP headers. In CLF format, <em>i.e.</em>

        a '<code>-</code>' rather than a 0 when no bytes are sent.</td></tr>



    <tr><td><code>%...{<var>Foobar</var>}C</code></td>

    <tr><td><code>%{<var>Foobar</var>}C</code></td>

        <td>The contents of cookie <var>Foobar</var> in the request sent

        to the server.</td></tr>



    <tr><td><code>%...D</code></td>

    <tr><td><code>%D</code></td>

        <td>The time taken to serve the request, in microseconds.</td></tr>



    <tr><td><code>%...{<var>FOOBAR</var>}e</code></td>

    <tr><td><code>%{<var>FOOBAR</var>}e</code></td>

        <td>The contents of the environment variable

        <var>FOOBAR</var></td></tr>



    <tr><td><code>%...f</code></td>

    <tr><td><code>%f</code></td>

        <td>Filename</td></tr>



    <tr><td><code>%...h</code></td>

    <tr><td><code>%h</code></td>

        <td>Remote host</td></tr>



    <tr><td><code>%...H</code></td>

    <tr><td><code>%H</code></td>

        <td>The request protocol</td></tr>



    <tr><td><code>%...{<var>Foobar</var>}i</code></td>

    <tr><td><code>%{<var>Foobar</var>}i</code></td>

        <td>The contents of <code><var>Foobar</var>:</code> header line(s)

        in the request sent to the server.</td></tr>



    <tr><td><code>%...l</code></td>

    <tr><td><code>%l</code></td>

        <td>Remote logname (from identd, if supplied). This will return a

        dash unless <module>mod_ident</module> is present and <directive

        module="mod_ident">IdentityCheck</directive> is set

        <code>On</code>.</td></tr>



    <tr><td><code>%...m</code></td>

    <tr><td><code>%m</code></td>

        <td>The request method</td></tr>



    <tr><td><code>%...{<var>Foobar</var>}n</code></td>

    <tr><td><code>%{<var>Foobar</var>}n</code></td>

        <td>The contents of note <var>Foobar</var> from another

        module.</td></tr>



    <tr><td><code>%...{<var>Foobar</var>}o</code></td>

    <tr><td><code>%{<var>Foobar</var>}o</code></td>

        <td>The contents of <code><var>Foobar</var>:</code> header line(s)

        in the reply.</td></tr>



    <tr><td><code>%...p</code></td>

    <tr><td><code>%p</code></td>

        <td>The canonical port of the server serving the request</td></tr>



    <tr><td><code>%...P</code></td>

    <tr><td><code>%P</code></td>

        <td>The process ID of the child that serviced the request.</td></tr>



    <tr><td><code>%...{<var>format</var>}P</code></td>

    <tr><td><code>%{<var>format</var>}P</code></td>

        <td>The process ID or thread id of the child that serviced the 

        request.  Valid formats are <code>pid</code> and <code>tid</code>.

        </td></tr>



    <tr><td><code>%...q</code></td>

    <tr><td><code>%q</code></td>

        <td>The query string (prepended with a <code>?</code> if a query

        string exists, otherwise an empty string)</td></tr>



    <tr><td><code>%...r</code></td>

    <tr><td><code>%r</code></td>

        <td>First line of request</td></tr>



    <tr><td><code>%...s</code></td>

    <tr><td><code>%s</code></td>

        <td>Status. For requests that got internally redirected, this is

        the status of the *original* request --- <code>%...&gt;s</code>

        the status of the *original* request --- <code>%&gt;s</code>

        for the last.</td></tr>



    <tr><td><code>%...t</code></td>

    <tr><td><code>%t</code></td>

        <td>Time the request was received (standard english

        format)</td></tr>



    <tr><td><code>%...{<var>format</var>}t</code></td>

    <tr><td><code>%{<var>format</var>}t</code></td>

        <td>The time, in the form given by format, which should be in

        <code>strftime(3)</code> format. (potentially localized)</td></tr>



    <tr><td><code>%...T</code></td>

    <tr><td><code>%T</code></td>

        <td>The time taken to serve the request, in seconds.</td></tr>



    <tr><td><code>%...u</code></td>

    <tr><td><code>%u</code></td>

        <td>Remote user (from auth; may be bogus if return status

        (<code>%s</code>) is 401)</td></tr>



    <tr><td><code>%...U</code></td>

    <tr><td><code>%U</code></td>

        <td>The URL path requested, not including any query string.</td></tr>



    <tr><td><code>%...v</code></td>

    <tr><td><code>%v</code></td>

        <td>The canonical <directive module="core">ServerName</directive>

        of the server serving the request.</td></tr>



    <tr><td><code>%...V</code></td>

    <tr><td><code>%V</code></td>

        <td>The server name according to the <directive module="core"

        >UseCanonicalName</directive> setting.</td></tr>



    <tr><td><code>%...X</code></td>

    <tr><td><code>%X</code></td>

        <td>Connection status when response is completed:



        <table>
@@ -188,62 +188,71 @@ 
            sent.</td></tr>

        </table>



        <p>(This directive was <code>%...c</code> in late versions of Apache

        <p>(This directive was <code>%c</code> in late versions of Apache

        1.3, but this conflicted with the historical ssl

        <code>%...{<var>var</var>}c</code> syntax.)</p></td></tr>

        <code>%{<var>var</var>}c</code> syntax.)</p></td></tr>



    <tr><td><code>%...I</code></td>

    <tr><td><code>%I</code></td>

        <td>Bytes received, including request and headers, cannot be zero.

        You need to enable <module>mod_logio</module> to use this.</td></tr>



    <tr><td><code>%...O</code></td>

    <tr><td><code>%O</code></td>

        <td>Bytes sent, including headers, cannot be zero. You need to

        enable <module>mod_logio</module> to use this.</td></tr>

    </table>



    <p>The "<var>...</var>" can be nothing at all (<em>e.g.</em>,

    <code>"%h %u %r %s %b"</code>), or it can indicate conditions for

    inclusion of the item (which will cause it to be replaced with "-" if

    the condition is not met). The forms of condition are a list of

    HTTP status codes, which may or may not be preceded by "!".

    Thus, "%400,501{User-agent}i" logs <code>User-agent:</code> on 400

    errors and 501 errors (Bad Request, Not Implemented) only;

    "%!200,304,302{Referer}i" logs <code>Referer:</code> on all requests

    which did <em>not</em> return some sort of normal status.</p>

    <section id="modifiers"><title>Modifiers</title>



      <p>Particular items can be restricted to print only for

      responses with specific HTTP status codes by placing a

      comma-separated list of status codes immediately following the

      "%".  For example, <code>"%400,501{User-agent}i"</code> logs

      <code>User-agent</code> on 400 errors and 501 errors only.  For

      other status codes, the literal string <code>"-"</code> will be

      logged.  The status code list may be preceded by a

      "<code>!</code>" to indicate negation:

      <code>"%!200,304,302{Referer}i"</code> logs <code>Referer</code>

      on all requests that do <em>not</em> return one of the three

      specified codes.</p>



      <p>The modifiers "&lt;" and "&gt;" can be used for requests that

    have been internally redirected to choose whether the original or

    final (respectively) request should be consulted.  By default, the

    <code>%</code> directives <code>%s, %U, %T, %D,</code> and

    <code>%r</code> look at the original request while all others look

    at the final request.  So for example, <code>%&gt;s</code> can be

    used to record the final status of the request and

    <code>%&lt;u</code> can be used to record the original

    authenticated user on a request that is internally redirected to an

    unauthenticated resource.</p>



    <p>Note that in httpd 2.0 versions prior to 2.0.46, no escaping was performed

    on the strings from <code>%...r</code>, <code>%...i</code> and

    <code>%...o</code>. This was mainly to comply with the requirements of

    the Common Log Format. This implied that clients could insert control

    characters into the log, so you had to be quite careful when dealing

    with raw log files.</p>



    <p>For security reasons, starting with 2.0.46, non-printable and

    other special characters are escaped mostly by using

    <code>\x<var>hh</var></code> sequences, where <var>hh</var> stands for

    the hexadecimal representation of the raw byte. Exceptions from this

    rule are <code>"</code> and <code>\</code> which are escaped by prepending

    a backslash, and all whitespace characters which are written in their

    C-style notation (<code>\n</code>, <code>\t</code> etc).</p>



    <p>Note that in httpd 2.0, unlike 1.3, the <code>%b</code> and

      have been internally redirected to choose whether the original

      or final (respectively) request should be consulted.  By

      default, the <code>%</code> directives <code>%s, %U, %T,

      %D,</code> and <code>%r</code> look at the original request

      while all others look at the final request.  So for example,

      <code>%&gt;s</code> can be used to record the final status of

      the request and <code>%&lt;u</code> can be used to record the

      original authenticated user on a request that is internally

      redirected to an unauthenticated resource.</p>



    </section>



    <section id="format-notes"><title>Some Notes</title>



      <p>For security reasons, starting with version 2.0.46,

      non-printable and other special characters in <code>%r</code>,

      <code>%i</code> and <code>%o</code> are escaped using

      <code>\x<var>hh</var></code> sequences, where <var>hh</var>

      stands for the hexadecimal representation of the raw

      byte. Exceptions from this rule are <code>"</code> and

      <code>\</code>, which are escaped by prepending a backslash, and

      all whitespace characters, which are written in their C-style

      notation (<code>\n</code>, <code>\t</code>, etc).  In versions

      prior to 2.0.46, no escaping was performed on these strings so

      you had to be quite careful when dealing with raw log files.</p>



      <p>In httpd 2.0, unlike 1.3, the <code>%b</code> and

      <code>%B</code> format strings do not represent the number of

    bytes sent to the client, but simply the size in bytes of the HTTP

    response (which will differ, for instance, if the connection is

    aborted, or if SSL is used).  The <code>%O</code> format provided

    by <module>mod_logio</module> will log the actual number of bytes

    sent over the network.</p>

      bytes sent to the client, but simply the size in bytes of the

      HTTP response (which will differ, for instance, if the

      connection is aborted, or if SSL is used).  The <code>%O</code>

      format provided by <module>mod_logio</module> will log the

      actual number of bytes sent over the network.</p>



    </section>



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



      <p>Some commonly used log format strings are:</p>
@@ -264,16 +273,7 @@ 
        <dt>Agent (Browser) log format</dt>

        <dd><code>"%{User-agent}i"</code></dd>

      </dl>



    <p>Note that the canonical <directive module="core"

    >ServerName</directive> and <directive module="mpm_common"

    >Listen</directive> of the server serving the

    request are used for <code>%v</code> and <code>%p</code>

    respectively. This happens regardless of the <directive

    module="core">UseCanonicalName</directive> setting

    because otherwise log analysis programs would have to duplicate

    the entire vhost matching algorithm in order to decide what

    host really served the request.</p>

    </section>

</section>



<section id="security"><title>Security Considerations</title>