ZK Developer's Guide/Beyond zk/Logger

This documentation is for an older version of ZK. For the latest one, please click here.

Package: Log

The logger used by ZK is based on the standard logger, java.util.Logger. However, we wrap it as Log to make it more efficient. The typical use is as follows.

 import org.zkoss.util.logging.Log;
 class MyClass {
     private static final Log log = Log.lookup(MyClass.class);
     public void f(Object v) {
         if (log.debugable()) log.debug("Value is "+v);
     }
 }

Since ZK uses the standard logger to log message, you could control what to log by configuring the logging of the Web server you are using. How to configure the logging of the Web server varies from one server to another. Please consult the manuals. Or, you might use the logging configuration mechanism provided by ZK as described below.

Note: By default, all ZK log instances are mapped to the same Java logger named org.zkoss to have the better performance. If you want to control the log level up to individual class, you have to invoke the following statement to turn on the hierarchy support.

Log.setHierarchy(true);

Note: The hierarchy support is enabled automatically, if you configure the log level with WEB-INF/zk.xml as described in the following section.

How to Configure Log Levels with ZK

In addition to configuring the logging of the Web server, you can use the logging configuration mechanism provided by ZK. By default, it is disabled. To enable it, you have to specify the following content in WEB-INF/zk.xml. Refer to ZK Configuration Reference fore more details.

<zk>
    <log>
    <log-base>org.zkoss</log-base>
    </log>
</zk>

Alternatively, you can enable the logging configuration mechanism manually by invoking the init method of LogService as follows.

 org.zkoss.util.logging.LogService.init("org.zkoss", null);

If you want to log not just org.zkoss but also everything, you could specify an empty value for log-base.

Once the mechanism is enabled, ZK looks for i3-log.conf by searching the classpath at start-up and some particular locations (see below). If found, ZK loads its content to initialize the log levels. Then, ZK keeps watching this file, and reloads its content if the file is modified.

Content of i3-log.conf

An example of i3-log.conf is as follows.

 org.zkoss.zk.ui.impl.UiEngineImpl=FINER
    #Make the log level of the specified class to FINER
 org.zkoss.zk.ui.http=DEBUG
    #Make the log level of the specified package to DEBUG
 org.zkoss.zk.au.http.DHtmlUpdateServlet=INHERIT
    #Clear the log level of a specified class such that it inherits what
    #has been defined above (Default: INFO)
 org.zkoss.zk.ui=OFF
    #Turn off the log for the specified package
 org.zkoss=WARNING
    #Make all log levels of ZK classes to WARNING except those specified here

Allowed Levels

Level	Description
OFF	Indicates no message at all.
ERROR	Indicates providing error messages.
WARNING	Indicates providing warning messages. It also implies ERROR.
INFO	Indicates providing informational messages. It also implies ERROR and WARNING.
DEBUG	Indicates providing tracing information for debugging purpose. It also implies ERROR, WARNING and INFO.
FINER	Indicates providing fairly detailed tracing information for debugging purpose. It also implies ERROR, WARNING, INFO and DEBUG
INHERIT	Indicates to clear any level being set to the specified package or class. In other words, the log level will be the same as its parent node.

Location of i3-log.conf

At first, ZK looks for this file in the classpath. If not found, it looks for the conf directory.

Application Server	Location
Tomcat	Place i3-log.conf under the $TOMCAT_HOME/conf directory
Others	Try the conf directory first. If not working, you could set the system property called the org.zkoss.io.conf.dir directory to be the directory where i3-log.conf resides.

Disable All Logs

Some logs are generated before loading i3-log.conf. If you want to disable all logs completely, you have to either configure the logging of the Web server, or specify log-level when configuring DHtmlLayoutServlet in WEB-INF/web.xml. Refer to the Developer's Reference for details.

<servlet>
    <servlet-name>zkLoader</servlet-name>
    <servlet-class>org.zkoss.zk.ui.http.DHtmlLayoutServlet</servlet-class>
        <init-param>
            <param-name>log-level</param-name>
            <param-value>OFF</param-value>
        </init-param>
		<init-param>    
			<param-name>compress</param-name>        
			<param-value>false</param-value>        
		</init-param>    
</servlet>

Notes