Logging

Resin Configuration is at http://www.caucho.com/resin-3.0/config/log.xtp

Resin's <access-log> configures the URL access logging. Its <log> configures the [java.util.logging] output. Both share much of the common configuration.

See Also

Redirecting Standard Output

rollover tags

<access-log> shares the rollover configuration with the <log>.

Log Rollover

archive-format and path-format

archive-format and path-format are two mutually exclusive methods for archiving logs. path-format writes directly to the archive log, e.g. archive-2005-01-02.log. archive-format first writes to a log specified by path, e.g. access.log and then copies the access.log to the archive name at rollover time.

archive-format uses the Date Format Configuration and Period Configuration syntax, for example:

...
<host id="www.foo.com">
   <access-log path-format="/var/www/log/%Y/%m/%d.access.log"
               rollover-period="1D"/>
   ... 
</host>
...

The archive-format can use a *.gz or *.zip extension to indicate that the archived log should be compressed. Currently, path-format cannot be compressed.

<access-log path="log/access.log"
            archive-path="/var/www/log/access.log.%Y%m%d.gz"
            rollover-period="1D"/>

access-log

An access-log receives output describing each request received by the server. It is commonly used in conjunction with analyzing tools to determine statistics and patterns of use for a website.

The access-log directive controls the information Resin writes with each request. It can appear in any environment (i.e. within a server, host, or web-app).

directives

directive	meaning	default
auto-flush	flush after each log entry	false
path	output path for the stream	either path-format or path is required
path-format	the name of a file to write the log to, date format escape sequences are replaced with the current date and time	either path or path-format is required
rollover-period	how often to rollover the log. Specify a period in days (15D), weeks (2W), months (1M), or hours (1h)	none
rollover-size	maximum size of the file before a rollover occurs. Specify a size in bytes (50000), kb (128kb), or megabytes (10mb)	1mb
archive-format	the format for the archive filename when a rollover occurs	path + ".%Y%m%d" or path + ".%Y%m%d.%H" if rollover-period < 1 day

format

code	meaning
%b	content length
%h	remote IP address
%\{xxx}i	request header xxx
%\{xxx}o	response header xxx
%\{xxx}c	cookie value xxx
%\{xxx}n	request attribute
%r	request URL
%s	status code
%\{xxx}t	date with optional time format
%T	time of request in seconds
%D	time of request in microseconds (3.0.15)
%u	remote user
%U	request URL
%l	Not used. Recognized but always results in "-"

Custom log handlers

resin:type allows for custom logging. Applications can extend a custom class from com.caucho.http.log.AccessLog. Bean-style initialization can be used to set bean parameters in the custom class.

The followng example shows the configuration for a theoretical test.MyLog class that extends com.caucho.http.log.AccessLog. Since the configuration is contained within a host, the test/Mylog.class must be available in the class-loader for the host.

...
<host>
  <access-log resin:type='test.MyLog'>
             path='$server-root/foo/error.log'
             rollover-period='1W'>
    <init>
      <foo>bar</foo>
    </init>
  </access-log>
  ...

See also

Logging 

A general overview of logging facilities in Resin

The <access-log> tag controls the information Resin prints with each request. It can appear in any of the <server>, <host>, or <web-app environments.

<access-log path="logs/access.log"
            format='%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i"'
            rollover-period="1W"/>

access-log format tags

code	meaning
%b	content length
%h	remote IP address
%\{xxx}i	request header xxx
%\{xxx}o	response header xxx
%\{xxx}c	cookie value xxx
%n	request attribute
%r	request URL
%s	status code
%\{xxx}t	date with optional time format
%T	time of request in seconds
%D	time of request in microseconds (3.0.15)
%u	remote user
%U	request URL

<log>

The <log> tag configures java.util.logging output. It can appear in any Environment.

By convention, the name of a logger is the class of the Java file that's logging, e.g. "com.caucho.server.port.Port".

attribute	meaning	default
name	logging name	required
level	java.util.logging level	info
timestamp	a timestamp to be used for logging	none
use-parent-handlers	if true, also write to the parent	true
handler	add a custom handler
formatter	add a custom formatter
mbean-name	save in jmx
path	output path (see above)	required
path-format	formatted path (see above)
archive-format	format of the archive (see above)
rollover-period	how often to rollover (see above)
rollover-size	how large a file before rolling over (see above)

The timestamp uses the Date Format Configuration syntax.

package com.foo;

import java.util.logging.Logger;

public class Test {
  private static final Logger log
    = Logger.getLogger(Test.class.getName());

  public void doStuff()
  {
    log.fine("doing stuff");
  }
}

<resin xmlns="http://caucho.com/ns/resin">
  <log name="com.foo" level="fine" path="log/debug.log"
       timestamp="[%H:%M:%S] "/>
  ...
</resin>

Conventions on logging levels:

level	use
warning	fatal errors
info	information for a typical install
fine	debug information useful for users
finer	debug information useful for developers

For example, level="fine" for "com.caucho" will give the information most generally useful for Resin uses, while level="finer" will add more information that's more detailed for the Caucho developers. level="info" is infrequent, giving significant information like the server starting.

Some Resin Logging Names have been documented.

stdout-log and stderr-log

Resin can redirect the output of System.out and System.err using the <stdout-log> and <stderr-log> configuration in any Environment. The <stdout-log> and <stderr-log> use the same configuration as the <log> for rollover and archive paths.