Log
Resin 3.0

Features
Installation
Configuration
Web Applications
IOC/AOP
Resources
JSP
Quercus
Servlets and Filters
Databases
Admin (JMX)
CMP
EJB
Amber
EJB 3.0
Security
XML and XSLT
XTP
JMS
Performance
Protocols
Third-party
Troubleshooting/FAQ

index
howto
resin.conf
env
web-app
log
el control
Bean Config
Common Tasks
Relax Schema
Config FAQ
Scrapbook
web-app
Configuration
el control

Resin can perform access logging, specify where JDK logging interface messages go, and redirect the stderr and stdout for your applications.

  1. Log Configuration Tags
    1. stdout-log
    2. stderr-log
    3. access-log
    4. log
      1. Log names
      2. Use logging in applications
      3. Log levels
      4. <logger> specifies multiple names for one destination
      5. Log format string
      6. com.caucho.log.SyslogHandler
  2. Log Paths
  3. Rollovers
    1. Size based rollover
    2. Time based rollover
    3. Archive files
    4. Disabling rollovers
    5. Compression
  4. Timestamp format string

Log Configuration Tags

stdout-log

child of: resin, server, host-default, web-app-default, web-app
default: use the JDK's destination for System.out

Configure the destination for System.out.

Usage of the stdout-log overrides a previous usage. For example, specifying stdout-log as a child of a <web-app> causes a redirection of System.out for that web application only, and will override the System.out location in the enclosing <host> .

Warning: The path must not be the same as the path specified on the command line with -stdout. If it is, there will be conflicts with which process owns the file.

AttributeMeaningdefault
path Output path for the stream, see "Log Paths". required
timestamp a timestamp format string to use at the beginning of each log line. no timestamp
rollover-period how often to rollover the log. Specify in days (15D), weeks (2W), months (1M), or hours (1h). See Rollovers. none
rollover-size maximum size of the file before a rollover occurs, in bytes (50000), kb (128kb), or megabytes (10mb). See Rollovers. 1mb
archive-format the format for the archive filename when a rollover occurs, see Rollovers. see below

The default archive format is

  path + ".%Y%m%d" or
  path + ".%Y%m%d.%H" if rollover-period < 1 day.

The following example configures System.out for a <host> . Unless a web-app overrides with it's own stdout-log, all web-apps in the host will write to the same output file.

...
<host id='foo.com'>
  <stdout-log path='/var/log/foo/stdout.log'
              rollover-period='1W'/>
  ...
</host>
...
  

stderr-log

child of: resin, server, host-default, web-app-default, web-app
default: use the JDK's destination for System.err

Configure the destination for System.err.

Usage of the stderr-log overrides a previous usage. For example, specifying stderr-log as a child of a <web-app> causes a redirection of System.err for that web application only, and will override the System.err location in the enclosing <host> .

Warning: The path must not be the same as the path specified on the command line with -stderr. If it is, there will be conflicts with which process owns the file.

AttributeMeaningdefault
path Output path for the stream, see "Log Paths". required
timestamp a timestamp format string to use at the beginning of each log line. no timestamp
rollover-period how often to rollover the log. Specify in days (15D), weeks (2W), months (1M), or hours (1h). See Rollovers. none
rollover-size maximum size of the file before a rollover occurs, in bytes (50000), kb (128kb), or megabytes (10mb). See Rollovers. 1mb
archive-format the format for the archive filename when a rollover occurs, see Rollovers. see below

The default archive format is

  path + ".%Y%m%d" or
  path + ".%Y%m%d.%H" if rollover-period < 1 day.

The following example configures System.err for a <host> . Unless a web-app overrides with it's own stderr-log, all web-apps in the host will write to the same output file.

...
<host id='foo.com'>
  <stderr-log path='/var/log/foo/stderr.log'
              rollover-period='1W'/>
  ...
</host>
...

access-log

Resin 2.1

child of: server, host-default, host, web-app-default, web-app

Specify the access log file.

As a child of <web-app> , overrides the definition in the <host> that the web-app is deployed in. As a child of <host> , overrides the definition in the <server> that the host is in.

