Difference between revisions of "Debugging OpenKM with JBoss"

Revision as of 12:32, 8 February 2010

You can debug your OpenKM installation using the JBoss logging facility. This is an useful thing when you have problems with your configuration. Default OpenKM installation tries to log important events like errors and warnings. Is possible to change this configuration editing the file $JBOSS_HOME/server/default/conf/jboss-log4j.xml.

Default JBoss log configuration can generate a lot of messages. These files are stored at $JBOSS_HOME/server/default/log. It is configured to use the DailyRollingFileAppender. This appender create a new log file for every day. This is better than have a unique huge log file, os course. The rollover is performed at midnight each day, but you can configure it to make the rollover every hour (uncomment the proper line).

<!-- A time/date based rolling appender -->
<appender name="FILE"
          class="org.jboss.logging.appender.DailyRollingFileAppender">
   <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
   <param name="File" value="${jboss.server.log.dir}/server.log"/>
   <param name="Append" value="false"/>
   <!-- Rollover at midnight each day -->
   <param name="DatePattern" value="'.'yyyy-MM-dd"/>
   <!-- Rollover at the top of each hour
   <param name="DatePattern" value="'.'yyyy-MM-dd-HH"/>
   -->
   <layout class="org.apache.log4j.PatternLayout">
      <!-- The default pattern: Date Priority [Category] Message\n -->
      <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
      <!-- The full pattern: Date MS Priority [Category] (Thread:NDC) Message\n
      <param name="ConversionPattern" value="%d %-5r %-5p [%c] (%t:%x) %m%n"/>
      -->
   </layout>
</appender>

You can reduce the amount of log messages produced by OpenKM, or can increase them. In this example we limit the log messages produced by the class OKMAccessManager for those of type ERROR.

<category name="com.openkm.core.OKMAccessManager">
   <priority value="ERROR" />
</category>

If you create this configuration:

<category name="com.openkm">
   <priority value="DEBUG" />
</category>

All the log messages generated by OpenKM will be shown. As you can see, you can increase debug messages in some parts of OpenKM to check a determinate behavior.

Debugging JAAS configuration

If you are trying to setup another authentication source different from the default provided by OpenKM, you can afford some problems. The JBoss login-config.xml is supposed to have the right configuration, but you can't log into the application. The most common case is a bad or missing JAAS configuration. So if you need to debug the JAAS, you can add to the log4j.xml file the following:

<category name="org.jboss.security">
   <priority value="TRACE" class="org.jboss.logging.XLevel"/>
   <appender-ref ref="SECURITY_F"/>
</category>
<appender name="SECURITY_F" class='org.jboss.logging.appender.DailyRollingFileAppender'>
   <param name="Append" value="true"/>
   <param name="DatePattern" value="'.'yyyy-MM-dd"/>
   <param name="File" value="${jboss.server.home.dir}/log/jboss.security.log"/>
   <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d{ABSOLUTE} %-5p [%c] %m%n"/>
   </layout>
</appender>

This is more or less in the middle of the file, just where the <category-name> section begins.

Email error notification

Always is good idea to be notified when things goes wrong. There are some log appenders that can help you. The SMTPAppender will mail you log messages with threshold ERROR by default. You can lower this threshold, but you will got lots of useless mail messages. Here you must configure some properties:

• To: The mail account where the messages will arrive.
• From: You can set it simply as noreply@your-domain.com.
• Subject: Here you can specify the subject of the mail. If you have several OpenKM installations, you can create a filter in your mail client using this value.
• SMTPHost: The mail server server. Can be localhost if there is a mail server installed in this computer.

<!-- EMail events to an administrator -->
<appender name="SMTP" class="org.apache.log4j.net.SMTPAppender">
  <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
  <param name="Threshold" value="ERROR"/>
  <param name="To" value="admin@myhost.domain.com"/>
  <param name="From" value="nobody@myhost.domain.com"/>
  <param name="Subject" value="JBoss Sever Errors"/>
  <param name="SMTPHost" value="localhost"/>
  <param name="BufferSize" value="10"/>
  <layout class="org.apache.log4j.PatternLayout">
     <param name="ConversionPattern" value="[%d{ABSOLUTE},%c{1}] %m%n"/>
  </layout>
</appender>

In Unix / Linux systems there is a centralized log manager called syslog. You can configure Log4J to use this system using the SyslogAppender:

<!-- Syslog events -->
<appender name="SYSLOG" class="org.apache.log4j.net.SyslogAppender">
  <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
  <param name="Facility" value="LOCAL7"/>
  <param name="FacilityPrinting" value="true"/>
  <param name="SyslogHost" value="localhost"/>
  <layout class="org.apache.log4j.PatternLayout">
     <param name="ConversionPattern" value="[%d{ABSOLUTE},%c{1}] %m%n"/>
  </layout>
</appender>

• SyslogHost: This configuration parameters allows you to specify the local syslog or a remote syslog server used to centralize the network log management.

For more info, visit:

• http://jboss.org/community/docs/DOC-11280
• http://jboss.org/community/docs/DOC-9372
• http://jakarta.apache.org/log4j
• http://primalcortex.wordpress.com/2007/11/28/jboss-and-jaas-debug