tomcat8的Valve Component(阀门组件)之AccessLog访问日志配置

官方文档介绍https://tomcat.apache.org/tomcat-8.5-doc/config/valve.html#Access_Log_Valve

Valve 组件介绍

A Valve element represents a component that will be inserted into the request processing pipeline for the associated Catalina container (Engine, Host, or Context). Individual Valves have distinct processing capabilities, and are described individually below.

Valve元素表示将插入相关Catalina容器（引擎，主机或上下文）的请求处理管道中的组件。 各个阀门具有独特的处理能力，下面分别进行介绍。

The description below uses the variable name $CATALINA_BASE to refer the base directory against which most relative paths are resolved. If you have not configured Tomcat for multiple instances by setting a CATALINA_BASE directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, the directory into which you have installed Tomcat.

下面的描述使用变量名$ CATALINA_BASE来引用可解决大多数相对路径的基本目录。 如果尚未通过设置CATALINA_BASE目录为多个实例配置Tomcat，则$ CATALINA_BASE将设置为$ CATALINA_HOME的值，该目录已将Tomcat安装到该目录中。

1、Access Logging

访问日志记录由实现org.apache.catalina.AccessLog接口的阀门(valve)执行。

1.1、Access Log Valve

介绍

警告：如果使用了多个AccessLogValve实例，则应将它们配置为使用不同的输出文件。

The Access Log Valve creates log files in the same format as those created by standard web servers. These logs can later be analyzed by standard log analysis tools to track page hit counts, user session activity, and so on. This Valve uses self-contained logic to write its log files, which can be automatically rolled over at midnight each day. (The essential requirement for access logging is to handle a large continuous stream of data with low overhead. This Valve does not use Apache Commons Logging, thus avoiding additional overhead and potentially complex configuration).

This Valve may be associated with any Catalina container (Context, Host, or Engine), and will record ALL requests processed by that container.

        Access Log Valve以与标准Web服务器创建的格式相同的格式创建日志文件。以后可以使用标准的日志分析工具来分析这些日志，以跟踪页面的点击数，用户会话活动等。该Valve使用独立的逻辑来写入其日志文件，该日志文件可以在每天午夜自动翻转。 （访问日志记录的基本要求是以低开销处理大量连续的数据流。此Valve不使用Apache Commons Logging，从而避免了额外的开销和潜在的复杂配置）。

此Valve可以与任何Catalina容器（上下文，主机或引擎）关联，并将记录该容器处理的所有请求。

属性