AttributeMeaningdefault
path Output path for the log entries, see "Log Paths". required
format Access log format. see below
rollover-period how often to rollover the log. Specify in days (15D), weeks (2W), months (1M), or hours (1h). See Rollovers. none
rollover-size maximum size of the file before a rollover occurs, in bytes (50000), kb (128kb), or megabytes (10mb). See Rollovers. 1mb
archive-format the format for the archive filename when a rollover occurs, see Rollovers. see below
resin:type a class extending class com.caucho.server.log.AccessLog for custom logging com.caucho.server.log.AccessLog
initbean-style initialization for the custom classn/a

The default archive format is

  path + ".%Y%m%d" or
  path + ".%Y%m%d.%H" if rollover-period < 1 day.

...
<host id=''>
  <access-log path='log/access.log'>
    <rollover-period>2W</rollover-period>
  </access-log>
  ...
</host>
...

The access log formatting variables follow the Apache variables:

%bresult content length
%hremote IP addr
%{xxx}irequest header xxx
%{xxx}oresponse header xxx
%{xxx}ccookie value xxx
%nrequest attribute
%rrequest URL
%sstatus code
%{xxx}trequest date with optional time format string.
%Ttime of request in seconds
%Dtime of request in microseconds (3.0.16)
%uremote user
%Urequest URI

The default format is:

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

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

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

log

child of: resin, server, host-default, host, web-app-default, web-app

Configure the amount and destination of debug logging for the JDK java.util.logging.* API.

AttributeMeaningdefault
name A hierarchical name, typically aligned with the Java packaging names match all names
level The log level info
path Output path for the log messages, see "Log Paths" required
timestamp a timestamp format string to use at the beginning of each log line. "[%Y/%m/%d %H:%M:%S.%s] "
format a format string to control the output of each log message. Since Resin 3.0.5. ${log.message}
rollover-period how often to rollover the log. Specify in days (15D), weeks (2W), months (1M), or hours (1h). See Rollovers. none
rollover-size maximum size of the file before a rollover occurs, in bytes (50000), kb (128kb), or megabytes (10mb). See Rollovers. 1mb
archive-format the format for the archive filename when a rollover occurs, see Rollovers. see below
mbean-name an mbean name, see MBean control. no mbean name, no mbean registration
handler add a custom Handler, the name of a class that extends class java.util.logging.Handler  
formatter set a custom Formatter, the name of a class that extends class java.util.logging.Formatter none, or class com.caucho.log.ELFormatter if format is used.

The default archive format is

  path + ".%Y%m%d" or
  path + ".%Y%m%d.%H" if rollover-period < 1 day.

For example, to log everything to standard error use:

<resin>
  <log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"/>
  ...
</resin>

A useful technique is to enable full debug logging to track down a problem:

debug logging

<resin>
  ...
  <log name='' level='finer' path='log/debug.log'
       timestamp="[%H:%M:%S.%s]"
       rollover-period='1h' rollover-count='1'/>
  ...
</resin>

More examples of debug logging are in the Troubleshooting section.

The class that corresponds to <log> is class com.caucho.log.LogConfig .

Log names

The JDK logging api uses a hierarchical naming scheme. Typically the name is aligned with a java class name. When you specify a name, all logging requests that use a name that starts with the name you have specified are matched. For example: <log name="example.hogwarts" ...> matches a logging request for both "example.hogwarts.System" and "example.hogwarts.gryffindor.System"

Resin's logging is based on Resin's source class names. The following are useful logs.

log name valueMeaning
""Debug everything
com.caucho.jspDebug jsp
com.caucho.javaJava compilation
com.caucho.xslXSL debugging
com.caucho.server.portTCP port debugging and threading
com.caucho.server.port.AcceptPoolport thread creation
com.caucho.server.httpHTTP-related debugging
com.caucho.server.webappweb-app related debugging
com.caucho.server.cacheCache related debugging
com.caucho.sqlDatabase pooling
com.caucho.transactionTransaction handling
com.caucho.ejbEJB handling

Use logging in applications

You can take advantage of the JDK's logging facility to add logging to your application. It's a good idea to keep such log messages in your code, when your application goes into production you can set the log level to warn; if problem's occur you can set it to finest and still have all of the information you need to troubleshoot.

import java.util.logging.Logger;
import java.util.logging.Level;

public class Foo {
  static protected final Logger log = 
    Logger.getLogger(Foo.class.getName());

