Logger"

From Documentation
m
 
(23 intermediate revisions by 4 users not shown)
Line 2: Line 2:
 
__TOC__
 
__TOC__
  
Class: <javadoc>org.zkoss.util.logging.Log</javadoc>
+
In this section we describe how to configure the logging of ZK internal functions. You can generally ignore it, unless you'd like to know how ZK operates internally.
 +
 
 +
Notice that, if you are using Google App Engine, you can ''not'' configure the logging as described in this chapter. For more information, please refer to [[ZK Installation Guide/Setting up Servers/Google App Engine|Setting up Google App Engine]].
 +
 
 +
=How to Configure Logging=
 +
 
 +
{{versionSince| 7.0.0}}
 +
 
 +
ZK uses [http://www.slf4j.org/ SLF4J] as its internal logging system, and developers can follow the [http://www.slf4j.org/manual.html SLF4J document] to use the logging in ZK.
  
The logger used by ZK is based on the standard logger, <tt>java.util.Logger</tt>. However, we wrap it as <javadoc>org.zkoss.util.logging.Log</javadoc> to make it more efficient. The typical use is as follows.
+
By default, ZK maven setting will bundle the '''slf4j-jdk14''' implementation as its default logging.<ref>https://docs.oracle.com/cd/E19717-01/819-7753/gcbkm/index.html</ref>
 +
If developers want to change that implementation for '''Log4j''', '''Simple''', or '''Logback''', they have to exclude the dependency first like:
  
<source lang="java" >
+
<source lang="xml">
import org.zkoss.util.logging.Log;
+
<dependency>
class MyClass {
+
<groupId>org.zkoss.common</groupId>
    private static final Log log = Log.lookup(MyClass.class);
+
<artifactId>zcommon</artifactId>
    public void f(Object v) {
+
<version>${zk.version}</version>
        if (log.debugable()) log.debug("Value is "+v);
+
<exclusions>
    }
+
<exclusion>
}
+
<groupId>org.slf4j</groupId>
 +
<artifactId>slf4j-jdk14</artifactId>
 +
</exclusion>
 +
</exclusions>
 +
</dependency>
 
</source>
 
</source>
 
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.
 
  
By default, all ZK log instances are mapped to the same Java logger named <tt>org.zkoss</tt> to have the better performance. If you want to control the log level for individual class, you have to call <javadoc method="setHierarchy(boolean)">org.zkoss.util.logging.Log</javadoc> to turn on the hierarchy support.
+
 
 +
{{versionSince| 9.5.0}}
 +
 
 +
ZK maven dropped the transitive dependency of '''slf4j-jdk14'''. If a developer decides to enable logging, include either '''Log4j''', '''Simple''', or '''Logback''' implementation in their maven pom.xml file, e.g.
  
 
<source lang="xml">
 
<source lang="xml">
Log.setHierarchy(true);
+
<dependency>
 +
<groupId>ch.qos.logback</groupId>
 +
<artifactId>logback-classic</artifactId>
 +
<version>${logback.version}</version>
 +
</dependency>
 
</source>
 
</source>
  
The hierarchy support is enabled automatically, if you configure the log level with <tt>WEB-INF/zk.xml</tt> as described in the following section.
 
  
= Configure Log Levels with ZK =
+
{{DeprecatedSince| 7.0.0}}
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 <tt>WEB-INF/zk.xml</tt>. Refer to [http://books.zkoss.org/wiki/ZK_Configuration_Reference ZK Configuration Reference] fore more details.
+
ZK uses [http://docs.oracle.com/javase/1.4.2/docs/guide/util/logging/overview.html the standard logger] to log messages. You could control what to log by configuring the logging of the Web server you are using. The configuration usually varies from one server to another. However, you could use the configuration mechanism provided by ZK as described in this section. It shall work with most Web servers.
  
<source lang="xml" >
+
There are basically two steps to configure the standard logger with ZK's configuration mechanism:
<zk>
+
 
    <log>
+
# Prepare a logging configuration file
    <log-base>org.zkoss</log-base>
+
# Specify the configuration file in a library property
    </log>
 
</zk>
 
</source>
 
  
Alternatively, you can enable the logging configuration mechanism manually by invoking <javadoc method="init(java.lang.String, java.lang.Class)">org.zkoss.util.logging.LogService</javadoc> as follows.
+
== Prepare a logging configuration file ==
 +
{{DeprecatedSince| 7.0.0}}
 +
A logging configuration file is a standard properties file. Each line is a key-value pair in the following format:
  
<source lang="xml" >
+
<source lang="xml">
org.zkoss.util.logging.LogService.init("org.zkoss", null);
+
''a.package.or.a.class'' = ''level''
 
</source>
 
</source>
 
If you want to log not just <tt>org.zkoss</tt> but also everything, you could specify an empty value for the <tt>log-base</tt> argument.
 
 
Once the mechanism is enabled, ZK will look for <tt>i3-log.conf</tt> 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 =
+
Here is an example of a configuration file.
An example of <tt>i3-log.conf</tt> is as follows.
 
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 55: Line 66:
 
  org.zkoss.zk.ui.http=DEBUG
 
  org.zkoss.zk.ui.http=DEBUG
 
     #Make the log level of the specified package to 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
 
  org.zkoss.zk.ui=OFF
 
     #Turn off the log for the specified package
 
     #Turn off the log for the specified package
Line 64: Line 72:
 
</source>
 
</source>
 
 
== Allowed Levels ==
+
=== Allowed Levels ===
 
+
{{DeprecatedSince|7.0.0}}
{| border="1px"
+
{| class='wikitable' | width="100%"
 
! <center>Level</center>
 
! <center>Level</center>
 
! <center>Description</center>
 
! <center>Description</center>
Line 73: Line 81:
 
| <center>OFF</center>
 
| <center>OFF</center>
 
| Indicates no message at all.
 
| Indicates no message at all.
 
 
|-
 
|-
| <center>ERROR</center>
+
| <center>ERROR | SEVERE</center>
 
| Indicates providing error messages.
 
| Indicates providing error messages.
 
 
|-
 
|-
 
| <center>WARNING</center>
 
| <center>WARNING</center>
 
| Indicates providing warning messages. It also implies ERROR.
 
| Indicates providing warning messages. It also implies ERROR.
 
 
|-
 
|-
 
| <center>INFO</center>
 
| <center>INFO</center>
 
| Indicates providing informational messages. It also implies ERROR and WARNING.
 
| Indicates providing informational messages. It also implies ERROR and WARNING.
 
 
|-
 
|-
| <center>DEBUG</center>
+
| <center>DEBUG | FINE </center>
 
| Indicates providing tracing information for debugging purpose. It also implies ERROR, WARNING and INFO.
 
| Indicates providing tracing information for debugging purpose. It also implies ERROR, WARNING and INFO.
 
 
|-
 
|-
 
| <center>FINER</center>
 
| <center>FINER</center>
 
| Indicates providing fairly detailed tracing information for debugging purpose. It also implies ERROR, WARNING, INFO and DEBUG
 
| Indicates providing fairly detailed tracing information for debugging purpose. It also implies ERROR, WARNING, INFO and DEBUG
 +
|}
 +
 +
=== Specify the handler for Jetty and servers that don't turn on the standard logger ===
 +
{{DeprecatedSince|7.0.0}}
 +
Some Web servers, such as Jetty, don't turn on the standard logger by default. Thus, in the logging configuration file, you have to configure the handler too. For example, you can turn on the <code>java.util.logging.ConsoleHandler</code> to write the logs to the console by adding the following lines to the logging configuration file:
 +
 +
<source lang="xml">
 +
handlers = java.util.logging.ConsoleHandler
  
|-
+
java.util.logging.ConsoleHandler.level = FINER
| <center>INHERIT</center>
+
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
| 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.
+
</source>
 +
 
 +
Here is another example that configures the console and a file to be the target of the logs:
 +
 
 +
<source lang="xml">
 +
handlers = java.util.logging.FileHandler, java.util.logging.ConsoleHandler
 +
 
 +
java.util.logging.ConsoleHandler.level = FINER
 +
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
 +
 
 +
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
 +
java.util.logging.FileHandler.pattern = /var/log/jetty6/solr-%u.log
 +
java.util.logging.FileHandler.level = FINER
  
|}
+
org.zkoss.zk.ui.impl.UiEngineImpl=FINER
= Location of i3-log.conf =
+
org.zkoss.bind=FINE
 +
</source>
  
At first, ZK looks for this file in the classpath. If not found, it looks for the <tt>conf</tt> directory.
+
== Specify the configuration file in a library property ==
 +
{{DeprecatedSince|7.0.0}}
 +
To let  ZK load the logging configuration file, you have to specify in a library property called [[ZK Configuration Reference/zk.xml/The Library Properties/org.zkoss.util.logging.config.file|org.zkoss.util.logging.config.file]]. For example,
  
{| border="1px"
+
<source lang="xml">
! <center>Application Server</center>
+
<library-property>
! <center>Location</center>
+
<name>org.zkoss.util.logging.config.file</name>
 +
<value>conf/zk-log.properties</value>
 +
</library-property>
 +
</source>
  
|-
+
If a relative path is specified, it will look for the classpath first. If not found, it will assume it is related to the current directory, i.e., the directory specified in the system property called <code>user.dir</code>.
| <center>Tomcat</center>
 
| Place <tt>i3-log.conf</tt> under the <tt>$TOMCAT_HOME/conf</tt> directory
 
  
|-
+
You could specify an absolute path, such as <code>/usr/jetty/conf/zk-log.properties</code>, if you are not sure what the current directory is.
| <center>Others</center>
 
| Try the conf directory first. If not working, you could set the system property called the <tt>org.zkoss.io.conf.dir</tt> directory to be the directory where <tt>i3-log.conf</tt> resides.
 
  
|}
+
<references/>
  
 
= Disable All Logs =
 
= Disable All Logs =
Some logs are generated before loading <tt>i3-log.conf</tt>. If you want to disable all logs completely, you have to either configure the logging of the Web server<ref>Remember ZK uses the standard logging utilities. Unless you specify something in <tt>i3-log.conf</tt>, and the default logging levels depend on the Web server (usually <tt>INFO</tt>).</ref>, or specify <tt>log-level</tt> when configuring <javadoc>org.zkoss.zk.ui.http.DHtmlLayoutServlet</javadoc> in <tt>WEB-INF/web.xml</tt>. For more information, please refer to [[ZK Configuration Reference/web.xml/ZK Loader|ZK Configuration Reference]].
+
If you want to disable all loggers completely or change the level for all loggers, you don't need to prepare a logging configuration file. Rather, you can configure <javadoc>org.zkoss.zk.ui.http.DHtmlLayoutServlet</javadoc> in <code>WEB-INF/web.xml</code> as follows.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 124: Line 149:
 
     <servlet-name>zkLoader</servlet-name>
 
     <servlet-name>zkLoader</servlet-name>
 
     <servlet-class>org.zkoss.zk.ui.http.DHtmlLayoutServlet</servlet-class>
 
     <servlet-class>org.zkoss.zk.ui.http.DHtmlLayoutServlet</servlet-class>
        <init-param>
+
    <init-param>
            <param-name>log-level</param-name>
+
        <param-name>log-level</param-name>
            <param-value>OFF</param-value>
+
        <param-value>OFF</param-value>
        </init-param>
+
    </init-param>
 
</servlet>
 
</servlet>
 
</source>
 
</source>
 +
 +
For more information, please refer to [[ZK Configuration Reference/web.xml/ZK Loader|ZK Configuration Reference]].
 +
 +
=How to Log=
 +
Class: <javadoc>org.zkoss.util.logging.Log</javadoc>
 +
 +
The logger used by ZK is based on the standard logger, <code>java.util.logging.Logger</code>. However, we wrap it as <javadoc>org.zkoss.util.logging.Log</javadoc> to make it more efficient.
  
 
<blockquote>
 
<blockquote>
 
----
 
----
<references/>
+
To log the message to the client rather than the console at the server, you could use <javadoc method="log(java.lang.String)">org.zkoss.zk.ui.util.Clients</javadoc>
 
</blockquote>
 
</blockquote>
 +
 +
The typical use is as follows.
 +
 +
<source lang="java" >
 +
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);
 +
    }
 +
}
 +
