Tomcat 10.1.19 · org.apache.catalina.valves.AbstractAccessLogValve

Abstract implementation of the Valve interface that generates a web server access log with the detailed line contents matching a configurable pattern. The syntax of the available patterns is similar to that supported by the Apache HTTP Server mod_log_config module.

Patterns for the logged message may include constant text or any of the following replacement strings, for which the corresponding information from the specified Response is substituted:

%a - Remote IP address
%A - Local IP address
%b - Bytes sent, excluding HTTP headers, or '-' if no bytes were sent
%B - Bytes sent, excluding HTTP headers
%h - Remote host name (or IP address if enableLookups for the connector is false)
%H - Request protocol
%l - Remote logical username from identd (always returns '-')
%m - Request method
%p - Local port
%q - Query string (prepended with a '?' if it exists, otherwise an empty string
%r - First line of the request
%s - HTTP status code of the response
%S - User session ID
%t - Date and time, in Common Log Format format
%u - Remote user that was authenticated
%U - Requested URL path
%v - Local server name
%D - Time taken to process the request, in microseconds
%T - Time taken to process the request, in seconds
%F - Time taken to commit the response, in milliseconds
%I - current Request thread name (can compare later with 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.

In addition, the caller can specify one of the following aliases for commonly utilized patterns:

common - %h %l %u %t "%r" %s %b
combined - %h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"

There is also support to write information from the cookie, incoming header, the Session or something else in the ServletRequest.
It is modeled after the Apache HTTP Server log configuration syntax:

%{xxx}i for incoming headers
%{xxx}o for outgoing response headers
%{xxx}c for a specific cookie
%{xxx}r xxx is an attribute in the ServletRequest
%{xxx}s xxx is an attribute in the HttpSession
%{xxx}t xxx is an enhanced SimpleDateFormat pattern (see Configuration Reference document for details on supported time patterns)
%{xxx}T xxx is the unit for the time taken to process the request (see Configuration Reference document for details on supported units)

Conditional logging is also supported. This can be done with the conditionUnless and conditionIf properties. If the value returned from ServletRequest.getAttribute(conditionUnless) yields a non-null value, the logging will be skipped. If the value returned from ServletRequest.getAttribute(conditionIf) yields the null value, the logging will be skipped. The condition attribute is synonym for conditionUnless and is provided for backwards compatibility.

For extended attributes coming from a getAttribute() call, it is you responsibility to ensure there are no newline or control characters.

Nested and Inner Type Summary

Modifier and Type	Class and Description
protected static interface	AbstractAccessLogValve.AccessLogElement AccessLogElement writes the partial message into the buffer.
protected static class	AbstractAccessLogValve.ByteSentElement write bytes sent, excluding HTTP headers - %b, %B
protected static interface	AbstractAccessLogValve.CachedElement Marks an AccessLogElement as needing to be have the value cached at the start of the request rather than just recorded at the end as the source data for the element may not be available at the end of the request.
protected static class	AbstractAccessLogValve.ConnectionStatusElement Write connection status when response is completed - %X
protected static class	AbstractAccessLogValve.CookieElement write a specific cookie - %{xxx}c
protected class	AbstractAccessLogValve.DateAndTimeElement write date and time, in configurable format (default CLF) - %t or %{format}t
protected static class	AbstractAccessLogValve.DateFormatCache Cache structure for formatted timestamps based on seconds.
protected static class	AbstractAccessLogValve.ElapsedTimeElement write time taken to process the request - %D, %T
protected static class	AbstractAccessLogValve.FirstByteTimeElement write time until first byte is written (commit time) in millis - %F
private static enum	AbstractAccessLogValve.FormatType The list of our time format types.
protected static class	AbstractAccessLogValve.HeaderElement write incoming headers - %{xxx}i
protected class	AbstractAccessLogValve.HostElement write remote host name - %h
protected static class	AbstractAccessLogValve.HttpStatusCodeElement write HTTP status code of the response - %s
protected static class	AbstractAccessLogValve.LocalAddrElement write local IP address - %A
protected class	AbstractAccessLogValve.LocalServerNameElement write local server name - %v
protected static class	AbstractAccessLogValve.LogicalUserNameElement write remote logical username from identd (always returns '-') - %l
protected static class	AbstractAccessLogValve.MethodElement write request method (GET, POST, etc.) - %m
protected class	AbstractAccessLogValve.PortElement write local or remote port for request connection - %p and %{xxx}p
private static enum	AbstractAccessLogValve.PortType The list of our port types.
protected class	AbstractAccessLogValve.ProtocolElement write request protocol - %H
protected static class	AbstractAccessLogValve.QueryElement write Query string (prepended with a '?' if it exists) - %q
protected class	AbstractAccessLogValve.RemoteAddrElement write remote IP address - %a
private static enum	AbstractAccessLogValve.RemoteAddressType The list of our ip address types.
protected static class	AbstractAccessLogValve.RequestAttributeElement write an attribute in the ServletRequest - %{xxx}r
protected static class	AbstractAccessLogValve.RequestElement write first line of the request (method and request URI) - %r
protected static class	AbstractAccessLogValve.RequestURIElement write requested URL path - %U
protected static class	AbstractAccessLogValve.ResponseHeaderElement write a specific response header - %{xxx}o
protected static class	AbstractAccessLogValve.SessionAttributeElement write an attribute in the HttpSession - %{xxx}s
protected static class	AbstractAccessLogValve.SessionIdElement write user session ID - %S
protected static class	AbstractAccessLogValve.StringElement write any string
protected static class	AbstractAccessLogValve.ThreadNameElement write thread name - %I
protected static class	AbstractAccessLogValve.UserElement write remote user that was authenticated (if any), else '-' - %u

Field Summary

Modifier and Type	Field and Description
protected AbstractAccessLogValve.CachedElement[]	cachedElements Array of elements where the value needs to be cached at the start of the request.
private SynchronizedStack<CharArrayWriter>	charArrayWriters Buffer pool used for log message generation.
protected String	condition Are we doing conditional logging.
protected String	conditionIf Are we doing conditional logging.
protected boolean	enabled enabled this component
private static final int	globalCacheSize The size of our global date format cache
private static final AbstractAccessLogValve.DateFormatCache	globalDateCache Global date format cache.
private boolean	ipv6Canonical Use IPv6 canonical representation format as defined by RFC 5952.
private static final int	localCacheSize The size of our thread local date format cache
private static final ThreadLocal<Date>	localDate The system time when we last updated the Date that this valve uses for log lines.
private static final ThreadLocal<AbstractAccessLogValve.DateFormatCache>	localDateCache Thread local date format cache.
protected Locale	locale Locale used to format timestamps in log entries and in log file name suffix.
protected String	localeName Name of locale used to format timestamps in log entries and in log file name suffix.
private static final Log	log Hides org.apache.catalina.util.LifecycleMBeanBase.log.
protected AbstractAccessLogValve.AccessLogElement[]	logElements Array of AccessLogElement, they will be used to make log message.
private int	maxLogMessageBufferSize Log message buffers are usually recycled and re-used.
protected String	pattern The pattern used to format our access log lines.
protected boolean	requestAttributesEnabled Should this valve use request attributes for IP address, hostname, protocol and port used for the request.
private boolean	tlsAttributeRequired Does the configured log pattern include a known TLS attribute?

Inherited from org.apache.catalina.valves.ValveBase:: asyncSupported container containerLog next sm

Access	Constructor and Description
public	AbstractAccessLogValve()

Method Summary

Modifier and Type	Method and Description
protected AbstractAccessLogValve.AccessLogElement	Returns: the log element createAccessLogElement(String Header name name, char char in the log pattern pattern) Create an AccessLogElement implementation which needs an element name.
protected AbstractAccessLogValve.AccessLogElement	Returns: the log element createAccessLogElement(char char in the log pattern pattern) Create an AccessLogElement implementation.
private AbstractAccessLogValve.CachedElement[]	createCachedElements(AbstractAccessLogValve.AccessLogElement[] elements)
protected AbstractAccessLogValve.AccessLogElement[]	Returns: the log elements array createLogElements() Parse pattern string and create the array of AccessLogElement.
protected static void	escapeAndAppend(String input, CharArrayWriter dest)
protected static Locale	Returns: the locale object findLocale(String The locale name name, Locale Fallback locale if the name is not found fallback) Find a locale by name.
public String	Returns: the attribute name getCondition() Return whether the attribute name to look for when performing conditional logging.
public String	Returns: the attribute name getConditionIf() Return whether the attribute name to look for when performing conditional logging.
public String	Returns: the attribute name getConditionUnless() Return whether the attribute name to look for when performing conditional logging.
private static Date	Returns: the date object getDate(long The time systime) This method returns a Date object that is accurate to within one second.
public boolean	Returns: the enabled flag. getEnabled()
public boolean	getIpv6Canonical()
public String	Returns: the locale getLocale() Return the locale used to format timestamps in log entries and in log file name suffix.
public int	getMaxLogMessageBufferSize()
public String	Returns: the format pattern. getPattern()
public boolean	getRequestAttributesEnabled() Implements org.apache.catalina.AccessLog.getRequestAttributesEnabled.
public void	invoke(Request Request being processed request, Response Response being processed response) Implements org.apache.catalina.Valve.invoke. Log a message summarizing the specified request and response, according to the format specified by the `pattern` property.
public void	log(Request Request (associated with the response) to log request, Response Response (associated with the request) to log response, long Time taken to process the request/response in nanoseconds (use 0 if not known); in Tomcat versions prior to 10, the time unit was milliseconds time) Implements org.apache.catalina.AccessLog.log. Add the request/response to the access log using the specified processing time.
protected abstract void	log(CharArrayWriter Message to be logged. This object will be recycled by the calling method. message) Log the specified message.
public void	setCondition(String Set to null to log everything condition) Set the ServletRequest.attribute to look for to perform conditional logging.
public void	setConditionIf(String Set to null to log everything condition) Set the ServletRequest.attribute to look for to perform conditional logging.
public void	setConditionUnless(String Set to null to log everything condition) Set the ServletRequest.attribute to look for to perform conditional logging.
public void	setEnabled(boolean The enabled to set. enabled)
public void	setIpv6Canonical(boolean ipv6Canonical)
public void	setLocale(String The locale to use. localeName) Set the locale used to format timestamps in log entries and in log file name suffix.
public void	setMaxLogMessageBufferSize(int maxLogMessageBufferSize)
public void	setPattern(String The new pattern pattern) Set the format pattern, first translating any recognized alias.
public void	setRequestAttributesEnabled(boolean `true` causes the attributes to be used, `false` causes the original values to be used. requestAttributesEnabled) Implements org.apache.catalina.AccessLog.setRequestAttributesEnabled. Should this valve use request attributes for IP address, hostname, protocol and port used for the request?

Inherited from org.apache.catalina.valves.ValveBase:: backgroundProcess getContainer getDomainInternal getNext getObjectNameKeyProperties initInternal isAsyncSupported setAsyncSupported setContainer setNext startInternal stopInternal toString

public abstract Class AbstractAccessLogValve

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary