This is an automated email from the ASF dual-hosted git repository.
rjung pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/main by this push:
new 2ef1ec2062 Improve docs for access log valves.
new a9bdd19263 Merge branch 'main' of
https://gitbox.apache.org/repos/asf/tomcat
2ef1ec2062 is described below
commit 2ef1ec20629566d4e257cf276ed74273d58e2774
Author: Rainer Jung <[email protected]>
AuthorDate: Fri Apr 21 13:43:10 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 | 50 ++++++++++++++++++++++++++++++-------------
1 file changed, 35 insertions(+), 15 deletions(-)
diff --git a/webapps/docs/config/valve.xml b/webapps/docs/config/valve.xml
index 2c15ed6697..c0af86da54 100644
--- a/webapps/docs/config/valve.xml
+++ b/webapps/docs/config/valve.xml
@@ -288,9 +288,12 @@
<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
microseconds</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,13 +304,10 @@
<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>%T</code></b> - Time taken to process the request, in
seconds</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
microseconds</li>
- <li><b><code>%T</code></b> - Time taken to process the request, in
seconds</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>%X</code></b> - Connection status when response is completed:
<ul>
<li><code>X</code> = Connection aborted before the response
completed.</li>
@@ -331,8 +331,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
@@ -383,6 +383,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
@@ -508,9 +512,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
@@ -535,18 +539,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>
@@ -554,16 +572,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: [email protected]
For additional commands, e-mail: [email protected]