  ...
  void doFoo(String bar)
  {
    // check for log level if your logging call does anything more
    // than pass parameters
    if (log.isLoggable(Level.FINER))
        log.entering("Foo","doFoo()", new Object[] { bar });
    ...

    log.info(...);

    try {
        ...
    } catch (ExpectedException ex) {
      log.log(Level.FINE, "expected exception", ex);
    }
  }
  ...
}

Log levels

The level for log tags matches the levels in the JDK class java.util.logging.Level .

NameAPIMeaning
off turn off logging
severelog.severe("...")a serious failure, likely to prevent normal program execution
warninglog.warning("...")a potential problem
infolog.info("...")informational messages
configlog.config("...")static configuration messages, meant to assist in debugging problems associated with particular configurations
finelog.fine("...")tracing information
finerlog.finer("...")fairly detailed tracing message
finestlog.finest("...")highly detailed tracing message
all all messages should be logged

<logger> specifies multiple names for one destination

<log> can contain multiple <logger> entries.

multiple log
<resin>
  <!-- log request and response info -->
  <log path='stdout:' timestamp='[%H:%M:%S.%s] '>
    <logger name="com.caucho.server.port.TcpConnection" level="fine"/>
    <logger name="com.caucho.server.http.HttpRequest" level="fine"/>
    <logger name="com.caucho.server.connection.AbstractHttpResponse" level="fine"/>
  </log>

  ...
</resin>

Log format string

The format for log tags is used to specify a format string for each log message. format recognizes EL-expressions. The EL variable log is a class com.caucho.log.ELFormatter.ELFormatterLogRecord object.

log format string

<log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"
     format=" ${log.level} ${log.loggerName} ${log.message}"/>