</source>
 +
 +
= Reference =
 +
* [https://logging.apache.org/log4j/2.x/security.html Apache Log4j Security Vulnerabilities]
  
 
=Version History=
 
=Version History=
{{LastUpdated}}
+
 
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
| &nbsp;
+
| 6.0.0
| &nbsp;
+
| February 2012
| &nbsp;
+
| LogService was deprecated.
 
|}
 
|}
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Latest revision as of 09:41, 2 February 2024

In this section we describe how to configure the logging of ZK internal functions. You can generally ignore it, unless you'd like to know how ZK operates internally.

Notice that, if you are using Google App Engine, you can not configure the logging as described in this chapter. For more information, please refer to Setting up Google App Engine.

How to Configure Logging

Since 7.0.0

ZK uses SLF4J as its internal logging system, and developers can follow the SLF4J document to use the logging in ZK.

By default, ZK maven setting will bundle the slf4j-jdk14 implementation as its default logging.[1] If developers want to change that implementation for Log4j, Simple, or Logback, they have to exclude the dependency first like:

<dependency>
	<groupId>org.zkoss.common</groupId>
	<artifactId>zcommon</artifactId>
	<version>${zk.version}</version>
	<exclusions>
		<exclusion>
			<groupId>org.slf4j</groupId>
			<artifactId>slf4j-jdk14</artifactId>
		</exclusion>
	</exclusions>
