From: Joshua Slive Date: Wed, 25 May 2005 20:16:26 +0000 (+0000) Subject: Clean up the notes to the logformat section of the mod_log config docs. X-Git-Tag: 2.1.5~67 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3d55a97253a5942e9a0c92811d368e502cc60727;p=thirdparty%2Fapache%2Fhttpd.git 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 --- diff --git a/docs/manual/mod/mod_log_config.xml b/docs/manual/mod/mod_log_config.xml index 03ab1c6e6f2..2f623ca3861 100644 --- a/docs/manual/mod/mod_log_config.xml +++ b/docs/manual/mod/mod_log_config.xml @@ -70,110 +70,110 @@ %% The percent sign - %...a + %a Remote IP-address - %...A + %A Local IP-address - %...B + %B Size of response in bytes, excluding HTTP headers. - %...b + %b Size of response in bytes, excluding HTTP headers. In CLF format, i.e. a '-' rather than a 0 when no bytes are sent. - %...{Foobar}C + %{Foobar}C The contents of cookie Foobar in the request sent to the server. - %...D + %D The time taken to serve the request, in microseconds. - %...{FOOBAR}e + %{FOOBAR}e The contents of the environment variable FOOBAR - %...f + %f Filename - %...h + %h Remote host - %...H + %H The request protocol - %...{Foobar}i + %{Foobar}i The contents of Foobar: header line(s) in the request sent to the server. - %...l + %l Remote logname (from identd, if supplied). This will return a dash unless mod_ident is present and IdentityCheck is set On. - %...m + %m The request method - %...{Foobar}n + %{Foobar}n The contents of note Foobar from another module. - %...{Foobar}o + %{Foobar}o The contents of Foobar: header line(s) in the reply. - %...p + %p The canonical port of the server serving the request - %...P + %P The process ID of the child that serviced the request. - %...{format}P + %{format}P The process ID or thread id of the child that serviced the request. Valid formats are pid and tid. - %...q + %q The query string (prepended with a ? if a query string exists, otherwise an empty string) - %...r + %r First line of request - %...s + %s Status. For requests that got internally redirected, this is - the status of the *original* request --- %...>s + the status of the *original* request --- %>s for the last. - %...t + %t Time the request was received (standard english format) - %...{format}t + %{format}t The time, in the form given by format, which should be in strftime(3) format. (potentially localized) - %...T + %T The time taken to serve the request, in seconds. - %...u + %u Remote user (from auth; may be bogus if return status (%s) is 401) - %...U + %U The URL path requested, not including any query string. - %...v + %v The canonical ServerName of the server serving the request. - %...V + %V The server name according to the UseCanonicalName setting. - %...X + %X Connection status when response is completed: @@ -188,92 +188,92 @@ sent.
-

(This directive was %...c in late versions of Apache +

(This directive was %c in late versions of Apache 1.3, but this conflicted with the historical ssl - %...{var}c syntax.)

+ %{var}c syntax.)

- %...I + %I Bytes received, including request and headers, cannot be zero. You need to enable mod_logio to use this. - %...O + %O Bytes sent, including headers, cannot be zero. You need to enable mod_logio to use this. -

The "..." can be nothing at all (e.g., - "%h %u %r %s %b"), 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 User-agent: on 400 - errors and 501 errors (Bad Request, Not Implemented) only; - "%!200,304,302{Referer}i" logs Referer: on all requests - which did not return some sort of normal status.

- -

The modifiers "<" and ">" 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 - % directives %s, %U, %T, %D, and - %r look at the original request while all others look - at the final request. So for example, %>s can be - used to record the final status of the request and - %<u can be used to record the original - authenticated user on a request that is internally redirected to an - unauthenticated resource.

- -

Note that in httpd 2.0 versions prior to 2.0.46, no escaping was performed - on the strings from %...r, %...i and - %...o. 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.

- -

For security reasons, starting with 2.0.46, non-printable and - other special characters are escaped mostly by using - \xhh sequences, where hh stands for - the hexadecimal representation of the raw byte. Exceptions from this - rule are " and \ which are escaped by prepending - a backslash, and all whitespace characters which are written in their - C-style notation (\n, \t etc).

- -

Note that in httpd 2.0, unlike 1.3, the %b and - %B 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 %O format provided - by mod_logio will log the actual number of bytes - sent over the network.

- -

Some commonly used log format strings are:

- -
-
Common Log Format (CLF)
-
"%h %l %u %t \"%r\" %>s %b"
- -
Common Log Format with Virtual Host
-
"%v %h %l %u %t \"%r\" %>s %b"
- -
NCSA extended/combined log format
-
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" - \"%{User-agent}i\""
- -
Referer log format
-
"%{Referer}i -> %U"
- -
Agent (Browser) log format
-
"%{User-agent}i"
-
- -

Note that the canonical ServerName and Listen of the server serving the - request are used for %v and %p - respectively. This happens regardless of the UseCanonicalName 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.

+
Modifiers + +

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, "%400,501{User-agent}i" logs + User-agent on 400 errors and 501 errors only. For + other status codes, the literal string "-" will be + logged. The status code list may be preceded by a + "!" to indicate negation: + "%!200,304,302{Referer}i" logs Referer + on all requests that do not return one of the three + specified codes.

+ +

The modifiers "<" and ">" 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 % directives %s, %U, %T, + %D, and %r look at the original request + while all others look at the final request. So for example, + %>s can be used to record the final status of + the request and %<u can be used to record the + original authenticated user on a request that is internally + redirected to an unauthenticated resource.

+ +
+ +
Some Notes + +

For security reasons, starting with version 2.0.46, + non-printable and other special characters in %r, + %i and %o are escaped using + \xhh sequences, where hh + stands for the hexadecimal representation of the raw + byte. Exceptions from this rule are " and + \, which are escaped by prepending a backslash, and + all whitespace characters, which are written in their C-style + notation (\n, \t, 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.

+ +

In httpd 2.0, unlike 1.3, the %b and + %B 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 %O + format provided by mod_logio will log the + actual number of bytes sent over the network.

+ +
+ +
Examples + +

Some commonly used log format strings are:

+ +
+
Common Log Format (CLF)
+
"%h %l %u %t \"%r\" %>s %b"
+ +
Common Log Format with Virtual Host
+
"%v %h %l %u %t \"%r\" %>s %b"
+ +
NCSA extended/combined log format
+
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" + \"%{User-agent}i\""
+ +
Referer log format
+
"%{Referer}i -> %U"
+ +
Agent (Browser) log format
+
"%{User-agent}i"
+
+
Security Considerations