Log

This article requires cleanup and may refer to a legacy version of Resin. Please visit http://www.caucho.com/documentation/ for the most up-to-date documentation.

The log directive configures java.util.logging output. It can appear in any environment.

Directives

directive	meaning	default
name	logging name	required, "" matches all names
level	severe, warning, info, config, fine, finer, finest	info
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
timestamp	a timestamp in date format to use at the beginning of each log line.	no timestamp
format	a format string for each log message	just the log message
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

Level

Conventions on logging levels:

level	use
severe	a serious failure, likely to prevent normal program execution
warning	an unexpected error that indicates there is a problem, program execution may or may not continue
info	information for a typical install
config	static configuration messages, meant to assist in debugging problems associated with particular configurations
fine	debug information useful for users
finer	debug information useful for developers
finest	verbose debug information useful for developers of a particular module

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

Name

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

This article requires cleanup and may refer to a legacy version of Resin. Please visit http://www.caucho.com/documentation/ for the most up-to-date documentation.

Resin's logging convention uses the class name to as the java.util.logging name.

name	meaning
com.caucho	all Caucho logging
com.caucho.server.port	Port listening and accepts
com.caucho.server.cache	proxy caching
com.caucho.server.session	sessions
com.caucho.server.cluster	clustering and persistent sessions
com.caucho.server.webapp	<web-app> support
com.caucho.server.host	<host> support
com.caucho.server.e_app	.ear file support
com.caucho.server.resin	top-level container support, i.e. <resin> and <server>
com.caucho.server.http	http protocol support
com.caucho.server.security	authentication
com.caucho.jca	JCA pooling
com.caucho.sql	Database pooling (also see com.caucho.jca)
com.caucho.java	Internal compilation
com.caucho.jsp	JSP
com.caucho.amber	Amber
com.caucho.ejb	EJB
com.caucho.jmx	JMX
com.caucho.loader	Class Loading
com.caucho.jms	JMS

Multiple names for one destination

log can contain multiple logger directives:

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

Environments

log can appear in any environment (i.e. within a server, host, or web-app).

resin-web.xml

<web-app xmlns="http://caucho.com/ns/resin">
   <log name="com.caucho.server.webapp"
           level="warning"
           path="WEB-INF/logs/error-log"/>

  ...
</web-app>

format

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 com.caucho.log.ELFormatter.ELFormatterLogRecord.

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

accessor	value
${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 java.lang.Throwable associated with the logging request

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

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

[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[1] starting

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

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

<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[2] starting"

Unix syslog

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

Example logging usage in your application

Application developers can take advantage of the JDK logging facilities and Resin's flexible handling of log messages.

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>

See also

Logging 

A general overview of logging facilities in Resin