Attribute	Description
buffered	Flag to determine if logging will be buffered. If set to false, then access logging will be written after each request. Default value: true
className	Java class name of the implementation to use. This MUST be set to org.apache.catalina.valves.AccessLogValve to use the default access log valve.
condition	The same as conditionUnless. This attribute is provided for backwards compatibility.
conditionIf	Turns on conditional logging. If set, requests will be logged only if ServletRequest.getAttribute() is not null. For example, if this value is set to important, then a particular request will only be logged if ServletRequest.getAttribute("important") != null. The use of Filters is an easy way to set/unset the attribute in the ServletRequest on many different requests.
conditionUnless	Turns on conditional logging. If set, requests will be logged only if ServletRequest.getAttribute() is null. For example, if this value is set to junk, then a particular request will only be logged if ServletRequest.getAttribute("junk") == null. The use of Filters is an easy way to set/unset the attribute in the ServletRequest on many different requests.
directory	Absolute or relative pathname of a directory in which log files created by this valve will be placed. If a relative path is specified, it is interpreted as relative to $CATALINA_BASE. If no directory attribute is specified, the default value is "logs" (relative to $CATALINA_BASE). 该valve创建的日志文件将放置在目录的绝对或相对路径名。 如果指定了相对路径，则将其解释为相对于$ CATALINA_BASE。 如果未指定目录属性，则默认值为“ logs”（相对于$ CATALINA_BASE）。
encoding	Character set used to write the log file. An empty string means to use the system default character set. Default value: use the system default character set.
fileDateFormat	Allows a customized timestamp in the access log file name. The file is rotated whenever the formatted timestamp changes. The default value is .yyyy-MM-dd. If you wish to rotate every hour, then set this value to .yyyy-MM-dd.HH. The date format will always be localized using the locale en_US. 在访问日志文件名中允许自定义时间戳。 只要格式化的时间戳更改，文件就会旋转。 默认值为.yyyy-MM-dd。 如果您希望每小时旋转一次，请将此值设置为.yyyy-MM-dd.HH。 日期格式将始终使用语言环境en_US进行本地化。
ipv6Canonical	Flag to determine if IPv6 addresses should be represented in canonical representation format as defined by RFC 5952. If set to true, then IPv6 addresses will be written in canonical format (e.g. 2001:db8::1:0:0:1, ::1), otherwise it will be represented in full form (e.g. 2001:db8:0:0:1:0:0:1, 0:0:0:0:0:0:0:1). Default value: false
locale	The locale used to format timestamps in the access log lines. Any timestamps configured using an explicit SimpleDateFormat pattern (%{xxx}t) are formatted in this locale. By default the default locale of the Java process is used. Switching the locale after the AccessLogValve is initialized is not supported. Any timestamps using the common log format (CLF) are always formatted in the localeen_US.
maxDays	The maximum number of days rotated access logs will be retained for before being deleted. If not specified, the default value of -1will be used which means never delete old files. 轮换访问日志的最大保留天数将被删除之前保留。 如果未指定，将使用默认值-1，这表示从不删除旧文件。
maxLogMessageBufferSize	Log message buffers are usually recycled and re-used. To prevent excessive memory usage, if a buffer grows beyond this size it will be discarded. The default is 256 characters. This should be set to larger than the typical access log message size.
pattern	A formatting layout identifying the various information fields from the request and response to be logged, or the word common or combined to select a standard format. See below for more information on configuring this attribute. 格式布局，用于标识要记录的请求和响应中的各个信息字段，或者使用单词``通用''或``组合''来选择标准格式。 有关配置此属性的更多信息，请参见下文。
prefix	The prefix added to the start of each log file's name. If not specified, the default value is "access_log". 日志文件的名称前缀。
renameOnRotate	By default for a rotatable log the active access log file name will contain the current timestamp in fileDateFormat. During rotation the file is closed and a new file with the next timestamp in the name is created and used. When setting renameOnRotate to true, the timestamp is no longer part of the active log file name. Only during rotation the file is closed and then renamed to include the timestamp. This is similar to the behavior of most log frameworks when doing time based rotation. Default value: false
requestAttributesEnabled	Set to true to check for the existence of request attributes (typically set by the RemoteIpValve and similar) that should be used to override the values returned by the request for remote address, remote host, server port and protocol. If the attributes are not set, or this attribute is set to false then the values from the request will be used. If not set, the default value of false will be used.
resolveHosts	This attribute is no longer supported. Use the connector attribute enableLookups instead. If you have enableLookups on the connector set to true and want to ignore it, use %a instead of %h in the value of pattern. 不再支持此属性。 改为使用连接器属性enableLookups。 如果将连接器上的启用查阅设置为true并且想要忽略它，请在pattern的值中使用％a而不是％h。 原来的作用是：如果是true，tomcat会将这个服务器IP地址通过DNS转换为主机名；如果是false，就直接写服务器IP地址啦。默认false。
rotatable	Flag to determine if log rotation should occur. If set to false, then this file is never rotated and fileDateFormat is ignored. Default value: true 用于确定是否应该发生日志轮换的标志。 如果设置为false，则此文件永远不会旋转，并且fileDateFormat将被忽略。 默认值：true
suffix	The suffix added to the end of each log file's name. If not specified, the default value is "" (a zero-length string), meaning that no suffix will be added. 日志文件的名称后缀。

