Introduction #

Liferay uses the Apache Log4j library to perform all of it's logging operations. This allows for a very configurable setup with different levels of messages priority, from FATAL to DEBUG. It also allows to configure a different level of messages to be shown for every package or class within Liferay or any of its libraries.

The default configuration is set to only show errors for most classes and packages with a few of them set to show also warnings.

Where are the logs? #

By default, the logs are written to the standard output (CONSOLE in log4j's terminology) which means that they'll be outputted to the application server log file. Here are the location of the logs in some of the application servers supported by Liferay:

• Tomcat: $TOMCAT/bin/catalina.out
• Geronimo: $GERONIMO/var/log/geronimo.log
• JBoss: $JBOSS/server/default/log/
• Glassfish: $GLASSFISH/domains/domain1/logs/server.log

Customizing the Log4j configuration #

Using the Enterprise Admin Portlet #

The Admin Portlet available to portal administrators offers a UI to dinamically change the log levels for many of the packages of Liferay and its main libraries. To access this UI add the Admin Portlet to a portal page, go to the Server tab and click 'more' so that the subtabs are shown. Go to the 'Log levels' subtab and you should see a screen similar to the following:

By using the dropdown you can select a different log level for each of the paragraphs, from DEBUG to FATAL, or turn them off completely. Once you are finished click the save button to apply your changes. You can do this operation as many times as desired.

This changes are stored in memory, which means that they'll be lost when you reboot the server. If you wish to make changes to the configuration in a way that they are preserved after reboots or that can be maintained accross different installations read the following sections.

Creating a custom configuration file: portal-log4j-ext.xml #

The logging configuration of Liferay is stored in a file called portal-log4j.xml. It's possible to override all or certain parts of that configuration by creating another file called portal-log4j-ext.xml and deploying it to the appropriate place. This section details the steps necessary to achieve this.

The first step is to get a copy of the original configuration file. Depending on our environment the portal-log4j.xml can be found in:

• Liferay's sources: portal-impl/classes/META-INF/
• Tomcat bundle: inside $TOMCAT/WEB-INF/lib/portal-impl.jar in META-INF/
• Other bundles: look for portal-impl.jar, the file will be inside its META-INF directory once unzipped

Note for JBoss users: JBoss includes its own Log4j configuration that may override Liferay's configuration. The JBoss Log4j configuration file can be found in $JBOSS/server/default/conf/log4j.xml. Read the JBoss documentation for details.

Make a copy of that file and rename it as portal-log4j-ext.xml. It is recommended that you only keep in that file those entries that have been modified, delete the other entries, since they'll be loaded from portal-log4j.xml.

Let's see an example of how we could change the log level of a library, for example, Hibernate. By default the log level of this library is ERROR. Let's change it to INFO. Look in the file for the following entry:

  <category name="org.hibernate">
    <priority value="ERROR" />
  </category>

A portal-log4j-ext.xml file that changes only this log level would be:

 <?xml version="1.0"?>
 <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
 <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
  <category name="org.hibernate">
    <priority value="INFO" />
  </category>
 </log4j:configuration>

Once you've done the necessary changes deploy the file. The file has to be deployed inside a directory called META-INF to a directory that is in the classpath. Here are some recommended locations, depending on the application server:

• Tomcat 5.x: $TOMCAT/common/classes/META-INF
• Note: To this directory, you also need to copy log4j.dtd from the same location where you obtained the portal-log4j.xml file. Else, you will encounter errors about the fact that log4j.dtd cannot be resolved.
• Tomcat 6.x: $TOMCAT_HOME/lib/META-INF
• Note: As in Tomcat 5.x, you also need to copy log4j.dtd.
• Geronimo: One possibility to do is is by adding a .jar file containing the META-INF/log4j.dtd (as with Tomcat) and the META-INF/portal-log4j-ext.xml to Geronimo's $GERONIMO_HOME/lib directory. In a hurry, just adding the directory and files to one of the existing .jar files (i.e. log4j-1.x.jar) in the directory is also possible; this way, you do not have to create your own jar for it.
• Tomcat 7.2.3: $TOMCAT_HOME/webapps/ROOT/WEB-INF/classes/META-INF
• Note: Copy log4j.dtd as well as portal-log4j-ext.xml, replacing webapps/ROOT with the Liferay-Installation directory.
• Glassfish 3.1.2: domain-dir/lib/classes/META-INF/portal-log4j-ext.xml
• Other application servers: TBD

Note: If you are using an extension environment, it can only store and deploy for you a portal-log4j-ext.xml file. See Development in the ext environment for detailed instructions. When using the ext environment the portal-log4j-ext.xml file will be automatically included in your installation when using the deploy ant targets.

Appending logs to a file #

Customize the log4j.properties file to append the logs to a file: log4j.appender.CONSOLE=org.apache.log4j.FileAppender

And also specify where the file will be located: log4j.appender.CONSOLE.File=E:/Liferay/5.1/liferay-portal-tomcat-5.5-5.1.0/logs/test.log

Technical information #

Log4 initialization #

The initialization of Log4j is performed in the InitAction.run() method which is executed when the application server starts up. This method is invoked when the MainServlet class is loaded because of the following code that can be find within it:

 static {
   InitUtil.init();
 }

The InitUtil class is just a helper class that ends up invoking InitAction.run().

The InitAction class loads two log4j configuration files, portal-log4j.xml and portal-log4j-ext.xml with the second one overriding the configuration of the first. If any of this files is missing they are silently ignored. This is the code that performs this operation:

  if (GetterUtil.getBoolean(SystemProperties.get("log4j.configure.on.startup"), true) && !ServerDetector.isSun()) {
  
    ClassLoader classLoader = getClass().getClassLoader();
  
    Log4JUtil.configureLog4J(classLoader.getResource("META-INF/portal-log4j.xml"));
    Log4JUtil.configureLog4J(classLoader.getResource("META-INF/portal-log4j-ext.xml"));
  }

Note: This code may have slightly changed since this article was written or may be different for your version. Make sure you download Liferay's sources and look at your specific version of the mentioned files for accurate information.

Troubleshooting #

If you have setup a portal-log4j-ext.xml file but your changes are not being applied there are two possible causes:

• The file has an incorrect syntax
• The file is not being found

If you can't see any information in the logs to help you determine the cause, the best way to find out is to do some debugging:

1. Configure your IDE to be able to connect to a remote Liferay instance for debugging or to be able to run Liferay within it
2. Set up a breakpoint in the line where the ClassLoader is defined (see code fragment above)
3. Run Liferay with remote debugging enabled or within the IDE
4. If using remote debugging connect to Liferay very quickly after starting it (within the first 2 secs). The Log4J configuration happens very early in the startup. If the debugger does not stop in the breakpoint, stop Liferay and try again.
5. Execute step-by-step and enter the configureLog4J method for the portal-log4j-ext.xml file to find out if the file is found and if it's read correctly