log EL variable `log' is a LogRecord
AccessorValue
${log.level}The level of the log record
${log.name}The source loggers name
${log.shortName}A shorter version of the source loggers name, "Foo" instead of "com.hogwarts.Foo"
${log.message}The message, with no formatting or localization
${log.millis}event time in milliseconds since 1970
${log.sourceClassName}Get the name of the class that issued the logging request (may not be available at runtime)
${log.sourceMethodName}Get the name of the method that issued the logging request (may not be available at runtime)
${log.threadID}Get an int identifier of the thread where the logging request originated
${log.thrown}Get any class java.lang.Throwable associated with the logging request

You can also use the Environment EL variables in your format string:

log format string using an Environment EL variable.
<host ...>

  <web-app>
    <log name='' level='all' path='log/debug.log' timestamp="[%H:%M:%S.%s]"
         format=" [${app.contextPath}] ${log.message}"/>

    ...
  </web-app>

  ...

</host>

[14:55:10.189] [/foo] `null' returning JNDI java:
       model for EnvironmentClassLoader[web-app:http://localhost:8080/foo]
[14:55:10.189] [/foo] JNDI lookup `java:comp/env/caucho/auth'
       exception javax.naming.NameNotFoundException: java:comp/env/caucho/auth
[14:55:10.199] [/foo] Application[http://localhost:8080/foo] starting

The fmt.sprintf() function can space pad the values and make the results look a little nicer:

fmt.sprintf() in log format string
<log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"
     format=" ${fmt.sprintf('%-7s %45s %s',log.level,log.loggerName,log.message)}"/>

[14:28:08.137] INFO com.caucho.vfs.QJniServerSocket Loaded Socket JNI library.
[14:28:08.137] INFO com.caucho.server.port.Port http listening to *:8080
[14:28:08.137] INFO com.caucho.server.resin.ServletServer ServletServer[] starting
[14:28:08.307] INFO com.caucho.server.port.Port hmux listening to localhost:6802
[14:28:08.437] INFO com.caucho.server.host.Host Host[] starting 

fmt.sprintf() and fmt.timestamp() can be used to produce CSV files:

CSV log files
<log name='' level='all' path='log/debug.csv' timestamp=""
     format="${fmt.sprintf('%vs,%d,%d,%vs,%vs',fmt.timestamp('%Y-%m-%d %H:%M:%S.%s'), 
               log.threadID, log.level.intLevel(), log.loggerName, log.message)}"/>

"2003-11-17 14:46:14.529",10,800,"com.caucho.vfs.QJniServerSocket",
            "Loaded Socket JNI library."
"2003-11-17 14:46:14.549",10,800,"com.caucho.server.port.Port",
            "http listening to *:8080"
"2003-11-17 14:46:14.549",10,800,"com.caucho.server.resin.ServletServer",
            "ServletServer[] starting"
"2003-11-17 14:46:14.719",10,800,"com.caucho.server.port.Port",
            "hmux listening to localhost:6802"
"2003-11-17 14:46:14.850",10,800,"com.caucho.server.host.Host",
            "Host[] starting"
"2003-11-17 14:46:15.100",10,800,"com.caucho.server.webapp.Application",
            "Application[http://localhost:8080/freelistbm] starting"

com.caucho.log.SyslogHandler

On Unix systems, the SyslogHandler lets you log messages to syslog.

<log name="" level="warning">
  <handler resin:type="com.caucho.log.SyslogHandler">
    <facility>daemon</facility>
    <severity>notice</severity>
  </handler>
</log>

The possible values for facility are user, mail, daemon, auth, lpr, news, uucp, cron, authpriv, ftp, local0, local1, local2, local3, local4, local5, local6, local7. The default is daemon.

The possible values for severity are emerg, alert, crit, err, warning, notice, info, debug. The default is info.

See also `man 3 syslog' and `man syslog.conf'.

Log Paths

path is used to configure a destination for the messages. Typically, access-log, stdout-log, and stderr-log are configured to go to files, and log is configured to go to a file or to stderr or stdout so that they show up on the console screen.

PathResult
filesystem pathoutput log entries to a file
stdout:output log entries to stdout
stderr:output log entries to stderr

Log messages to stdout
  <log name="" level="all" path="stdout:"/>

You can use the Environment EL variables as part of your filesystem path:

Filesystem path using Environment EL variables
  <log name="" level="all" 
       path="log/debug-${server.id}.log"
       rollover-period="1h" rollover-count="1"/>

Rollovers

Log rollovers are a way to stop your log files from getting too large. When a rollover is triggered, the existing log file is renamed and a new file is started.

Size based rollover

A size based rollover is triggered when the size of the file reaches a certain amount. The default Resin behaviour for log's is to rollover when the file size reaches 1mb.

rollover-size is used to specify the maximum size, and can be in bytes (50000), kilobytes (128kb), or megabytes (10mb). A value of -1 disables size based rollovers.

Time based rollover

A time based rollover is triggered when a certain period of time has passed since the last rollover. The default Resin behaviour is to perform no time based rollover, unless rollover-size has been disabled with a value of -1 in which case the default time period is 1 month.

rollover-period is used to specify the time period, and can be in days (15D), weeks (2W), months (1M), or hours (1h).

Archive files

When a rollover is triggered, the log file is renamed (archived) and a new log file is started.

archive-format is used to specify the name of the archive file. It can contain regular characters, EL Environment variables , and % codes that capture the current date and time. The % codes are the same as the ones used for timestamp (see Timestamp format string).

The default behaviour depends on the value of rollover-period. If rollover-period is greater than one day, or is not being used because rollover-size has been specified, the archive filename is the original path with .%Y%m%d appended. If rollover-period is less than one day, the archive filename is the original path with .%Y%m%d.%H appended.

Disabling rollovers

To completely disable rollovers, set the rollover-size to such a high number that it will never occur:

disable log rollovers
  <stdout-log path="log//stdout.log" rollover-size="1024mb"/>

Compression

Rollover log files can be compressed with gzip or zip. The extension of the archive-format determines the compression.

<log name="" level="warning" path='log/error.log'
     archive-format="%Y-%m-%d.error.log.gz"
     rollover-period="1D"/>

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

Timestamp format string

The timestamp for log tags is a format string which can contain percent codes which are substituted with time and date values.

CodeMeaning
%aday of week (short)
%Aday of week (verbose)
%bday of month (short)
%Bday of month (verbose)
%cJava locale date
%dday of month (two-digit)
%H24-hour (two-digit)
%I12-hour (two-digit)
%jday of year (three-digit)
%mmonth (two-digit)
%Mminutes
%pam/pm
%Sseconds
%smilliseconds
%Wweek in year (three-digit)
%wday of week (one-digit)
%yyear (two-digit)
%Yyear (four-digit)
%Ztime zone (name)
%ztime zone (+/-0800)

typical timestamp for the log tag
    <log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"/>

[22:50:11.648] Application[/doc] starting
[22:50:11.698] http listening to *:8080
[22:50:11.828] hmux listening to *:6802


web-app
Configuration
el control
Copyright © 1998-2006 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.