This article describes the configuration of the access log for Apache Tomcat 7 web server.
A web server has the function to intercept user requests to resources, examine them and log them. This is an activity of web server administration.
Tomcat provides components called valves that can be placed in the request-processing stream (intercept user requests) for logging access to resources. This is a Tomcat specific interception mechanism.
Tomcat supplies the following standard valves for:
- Access logging
- Single sign-on for all web applications running on the server
- Request filtering/blocking by IP address and host name
- Detailed request dumps for debugging
Valves are specific to Tomcat and are not part of the Java Servlet specification. Web applications use filters as a similar interception mechanism; they are part of the Servlet specification and are defined for a web application. This article has details about access logging valves.
1. Access Log Valve
Access log valve logs requests. Access logs can be analyzed by standard log analysis tools to track page hit counts, user session activity, and so on.
An access log valve is not a logger. This does not use Apache Commons Logging (Tomcat’s default logging mechanism). This Valve may be associated with any Catalina container – Context, Host, or Engine. The valve records all the requests processed by that container.
Valves are nested components in the Tomcat configuration hierarchy and can be placed inside <Engine>, <Host>, or <Context> containers of
CATALINA_HOME\conf\server.xml configuration file. Each element has 0 or more Valve sub-elements.
NOTE: CATALINA_HOME environment variable is the Tomcat installation directory (conventionally named “apache-tomcat-[version]”).
2. Configuring Access Log Valve
The Access Log Valve entry in
server.xml looks like this for the engine, host or the context:
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log." suffix=".txt" pattern="common" resolveHosts="false"/>
2.1. The Attributes for the Standard Access Log Valve
className attribute represents the Java class of the valve. This must be
org.apache.catalina.valves.AccessLogValve. This is a mandatory attribute. All other attributes for the valve are optional.
A complete list of all the attributes and their descriptions are found at: Apache Tomcat 7 Configuration Reference – The Valve Component Attributes
2.2. The Access Log File
The access log output file will be placed in the directory given by the “directory” attribute (default value is
CATALINA_BASE/logs). The name of the file is composed by concatenation of the configured “prefix” (default value is “access_log.”) and “suffix” (default value is zero length string – “”) attributes. The format of the timestamp in the file name can be set using the “fileDateFormat” attribute (default value is “yyyy-MM-dd”). This timestamp will be omitted if the file rotation is switched off by setting “rotatable” to “false” (default value is “true”).
The typical default log file name is:
NOTE: CATALINA_BASE environment variable specifies location of the root directory of the “active configuration” of Tomcat. It is optional to define this variable. By default it is equal to CATALINA_HOME.
2.3. Valve Chaining
Valves can be chained together to work in conjunction with each other so that requests go through more than one filter before reaching their destinations. For example, a valve configured at the engine level will intercept all requests to contexts on this engine, no matter what host or context they are bound for.
3. An Example Access Log Valve
This shows an example access log valve, log file and examines some of its attributes. This is the default configuration example as found in Tomcat 7 new installation.
Navigate to the
CATALINA_HOME\conf\server.xml, and the
localhost entry. The following is found:
<Engine name="Catalina" defaultHost="localhost"> ... <Host name="localhost" ... <!-- Access log processes all example. Documentation at: /docs/config/valve.html Note: The pattern used is equivalent to using pattern="common" --> <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log." suffix=".txt" pattern="%h %l %u %t "%r" %s %b" /> </Host> </Engine>
In case the Valve entry is commented, un-comment this, start (or restart) Tomcat. Point a web browser to http:// localhost:8080; this shows the default Tomcat welcome page.
The above configuration will create log files, in the common format, in
CATALINA_HOME/logs directory. Now examine the directory, and open the “localhost_access_log.DATE.txt” (for example, “localhost_access_log.2015-02-24.txt”) file. This is the access log. Note that from the file name the log file Valve attributes “prefix” is “localhost_access_log.”, “fileDateFormat” is “YYYY-MM-DD” and the “suffix” is “.txt”.
The access log has entries for the accessed web page and also for the associated image files. This is in the common log file format as shown below:
0:0:0:0:0:0:0:1 - - [24/Feb/2015:14:06:41 +0530] "GET / HTTP/1.1" 200 11418 0:0:0:0:0:0:0:1 - - [24/Feb/2015:14:06:41 +0530] "GET /tomcat.css HTTP/1.1" 200 5926 0:0:0:0:0:0:0:1 - - [24/Feb/2015:14:06:41 +0530] "GET /favicon.ico HTTP/1.1" 200 21630 0:0:0:0:0:0:0:1 - - [24/Feb/2015:14:06:41 +0530] "GET /tomcat.png HTTP/1.1" 200 5103 0:0:0:0:0:0:0:1 - - [24/Feb/2015:14:06:41 +0530] "GET /bg-nav.png HTTP/1.1" 200 1401 ... 0:0:0:0:0:0:0:1 - - [24/Feb/2015:14:06:45 +0530] "GET /docs/ HTTP/1.1" 200 19367 0:0:0:0:0:0:0:1 - - [24/Feb/2015:14:06:45 +0530] "GET /docs/images/asf-logo.gif HTTP/1.1" 200 7279 0:0:0:0:0:0:0:1 - - [24/Feb/2015:14:06:45 +0530] "GET /docs/images/tomcat.gif HTTP/1.1" 200 2066 0:0:0:0:0:0:0:1 - - [24/Feb/2015:14:06:52 +0530] "GET /docs/logging.html HTTP/1.1" 200 38251 0:0:0:0:0:0:0:1 - - [24/Feb/2015:14:23:58 +0530] "GET /docs/config/valve.html HTTP/1.1" 200 111016 0:0:0:0:0:0:0:1 - - [24/Feb/2015:15:56:41 +0530] "GET /docs/index.html HTTP/1.1" 200 19367 0:0:0:0:0:0:0:1 - - [24/Feb/2015:15:56:51 +0530] "GET / HTTP/1.1" 200 11418 0:0:0:0:0:0:0:1 - - [24/Feb/2015:15:57:02 +0530] "GET /manager/html HTTP/1.1" 401 2538 0:0:0:0:0:0:0:1 - admin [24/Feb/2015:15:57:10 +0530] "GET /manager/html HTTP/1.1" 200 15829 0:0:0:0:0:0:0:1 - admin [24/Feb/2015:15:57:10 +0530] "GET /manager/images/tomcat.gif HTTP/1.1" 200 2066 0:0:0:0:0:0:0:1 - admin [24/Feb/2015:15:57:10 +0530] "GET /manager/images/asf-logo.gif HTTP/1.1" 200 7279
In the valve configuration – the Valve attribute pattern=”%h %l %u %t “%r” %s %b” defined above is the same as pattern=”common” which corresponds to the Common Log Format. The details of the pattern codes are as follows:
- %h – Remote hostname (or IP address if the resolveHosts attribute is set to false; by default the value is false).
- %l – Remote logical user name; this is always a hyphen (-).
- %u – Remote user that has been authenticated. In the example, “admin” and a hyphen (-). If there is none, it’s a hyphen (-).
- %t – Date and time in common log file format.
- %r – The first line of the request. In the example, “GET / HTTP/1.1” (note that this is configured to be shown within quotes (“”)).
- %s – The HTTP status code of the response. In the example 200 is the OK status.
- %b – Bytes sent count, excluding HTTP headers, and shows a hyphen (-) if zero.
NOTE: See the above section 2.1. The Attributes for the Standard Access Log Valve for a link pointing to the complete list of the attributes.