pattern属性的值由文字字符串组成，结合以“％”字符为前缀的模式标识符，以替换为来自当前请求和响应的相应变量值。 支持以下模式代码：％a-远程IP地址

%a   这是记录访问者的IP，在日志里是127.0.0.1
%A   这是记录本地服务器的IP，在日志里是192.168.254.108
%b   发送信息的字节数，不包括http头，如果字节数为0的话，显示为-
%B   发送信息的字节数，不包括http头。
%h   服务器的名称。如果resolveHosts为false的话，这里就是IP地址了，例如我的日志里是10.217.14.16
%H   访问者的协议，这里是HTTP/1.0
%l   Remote logical username from identd (always returns '-')
%m   访问的方式，是GET、POST等
%p   本地接收访问的端口 
%q   Query string (prepended with a '?' if it exists)；比如你访问的是aaa.jsp?bbb=ccc，那么这里就显示?bbb=ccc，就是querystring的意思
%r   First line of the request (method and request URI) 请求的方法和URL
%s   HTTP status code of the response http的响应状态码 
%S   用户的session ID,这个session ID大家可以另外查一下详细的解释，反正每次都会生成不同的session ID
%t   Date and time, in Common Log Format 请求时间
%u   Remote user that was authenticated (if any), else '-'  得到了验证的访问者，否则就是"-"
%U   访问的URL地址，我这里是/rightmainima/leftbott4.swf
%v   服务器名称，可能就是你url里面写的那个吧，我这里是localhost
%D   处理请求所需的时间（以毫秒为单位）。 注意：在httpd中，％D是微秒。 从Tomcat 10开始，行为将与httpd对齐。
%T  处理请求所花费的时间（以秒为单位）。 注意：此值具有毫秒分辨率，而在httpd中具有第二分辨率。 行为将与Tomcat 10及更高版本中的httpd保持一致。
%F  Time taken to commit the response, in millis 提交响应所花费的时间（以毫秒为单位）
%I  Current request thread name (can compare later with stacktraces) 当前请求线程名称（以后可以与stacktraces比较）
%X  Connection status when response is completed:响应完成时的连接状态：
    X = Connection aborted before the response completed.在响应完成之前，连接已中止。
    + = Connection may be kept alive after the response is sent. 发送响应后，连接可以保持活动状态
    - = Connection will be closed after the response is sent. 发送响应后，连接将关闭

还支持编写信息传入或传出的 headers, cookies, session或request attributes以及特殊的时间戳格式。 它是根据Apache HTTP Server日志配置语法建模的。 它们每个都可以使用不同的xxx键多次使用：

• %{xxx}i write value of incoming header with name xxx
• %{xxx}o write value of outgoing header with name xxx
• %{xxx}c write value of cookie with name xxx
• %{xxx}r write value of ServletRequest attribute with name xxx
• %{xxx}s write value of HttpSession attribute with name xxx
• %{xxx}p write local (server) port (xxx==local) or remote (client) port (xxx=remote)
• %{xxx}t write timestamp at the end of the request formatted using the enhanced SimpleDateFormat pattern xxx

％{xxx} t允许使用SimpleDateFormat支持的所有格式。 另外，添加了以下扩展名：

• sec - number of seconds since the epoch 自纪元以来的秒数
• msec - number of milliseconds since the epoch
• msec_frac - millisecond fraction

这些格式不能与同一格式标记中的SimpleDateFormat格式混合。

此外，可以定义是记录请求开始时间还是响应结束时间的时间戳：

• begin or prefix begin: chooses the request start time
• end or prefix end: chooses the response finish time

By adding multiple %{xxx}t tokens to the pattern, one can also log both timestamps.

The shorthand pattern pattern="common" corresponds to the Common Log Format defined by '%h %l %u %t "%r" %s %b'.

The shorthand pattern pattern="combined" appends the values of the Referer and User-Agent headers, each in double quotes, to the common pattern.

简单的配置的例子

tomcat访问日志格式配置，在config/server.xml里Host标签下加上

<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs/pv"
               prefix="pv" suffix=".txt"
               pattern="%{X-Forwarded-For}i|%a|%{host}i|%{yyyy-MM-dd HH:mm:ss}t|%{clientip}i|%S|%U|%{post}r|%m|%H|%s|%D|%{content-length}i|%b|%{referer}i|%{user-agent}i" 
               resolveHosts="false" fileDateFormat="yyyyMMddHH"/>

日志打印信息如下

117.136.9.10|127.0.0.1|xxx.yyy.net|2019-09-22 17:21:56|-|2C951C762525A4932C11326F78F5E85A|/favicon.ico|-|GET|HTTP/1.1|200|2|-|67646|http://xxx.yyy.net/|Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.67 Safari/537.36

2、Extended Access Log Valve

介绍

 Extended Access Log Valve扩展了 Access Log Valve类，因此使用相同的自包含日志逻辑。 这意味着它实现了许多相同的文件处理属性。 与标准AccessLogValve的主要区别在于ExtendedAccessLogValve创建的日志文件符合W3C定义的扩展日志文件格式的工作草案。

属性

 Extended Access Log Valve支持标准Access Log Valve的所有配置属性。 只有className和pattern的值不同。

Attribute	Description
className	Java class name of the implementation to use. This MUST be set to org.apache.catalina.valves.ExtendedAccessLogValve to use the extended access log valve.
pattern	A formatting layout identifying the various information fields from the request and response to be logged. See below for more information on configuring this attribute. 格式化布局，用于标识要记录的请求和响应中的各个信息字段。 有关配置此属性的更多信息，请参见下文。

pattern属性的值由格式标记组成。 一些标示需要附加前缀， 可能的前缀是c表示“客户端”，s表示“服务器”，cs表示“客户端到服务器”，sc表示“服务器到客户端”或x表示“特定于应用程序”。 

• bytes - Bytes sent, excluding HTTP headers, or '-' if zero
• c-dns - Remote host name (or IP address if enableLookups for the connector is false)
• c-ip - Remote IP address
• cs-method - Request method (GET, POST, etc.)
• cs-uri - Request URI
• cs-uri-query - Query string (prepended with a '?' if it exists)
• cs-uri-stem - Requested URL path
• date - The date in yyyy-mm-dd format for GMT
• s-dns - Local host name
• s-ip - Local IP address
• sc-status - HTTP status code of the response
• time - Time the request was served in HH:mm:ss format for GMT
• time-taken - Time (in seconds as floating point) taken to serve the request
• x-threadname - Current request thread name (can compare later with stacktraces)

对于任何x-H（XXX），将从HttpServletRequest对象调用以下方法：

• x-H(authType): getAuthType
• x-H(characterEncoding): getCharacterEncoding
• x-H(contentLength): getContentLength
• x-H(locale): getLocale
• x-H(protocol): getProtocol
• x-H(remoteUser): getRemoteUser
• x-H(requestedSessionId): getRequestedSessionId
• x-H(requestedSessionIdFromCookie): isRequestedSessionIdFromCookie
• x-H(requestedSessionIdValid): isRequestedSessionIdValid
• x-H(scheme): getScheme
• x-H(secure): isSecure

There is also support to write information about headers cookies, context, request or session attributes and request parameters.

还支持编写有关headers cookie，context， request或session属性和请求参数的信息。

• cs(XXX) for incoming request headers with name XXX
• sc(XXX) for outgoing response headers with name XXX
• x-A(XXX) for the servlet context attribute with name XXX
• x-C(XXX) for the first cookie with name XXX
• x-O(XXX) for a concatenation of all outgoing response headers with name XXX
• x-P(XXX) for the URL encoded (using UTF-8) request parameter with name XXX
• x-R(XXX) for the request attribute with name XXX
• x-S(XXX) for the session attribute with name XXX