</dependency>


Since 9.5.0

ZK maven dropped the transitive dependency of slf4j-jdk14. If a developer decides to enable logging, include either Log4j, Simple, or Logback implementation in their maven pom.xml file, e.g.

<dependency> 
	<groupId>ch.qos.logback</groupId>
	<artifactId>logback-classic</artifactId>
	<version>${logback.version}</version>
</dependency>


Deprecated Since 7.0.0 ZK uses the standard logger to log messages. You could control what to log by configuring the logging of the Web server you are using. The configuration usually varies from one server to another. However, you could use the configuration mechanism provided by ZK as described in this section. It shall work with most Web servers.

There are basically two steps to configure the standard logger with ZK's configuration mechanism:

  1. Prepare a logging configuration file
  2. Specify the configuration file in a library property

Prepare a logging configuration file

Deprecated Since 7.0.0 A logging configuration file is a standard properties file. Each line is a key-value pair in the following format:

''a.package.or.a.class'' = ''level''

Here is an example of a configuration file.

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

Deprecated Since 7.0.0

Level
Description
OFF
Indicates no message at all.
SEVERE Indicates providing error messages.
WARNING
Indicates providing warning messages. It also implies ERROR.
INFO
Indicates providing informational messages. It also implies ERROR and WARNING.
FINE 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

