Creating Custom Logs

Contents

/ Index

/ Glossary

/ Administration Tool Help

There are many compelling reasons to modify log formats. Fortunately, the Java Web Server^(TM) was designed in such a way that this customization is possible. However, customizing log formats produced by the server is not a supported action--here's why.

The procedure for modifying server logs:

Can be tricky to do correctly.
In testing we discovered that, while our design for this was powerful, it was tricky to use and did not tolerate errors well. Since logging is performed on every operation of the server, it was possible to vastly decrease performance, or even lock up the server, with simple programming errors.

Requires the use of undocumented classes.
Although these classes merely extend the functionality of documented public classes, there is the opportunity for confusion.

However, because so many people have asked to have more control over how log files work, we've written these cookbook-style instructions. We hope you will find them helpful should you ever need to customize log output in the Java Web Server.

Procedure for Customizing a Java Web Server Log

To modify your server logs, perform the following steps:

Choose the log
Write the custom format class
Install the edited class
Modify the format class property
Test your changes

Each of these steps is explained in more detail below. An example illustrating the procedure is also provided at the end of this document.

Step 1: Choose the Log

The first step is to actually choose the log whose format you wish to change. In the Java Web Server 2.0, you have several choices. Typically, users want to override the access log, to include more data. However, depending on need it may be simpler and safer to override one of the other logs.

Type Filename Information recorded Default

Access access_log For every access to server resources, the details. on

Agent agent_log For every http request, contains the datestamp and the contents of the User-Agent header. off

Combined combined_log Same as access log, but with agent, referer, and server information added. off

Error error_log For selected server errors, contains the datestamp and a stack dump. off

Event event_log For selected server events, contains the datestamp and a message. off

Referer referer_log For every http request, contains the datestamp and the contents of the Referer header. off

Type	Filename	Information recorded	Default
Access	access_log	For every access to server resources, the details.	on
Agent	agent_log	For every http request, contains the datestamp and the contents of the User-Agent header.	off
Combined	combined_log	Same as access log, but with agent, referer, and server information added.	off
Error	error_log	For selected server errors, contains the datestamp and a stack dump.	off
Event	event_log	For selected server events, contains the datestamp and a message.	off
Referer	referer_log	For every http request, contains the datestamp and the contents of the Referer header.	off

Step 2: Write the custom formatclass

All logging functions are controlled by properties. The property name that we are interested in is called formatclass, and is found in the system properties in a format like this:

log.logname.formatclass=classname

where logname is the internal name of the log concerned, and classname is the fully-qualified packagename of the class.

As an example of this in use, the default formatclass for access logs is:

log.access.formatclass=com.sun.server.log.http.HttpLog

while the default formatclass for error logs is:

log.error.formatclass=com.sun.server.log.TraceLog

To write the formatclass, you need to subclass the base class that the log expects, and override the implementation of write() that that class supports. Here's a table of information you need to know:

Log Name Class to extend method to override

access com.sun.server.log.http.HttpLog write(sun.servlet.http.ServletRequest req, sun.servlet.http.ServletResponse res)

agent com.sun.server.webserver.AgentLog write(sun.servlet.http.ServletRequest req, sun.servlet.http.ServletResponse res)

combined

error com.sun.server.log.TraceLog write(String message) or write(int level, String message)

event com.sun.server.log.TraceLog write(String message) or write(int level, String message)

referer com.sun.server.webserver.RefererLog write(sun.servlet.http.ServletRequest req, sun.servlet.http.ServletResponse res)

Log Name	Class to extend	method to override
access	com.sun.server.log.http.HttpLog	write(sun.servlet.http.ServletRequest req, sun.servlet.http.ServletResponse res)
agent	com.sun.server.webserver.AgentLog	write(sun.servlet.http.ServletRequest req, sun.servlet.http.ServletResponse res)
combined
error	com.sun.server.log.TraceLog	write(String message) or write(int level, String message)
event	com.sun.server.log.TraceLog	write(String message) or write(int level, String message)
referer	com.sun.server.webserver.RefererLog	write(sun.servlet.http.ServletRequest req, sun.servlet.http.ServletResponse res)

Step 3: Install the edited class

When the class is compiled, be certain to place it somewhere in the server's class path. Typically, this will be the server_root/classes directory which the server uses by default for user-supplied classes .

Step 4: Modify the formatclass property

Edit the systemDefaults.properties file for the server you wish to modify. Typically, it will be javawebserver, but your site may have customized this name. Change the entry for formatclass to your custom class name.

Step 5: Test your changes

Testing is an important step that shouldn't be overlooked. Remember, this code will be called for every request, so it needs to be high performance code. Errors in the code could cause failures up to and including truncated return data ("Document contains no data" in Netscape's browser). If that happens, not even a return code will get back to the client.

Caveats

The code should be threadsafe.
The code should not perform any synchronized actions.
The code should avoid heavy string manipulation.
The code should avoid network access.

Example

Suppose we want to include information about what URL each agent visited. Let's walk through the required steps:

Choose a log.
Sounds like we want to modify the agent log for the Java Web Server's web page service.

Write the custom-format class.
Here's the class we could use:

import sun.servlet.http.*;

public class MyAgentLog extends com.sun.server.webserver.AgentLog {

    public MyAgentLog() {
	super();
    }

    public AgentLog(OutputStream out) {
	super(out);
    }

    public void write(HttpRequest req, HttpResponse) {
       if (getLevel() > 0) {
            synchronized (this) {
                try {
                    print(req.getRequestURI());
                    print(" ");
                    req.getHeader("User-Agent");
                    println(req.getHeader("User-Agent"));
                } catch (IOException e) {
                    System.err.println("AgentLog.write() : " + e);
                }
            }
        }
    }
  
}

Install the edited class.
We can copy the file to the server_root/classes directory -- that directory is included in the Java Web Server's classpath by default. (server_root is the full path to where the Java Web Server is installed.)

Edit the format class properties file.
For this example, the file we edit would be:
server_root/properties/javawebserver/systemDefaults.properties

where server_root is the full path to where the Java Web Server is installed.
In the file, we would change the line
log.agent.formatclass=com.sun.server.webserver.AgentLog

to read

log.agent.formatclass=myAgentLog

Test the changes.
Note: The agent log for the Java Web Server's webpage service will be created as:
server_root/logs/javawebserver/webpageservice/agent_log
where server_root is the full path to where the Java Web Server is installed.

Top

java-server-feedback@java.sun.com