java.util.logging

Logger: Application logging

You can take advantage of the JDK's logging facility to add logging to your application. Choosing a good logging name and levels are important for troubleshooting and debugging your code. Logging to much can be almost as confusing as logging too little.

The logging name should be the full class name of the class you're instrumenting. Although other schemes are possible, the class name is more maintainable.

The logging level should be consistent across your application. For Resin, we use the following level conventions:

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

public class Foo {
  private static 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.finer(this + "doFoo(" + bar + ")");

    ...

    log.info(...);

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

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: <logger 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 levels

The level for log tags matches the levels in the JDK .

<log-handler>

Configure a log handler for the JDK java.util.logging.* API. java.util.logging has two steps: configure a set of log handlers, and configure the levels for each logger. The <log-handler> creates a destination for logs, sets a minimum logging level for the handler, and attaches the handler to a logging name.

In addition to configuring custom handlers, <log-handler> has the most common configuration build-in: logging to a rotating file. Most of the configuration attributes are used for the rotating file and are shared with the other logging configuration.

element log-handler {
  archive-format?
  & class?
  & filter?
  & format?
  & formatter?
  & init?
  & level?
  & mbean-name?
  & name
  & path?
  & path-format?
  & rollover-count?
  & rollover-period?
  & rollover-size?
  & timestamp?
  & uri?
  & use-parent-handlers?
}

The following example sends warning messages to a JMS queue. The uri="jms:" is an alias for com.caucho.log.handler.JmsHandler. The uri="timestamp:" is a formatter alias for com.caucho.log.formatter.TimestampFormatter

<web-app xmlns="http://caucho.com/ns/resin">

  <jms-queue name="myQueue" uri="memory:"/>

  <log-handler name="qa.test" level="warning" uri="jms:">
    <init target="${myQueue}"/>

    <formatter uri="timestamp:"/>
  </log-handler>

</web-app>

The following example is a standard log handler writing to a rollover file. Because the handler's level is "all", the <logger> configuration will set the actual logging level.

<web-app xmlns="http://caucho.com/ns/resin">

  <jms-queue name="myQueue" uri="memory:"/>

  <log-handler name="" level="all"
       timestamp="[%Y/%m/%d %H:%M:%S.%s] {%{thread}} "/>

  <logger name="com.caucho" level="info"/>

</web-app>

<log>

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

The default archive format is

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

For example, to log everything to standard error use:

<resin xmlns="http://caucho.com/ns/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:

<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 .

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

<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

<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 

<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"

Log Handlers

Resin provides a number of predefined custom log handlers for common logging patterns, including sending messages to JMS, HMTP, and the syslog service. Creating your own custom handler is also straightforward.

<web-app xmlns="http://caucho.com/ns/resin">

  <log-handler name="com.foo" level="warning" uri="event:"/>

</web-app>

<web-app xmlns="http://caucho.com/ns/resin">

  <log-handler name="com.foo" level="warning" uri="hmtp:">
    <init>
       <to>test@localhost</to>
   </init>
  </log-handler>

</web-app>

<web-app xmlns="http://caucho.com/ns/resin">

  <jms-queue name="myQueue" uri="memory:"/>

  <log-handler name="com.foo" level="warning" uri="jms:">
    <init>
       <target>${myQueue}</target>
   </init>
  </log-handler>

</web-app>

<resin xmlns="http://caucho.com/ns/resin">

<log-handler name="" level="warning" uri="syslog:">
    <init>
      <facility>daemon</facility>
      <severity>notice</severity>
    </init>
</log-handler>

<web-app xmlns="http://caucho.com/ns/resin">

  <log-handler name="" level="warning" class="demo.MyHandler"/>
  
</web-app>

package demo;

import java.util.logging.*;

public class MyHandler extends Handler
{
  @Override
  public void publish(LogRecord record)
  {
    System.out.println(getFormatter().format(record));
  }
  
  @Override
  public void flush();
  {
  }
  
  @Override
  public void close();
  {
  }
}

Log Formatting

Sites may wish to change the formatting of log messages to gather information more appropriate for the site. The formatter can be custom-configured just like the handlers.

<web-app xmlns="http://caucho.com/ns/resin">

  <log-handler name="com.foo" level="warning" path="WEB-INF/log.log">
    <formatter class="qa.MyFormatter"/>
  </log-handler>
  
</web-app>

package demo;

import java.util.logging.*;

public class MyFormatter extends Formatter
{
  @Override
  public String format(LogRecord record)
  {
    return "[" + record.getLevel() + "] " + record.getMessage();
  }
}

Standard Output Redirection

stdout-log

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>.

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

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>.

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 logging

Log Paths

Rollovers

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:

  <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