This is an automated email from the ASF dual-hosted git repository.
rjung pushed a commit to branch 9.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/9.0.x by this push:
new c7e83cfda1 Improve docs for access log valves.
c7e83cfda1 is described below
commit c7e83cfda180888ee5308e90a6fd5f1c23e6bf89
Author: Rainer Jung <rainer.j...@kippdata.de>
AuthorDate: Fri Apr 21 13:48:12 2023 +0200
Improve docs for access log valves.
- sort pattern identifier lists alphabetically.
Easier to find things than in a mxied alphabetical/context sorted list.
- document special cases (handling of unknown pattern indentifiers)
- list limitations of JsonAccessLogValve
- remove redundant field value info from JsonAccessLogValve,
refer to AccessLogValve values instead.
---
webapps/docs/config/valve.xml | 58 +++++++++++++++++++++++++++++--------------
1 file changed, 39 insertions(+), 19 deletions(-)
diff --git a/webapps/docs/config/valve.xml b/webapps/docs/config/valve.xml
index 936c02b227..895c9291f9 100644
--- a/webapps/docs/config/valve.xml
+++ b/webapps/docs/config/valve.xml
@@ -288,9 +288,14 @@
<li><b><code>%A</code></b> - Local IP address</li>
<li><b><code>%b</code></b> - Bytes sent, excluding HTTP headers, or '-' if
zero</li>
<li><b><code>%B</code></b> - Bytes sent, excluding HTTP headers</li>
+ <li><b><code>%D</code></b> - Time taken to process the request in millis.
Note: In
+ httpd %D is microseconds. Behaviour will be aligned to httpd
+ in Tomcat 10 onwards.</li>
+ <li><b><code>%F</code></b> - Time taken to commit the response, in
milliseconds</li>
<li><b><code>%h</code></b> - Remote host name (or IP address if
<code>enableLookups</code> for the connector is false)</li>
<li><b><code>%H</code></b> - Request protocol</li>
+ <li><b><code>%I</code></b> - Current request thread name (can compare
later with stacktraces)</li>
<li><b><code>%l</code></b> - Remote logical username from identd (always
returns
'-')</li>
<li><b><code>%m</code></b> - Request method (GET, POST, etc.)</li>
@@ -301,18 +306,13 @@
<li><b><code>%s</code></b> - HTTP status code of the response</li>
<li><b><code>%S</code></b> - User session ID</li>
<li><b><code>%t</code></b> - Date and time, in Common Log Format</li>
- <li><b><code>%u</code></b> - Remote user that was authenticated (if any),
else '-' (escaped if required)</li>
- <li><b><code>%U</code></b> - Requested URL path</li>
- <li><b><code>%v</code></b> - Local server name</li>
- <li><b><code>%D</code></b> - Time taken to process the request in millis.
Note: In
- httpd %D is microseconds. Behaviour will be aligned to httpd
- in Tomcat 10 onwards.</li>
<li><b><code>%T</code></b> - Time taken to process the request, in
seconds. Note: This
value has millisecond resolution whereas in httpd it has
second resolution. Behaviour will be align to httpd
in Tomcat 10 onwards.</li>
- <li><b><code>%F</code></b> - Time taken to commit the response, in
milliseconds</li>
- <li><b><code>%I</code></b> - Current request thread name (can compare
later with stacktraces)</li>
+ <li><b><code>%u</code></b> - Remote user that was authenticated (if any),
else '-' (escaped if required)</li>
+ <li><b><code>%U</code></b> - Requested URL path</li>
+ <li><b><code>%v</code></b> - Local server name</li>
<li><b><code>%X</code></b> - Connection status when response is completed:
<ul>
<li><code>X</code> = Connection aborted before the response
completed.</li>
@@ -336,8 +336,8 @@
<li><b><code>%{xxx}i</code></b> write value of incoming header with name
<code>xxx</code> (escaped if required)</li>
<li><b><code>%{xxx}o</code></b> write value of outgoing header with name
<code>xxx</code> (escaped if required)</li>
<li><b><code>%{xxx}c</code></b> write value of cookie(s) with name
<code>xxx</code> (comma separated and escaped if required)</li>
- <li><b><code>%{xxx}r</code></b> write value of ServletRequest attribute
with name <code>xxx</code> (escaped if required)</li>
- <li><b><code>%{xxx}s</code></b> write value of HttpSession attribute with
name <code>xxx</code> (escaped if required)</li>
+ <li><b><code>%{xxx}r</code></b> write value of ServletRequest attribute
with name <code>xxx</code> (escaped if required, value <code>??</code> if
request is null)</li>
+ <li><b><code>%{xxx}s</code></b> write value of HttpSession attribute with
name <code>xxx</code> (escaped if required, value <code>??</code> if request is
null)</li>
<li><b><code>%{xxx}p</code></b> write local (server) port
(<code>xxx==local</code>) or
remote (client) port (<code>xxx=remote</code>)</li>
<li><b><code>%{xxx}t</code></b> write timestamp at the end of the request
formatted using the
@@ -384,6 +384,10 @@
appends the values of the <code>Referer</code> and <code>User-Agent</code>
headers, each in double quotes, to the <code>common</code> pattern.</p>
+ <p>Fields using unknown pattern identifiers will be logged as
<code>???X???</code>
+ where <code>X</code> is the unknown identifier. Fields with unknown
pattern identifier
+ plus <code>{xxx}</code> key will be logged as <code>???</code>.</p>
+
<p>When Tomcat is operating behind a reverse proxy, the client information
logged by the Access Log Valve may represent the reverse proxy, the browser
or some combination of the two depending on the configuration of Tomcat and
@@ -509,9 +513,9 @@
<subsection name="Introduction">
<p>The <strong>JSON Access Log Valve</strong> extends the
- <a href="#Access_Log_Valve">Access Log Valve</a> class, and so
+ <a href="#Access_Log_Valve">Access Log Valve</a>, and so
uses the same self-contained logging logic. This means it
- implements many of the same file handling attributes. The main
+ implements the same file handling attributes. The main
difference to the standard <code>AccessLogValve</code> is that
<code>JsonAccessLogValve</code> creates log files which
follow the JSON syntax as defined by
@@ -536,18 +540,32 @@
</attributes>
- <p>While the pattern supported are the same as for the regular access log,
- those are mapped to specific JSON attribute names. The attributes are the
- following:
+ <p>While the patterns supported are the same as for the regular
+ <a href="#Access_Log_Valve">Access Log Valve</a>,
+ there are a few differences:
+ <ul>
+ <li>requests are logged as JSON objects. Each "%" prefixed pattern
+ identifier results in a key value pair in this object.
+ See below for the list of keys used for the respective pattern
+ identifiers.</li>
+ <li>the values logged are the same as the ones logged by
+ the standard <a href="#Access_Log_Valve">Access Log Valve</a>
+ for the same pattern identifiers.</li>
+ <li>pattern identifiers using a subkey of the form <code>%{subkey}</code>
+ are not yet supported and get silently ignored.</li>
+ <li>any verbatim text between pattern identifiers gets silently
ignored.</li>
+ </ul>
+ The JSON object keys used for the respective pattern identifiers are the
following:
<ul>
<li><b><code>%a</code></b>: remoteAddr</li>
<li><b><code>%A</code></b>: localAddr</li>
- <li><b><code>%b</code></b>: size (byteSent: size)</li>
+ <li><b><code>%b</code></b>: size</li>
<li><b><code>%B</code></b>: byteSentNC</li>
<li><b><code>%D</code></b>: elapsedTime</li>
<li><b><code>%F</code></b>: firstByteTime</li>
<li><b><code>%h</code></b>: host</li>
<li><b><code>%H</code></b>: protocol</li>
+ <li><b><code>%I</code></b>: threadName</li>
<li><b><code>%l</code></b>: logicalUserName</li>
<li><b><code>%m</code></b>: method</li>
<li><b><code>%p</code></b>: port</li>
@@ -555,16 +573,18 @@
<li><b><code>%r</code></b>: request</li>
<li><b><code>%s</code></b>: statusCode</li>
<li><b><code>%S</code></b>: sessionId</li>
- <li><b><code>%t</code></b>: time (dateTime: time)</li>
+ <li><b><code>%t</code></b>: time</li>
<li><b><code>%T</code></b>: elapsedTimeS</li>
<li><b><code>%u</code></b>: user</li>
- <li><b><code>%U</code></b>: path (requestURI: path)</li>
+ <li><b><code>%U</code></b>: path</li>
<li><b><code>%v</code></b>: localServerName</li>
- <li><b><code>%I</code></b>: threadName</li>
<li><b><code>%X</code></b>: connectionStatus</li>
</ul>
</p>
+ <p>Fields using unknown pattern identifiers will be logged with JSON
object key
+ <code>other-X</code> where <code>X</code> is the unknown identifier.</p>
+
</subsection>
</subsection>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