Specify the handler for Jetty and servers that don't turn on the standard logger

Deprecated Since 7.0.0 Some Web servers, such as Jetty, don't turn on the standard logger by default. Thus, in the logging configuration file, you have to configure the handler too. For example, you can turn on the java.util.logging.ConsoleHandler to write the logs to the console by adding the following lines to the logging configuration file:

handlers = java.util.logging.ConsoleHandler

java.util.logging.ConsoleHandler.level = FINER
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

Here is another example that configures the console and a file to be the target of the logs:

handlers = java.util.logging.FileHandler, java.util.logging.ConsoleHandler

java.util.logging.ConsoleHandler.level = FINER
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.FileHandler.pattern = /var/log/jetty6/solr-%u.log
java.util.logging.FileHandler.level = FINER

org.zkoss.zk.ui.impl.UiEngineImpl=FINER
org.zkoss.bind=FINE

Specify the configuration file in a library property

Deprecated Since 7.0.0 To let ZK load the logging configuration file, you have to specify in a library property called org.zkoss.util.logging.config.file. For example,

<library-property>
	<name>org.zkoss.util.logging.config.file</name>
	<value>conf/zk-log.properties</value>
</library-property>

If a relative path is specified, it will look for the classpath first. If not found, it will assume it is related to the current directory, i.e., the directory specified in the system property called user.dir.

You could specify an absolute path, such as /usr/jetty/conf/zk-log.properties, if you are not sure what the current directory is.

Disable All Logs

If you want to disable all loggers completely or change the level for all loggers, you don't need to prepare a logging configuration file. Rather, you can configure DHtmlLayoutServlet in WEB-INF/web.xml as follows.

<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>
</servlet>

For more information, please refer to ZK Configuration Reference.

How to Log

Class: Log

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


To log the message to the client rather than the console at the server, you could use Clients.log(String)

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);
     }
 }

Reference

Version History

Version Date Content
6.0.0 February 2012 LogService was deprecated.



Last Update : 2024/02/02

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.