<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<section id="Kernel.LogConfiguration">
  <title>Logs configuration</title>

    <para>In order to accommodate to the different target runtime where it can
    be deployed, eXo is capable of leveraging several logging systems. eXo
    lets you choose the underlying logging engine to use and even configure
    that engine (as a quick alternative to doing it directly in your runtime
    environment).</para>

    <para>The currently supported logging engines are: <itemizedlist>
        <listitem>
          <para>Apache Log4J</para>
        </listitem>

        <listitem>
          <para>JDK's logging</para>
        </listitem>

        <listitem>
          <para>Apache Commons logging (which is itself a pluggable logging
          abstraction)</para>
        </listitem>
      </itemizedlist></para>

  <section id="Kernel.LogConfiguration.LogsConfigurationInitializer">
    <title>Logs configuration initializer</title>

    <para>eXo lets you choose whatever logging engine you want as this is
    generally influences by the AS runtime or internal policy.</para>

    <para>This is done through an eXo component called
    <classname>LogConfigurationInitializer</classname>.</para>

    <para><classname>org.exoplatform.services.log.LogConfigurationInitializer</classname>
    that reads init parameters and configures logging system according to
    them. The parameters:<itemizedlist>
        <listitem>
          <para><firstterm>configurator</firstterm> - an implementation of the
          <classname>LogConfigurator</classname> interface with one method
          configure() that accepts a list of properties (3rd init parameter)
          to configure the underlying log system using the concrete mechanism.
          Again, there are three configurators for the most known log systems
          (commons, log4j, jdk).</para>
        </listitem>

        <listitem>
          <para><firstterm>properties</firstterm> - properties to configure
          the concrete log system (system properties for commons,
          log4j.properties or logging.properties for commons, log4j and jdk
          respectively) Look at the configuration examples below.</para>
        </listitem>

      </itemizedlist></para>
  </section>

  <section id="Kernel.LogConfiguration.ConfigurationExamples">
    <title>Configuration examples</title>

    <section id="Kernel.LogConfiguration.ConfigurationExamples.Log4J">
      <title>Log4J</title>

      <para><ulink url="http://logging.apache.org/log4j/">Log4J</ulink> is a
      very popular and flexible logging system. It is a good option for
      JBoss.</para>
      <programlisting language="xml">  &lt;component&gt;
    &lt;type&gt;org.exoplatform.services.log.LogConfigurationInitializer&lt;/type&gt;
    &lt;init-params&gt;
      &lt;value-param&gt;
        &lt;name&gt;configurator&lt;/name&gt;
        &lt;value&gt;org.exoplatform.services.log.impl.Log4JConfigurator&lt;/value&gt;
      &lt;/value-param&gt;
      &lt;properties-param&gt;
        &lt;name&gt;properties&lt;/name&gt;
        &lt;description&gt;Log4J properties&lt;/description&gt;
        &lt;property name="log4j.rootLogger" value="DEBUG, stdout, file"/&gt;
        &lt;property name="log4j.appender.stdout" value="org.apache.log4j.ConsoleAppender"/&gt;
        &lt;property name="log4j.appender.stdout.layout" value="org.apache.log4j.PatternLayout"/&gt;
        &lt;property name="log4j.appender.stdout.layout.ConversionPattern" value="%d {dd.MM.yyyy HH:mm:ss} %c {1}: %m (%F, line %L) %n"/&gt;
        &lt;property name="log4j.appender.file" value="org.apache.log4j.FileAppender"/&gt;
        &lt;property name="log4j.appender.file.File" value="jcr.log"/&gt;
        &lt;property name="log4j.appender.file.layout" value="org.apache.log4j.PatternLayout"/&gt;
        &lt;property name="log4j.appender.file.layout.ConversionPattern" value="%d{dd.MM.yyyy HH:mm:ss} %m (%F, line %L) %n"/&gt;
      &lt;/properties-param &gt;
    &lt;/init-params&gt;
  &lt;/component&gt;</programlisting>

      <section id="Kernel.LogConfiguration.ConfigurationExamples.Log4J.AssigningLoggerLevelForClassesComponents">
        <title>Assigning logger level for classes or components</title>

        <para>You can set logger level for class or group of classes by
        setting next property:</para>

        <programlisting language="xml">&lt;property name="log4j.category.{component or class name}" value="DEBUG"/&gt;</programlisting>

        <para>For example:</para>
        <itemizedlist>
            <listitem>
              <para>We want to log all debug messages for class
              <classname>org.exoplatform.services.jcr.impl.core.SessionDataManager</classname>,
              that lies in <package>exo.jcr.component.core</package>
              component</para>
            </listitem>
          </itemizedlist>

              <programlisting language="xml">&lt;property name="log4j.category.exo.jcr.component.core.SessionDataManager" value="DEBUG"/&gt;</programlisting>

          <itemizedlist>
            <listitem>
              <para>Or we want to log all debug messages for all classes in
              <package>exo.jcr.component.core</package>
              component</para>
            </listitem>
          </itemizedlist>

              <programlisting language="xml">&lt;property name="log4j.category.exo.jcr.component.core" value="DEBUG"/&gt;</programlisting>

          <itemizedlist>
            <listitem>
              <para>Or we want to log all messages for all kernel
              components</para>
            </listitem>
          </itemizedlist>

        <programlisting language="xml">&lt;property name="log4j.category.exo.kernel" value="DEBUG"/&gt;</programlisting>


      </section>
    </section>

    <section id="Kernel.LogConfiguration.ConfigurationExamples.JDKLogging">
      <title>JDK Logging</title>

      <para>JDK logging (aka JUL) is the builtin logging framework introduced
      in JDK 1.4. It is a good option for Tomcat AS.</para>
      <itemizedlist>
          <listitem>
            <para>Edit the variable <varname>LOG_OPTS</varname> in your
            <filename>eXo.sh</filename> or <filename>eXo.bat</filename>
            :</para>
          </listitem>
          </itemizedlist>
        <programlisting>LOG_OPTS="-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Jdk14Logger"</programlisting>

        <itemizedlist>
          <listitem>
            <para>Edit your <filename>logs-configuration.xml:</filename></para>
          </listitem>
        </itemizedlist>
            <programlisting language="xml">&lt;component&gt;
    &lt;type&gt;org.exoplatform.services.log.LogConfigurationInitializer&lt;/type&gt;
    &lt;init-params&gt;
      &lt;value-param&gt;
        &lt;name&gt;configurator&lt;/name&gt;
        &lt;value&gt;org.exoplatform.services.log.impl.Jdk14Configurator&lt;/value&gt;
      &lt;/value-param&gt;
      &lt;properties-param&gt;
        &lt;name&gt;properties&lt;/name&gt;
        &lt;description&gt;jdk1.4 Logger properties&lt;/description&gt;
        &lt;property name="handlers" value="java.util.logging.ConsoleHandler"/&gt;
        &lt;property name=".level" value="FINE"/&gt;
        &lt;property name="java.util.logging.ConsoleHandler.level" value="FINE"/&gt;
      &lt;/properties-param&gt;
    &lt;/init-params&gt;
  &lt;/component&gt;</programlisting>

    </section>

    <section id="Kernel.LogConfiguration.ConfigurationExamples.CommonsLoggingSimpleLogs">
      <title>Commons Logging SimpleLogss</title>

      <para>SimpleLog is a minimal logging system distributed with Commons
      Logging. To be used when nothing else is available or when you seek
      simplicity.</para>
      <programlisting language="xml">  &lt;component&gt;
    &lt;type&gt;org.exoplatform.services.log.LogConfigurationInitializer&lt;/type&gt;
    &lt;init-params&gt;
      &lt;value-param&gt;
        &lt;name&gt;configurator&lt;/name&gt;
        &lt;value&gt;org.exoplatform.services.log.impl.SimpleExoLogConfigurator&lt;/value&gt;
      &lt;/value-param&gt;
      &lt;properties-param&gt;
        &lt;name&gt;properties&lt;/name&gt;
        &lt;description&gt;SimpleLog properties&lt;/description&gt;
        &lt;property name="org.apache.commons.logging.simplelog.defaultlog" value="debug"/&gt;
        &lt;property name="org.apache.commons.logging.simplelog.showdatetime" value="true"/&gt;
      &lt;/properties-param&gt;
    &lt;/init-params&gt;
  &lt;/component&gt;</programlisting>
    </section>
  </section>

  <section id="Kernel.LogConfiguration.TipsAndTroubleshooting">
    <title>Tips and Troubleshooting</title>

    <section id="Kernel.LogConfiguration.TipsAndTroubleshooting.JBossTips">
      <title>JBoss tips</title>

      <para>If you use log4j configuration, you can change the log
      configuration directly at runtime in:</para>
      <filename>JBOSS_HOME/server/default/conf/jboss-log4j.xml</filename>.
      <itemizedlist>
        <listitem>
          <para>To enable debug logs:</para>
        </listitem>
      </itemizedlist>  
      <programlisting language="xml"> &lt;param name="Threshold" value="DEBUG"/&gt; </programlisting>
        
        <itemizedlist>
          <listitem>
            <para>To exclude messages from unnecessary classes (server's
            internal) modify the threshold of these classes to "FATAL".</para>
          </listitem>
        </itemizedlist>
        <tip>
          <para>If you see only ERROR level logs while starting ear on jboss
          (4.2.2), you have to remove log4j*.jar from your ear and
          application.xml.</para>
        </tip>
    </section>

    <section id="Kernel.LogConfiguration.TipsAndTroubleshooting.OtherTips">
      <title>Other tips</title>

      <para>If you see only ERROR level logs while starting ear on jboss
      (4.2.2), you have to remove log4j*.jar from your ear and
      application.xml.</para>
    </section>
  </section>
</section>
