<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:mml="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>Configuring the logging System</title>
  </info>

  <para><link
  xlink:href="http://monolog.objectweb.org/doc/index.html">Monolog</link> is
  the Objectweb solution for logging. It is not only a new logging
  implementation but can be seen as a bridge between different logging
  implementations. A library that uses the Monolog API can be used with any
  logging implementation at runtime.</para>

  <para>Furthermore some components of JOnAS like CAROL, JOTM, Tomcat etc...
  doesn't use the Monolog API but Jakarta commons loggins or log4j or other
  implementation. However all these components will be configured via the
  JOnAS Monolog configuration file.</para>

  <section>
    <info>
      <title>Monolog</title>
    </info>

    <para>JOnAS Monolog configuration files are:</para>

    <itemizedlist>
      <listitem>
        <para><filename>$JONAS_BASE/conf/trace.properties</filename> <footnote>
            <para>the name can be changed via
            <property>jonas.log.configfile</property> property in
            <filename>jonas.properties</filename></para>
          </footnote></para>

        <para>which is the server side Monolog configuration file</para>
      </listitem>

      <listitem>
        <para><filename>$JONAS_BASE/conf/traceclient.properties</filename></para>

        <para>which is used for a client in a client container.</para>
      </listitem>
    </itemizedlist>

    <para>Configuring trace messages inside <xi:include
    href="../variables.xml" xpointer="element(appserver)" /> can be done in
    two ways:</para>

    <orderedlist>
      <listitem>
        <para>Changing the <filename>trace.properties</filename> file to
        configure the traces statically, before the <xi:include
        href="../variables.xml" xpointer="element(appserver)" /> Server is
        run</para>
      </listitem>

      <listitem>
        <para>Using the jonas admin command or the JonasAdmin administration
        tool to configure the traces dynamically while the <xi:include
        href="../variables.xml" xpointer="element(appserver)" /> Server is
        running. In this case the modification are not persistent
        (<filename>trace.properties</filename> file is not modified).</para>
      </listitem>
    </orderedlist>
  </section>

  <section>
    <info>
      <title>trace.properties syntax</title>
    </info>

    <para>Applications make logging calls on <emphasis>logger
    </emphasis>objects.Loggers are organized in a hierarchical namespace and
    child <emphasis>loggers</emphasis> may inherit some logging properties
    from their parents in the namespace. <emphasis>Loggers</emphasis>
    allocates messages and passes them to <emphasis>handler</emphasis> for
    output; they uses logging <emphasis>levels</emphasis> in order to decide
    if they are interested in by a particular message.</para>

    <para>In <filename>trace.properties</filename> it is possible to define
    <emphasis>handlers</emphasis>, <emphasis>loggers</emphasis>,
    <emphasis>levels</emphasis>:</para>

    <itemizedlist>
      <listitem>
        <para>handlers</para>

        <para>A handler represents an output, is identified by its name, has a
        type, and has some additional properties. By default three handlers
        are used:</para>

        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">tty </emphasis>is basic standard
            output on a console</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">logf</emphasis> is a handler for
            printing messages on a file</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">mesonly </emphasis>handler used by
            generation tools for traces without header</para>
          </listitem>
        </itemizedlist>

        <para>Each handler can define the header it will use, the type of
        logging (console, file, rolling file), and the file name.</para>

        <para>The handler properties are the following:</para>

        <itemizedlist>
          <listitem>
            <para>type: is the type of the handler that may be:</para>

            <itemizedlist>
              <listitem>
                <para>Console : Log stream ends inside
                <filename>System.out</filename> or
                <filename>System.err</filename></para>
              </listitem>

              <listitem>
                <para>File : Log stream is directed into a file</para>
              </listitem>

              <listitem>
                <para>Rollingfile : A file set is used to roll the logs</para>
              </listitem>

              <listitem>
                <para>JMX : Logging actions are send to the JMX notification
                system</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>pattern:is the message format. A pattern can be composed of
            elements. An element is prefixed by the % character.The possible
            items:</para>

            <itemizedlist>
              <listitem>
                <para><emphasis role="bold">%h</emphasis>: the thread
                name</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">%O{1} </emphasis>: the Class name
                (basename only)</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">%M</emphasis> the method
                name</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">%L</emphasis> the line
                number</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">%d </emphasis>the date</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">%l </emphasis>the level</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">%m</emphasis> the message
                itself</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">%n</emphasis> a new line</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>output: is the output filename.</para>

            <para>If <emphasis>automatic</emphasis><footnote>
                <para>By default automatic is set for the handler logf</para>
              </footnote> is used, JOnAS will replace this tag with a file
            pointing to
            <filename>$JONAS_BASE/logs/&lt;jonas_name_server&gt;-&lt;timestamp&gt;.log</filename></para>

            <para><emphasis>Switch</emphasis> is used for logging either on
            <filename>System.out</filename> or <filename>System.err</filename>
            depending on the level of the log</para>
          </listitem>

          <listitem>
            <para>fileNumber: is the number of file to use (for
            RollingFile)</para>
          </listitem>

          <listitem>
            <para>maxSize:is the maximal size of the file (for Rolling
            file)</para>
          </listitem>
        </itemizedlist>
        
        <para>Note that another handler, named <emphasis role="bold">jmxHandler</emphasis>,
        can be used to allow to view the recent logs in the
        <xi:include href="../variables.xml" xpointer="element(appserver)" /> administration console.
        By default the definition of this handler is commented, for performance reason.
        </para>
        
      </listitem>

      <listitem>
        <para>loggers</para>

        <para>Loggers are identified by names that are structured as a tree.
        The root of the tree is named <emphasis>root. </emphasis>Each logger
        is associated with a topic. Topic names are usually based on the
        package name. Each logger can define the handler it will use and the
        trace level (see below). By default loggers inherit their level from
        their parents.</para>

        <para>By default handlers assigned to the parent logger are
        automatically assign to child loggers. Setting 'additivity' to false
        inform the system that the logger will use only its own set of
        handlers.<footnote>
            <para>this property is optional and its default value is
            'yes'</para>
          </footnote></para>
      </listitem>

      <listitem>
        <para>levels</para>

        <para>the trace levels are the following:</para>

        <itemizedlist>
          <listitem>
            <para>ERROR errors. Should always be printed.</para>
          </listitem>

          <listitem>
            <para>WARN warning. Should be printed.</para>
          </listitem>

          <listitem>
            <para>INFO informative messages.</para>
          </listitem>

          <listitem>
            <para>DEBUG debug messages. Should be printed only for
            debugging.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <info>
      <title>default trace.properties file</title>
    </info>

    <para><screen>log.config.classname org.objectweb.util.monolog.wrapper.javaLog.LoggerFactory  <co
          xml:id="log.config.classname" />

handler.tty.type Console <co xml:id="handler.tty.type" />
handler.tty.output Switch <co xml:id="handler.tty.output" />
handler.tty.pattern  %d : %O{1}.%M : %m%n <co xml:id="handler.tty.pattern" />

handler.logf.type File <co xml:id="handler.logf.type" />
handler.logf.output automatic <co xml:id="handler.logf.output" />
handler.logf.pattern  %d : %l : %h : %O{1}.%M :    %m%n

logger.root.handler.0 tty <co xml:id="logger.root.0" />
logger.root.handler.1 logf <co xml:id="logger.root.handler.1" />

logger.root.level INFO <co xml:id="logger.root.level" />
logger.org.objectweb.level INFO
logger.org.ow2.level INFO

#logger.org.ow2.jonas.lib.ejb21.level DEBUG <co xml:id="jonas_ejb21.level" />

handler.mesonly.type Console <co xml:id="handler.mesonly" />
handler.mesonly.output Switch
handler.mesonly.pattern  %m%n

logger.org.ow2.jonas.generators.genic.handler.0 mesonly <co
          xml:id="genic.handler" />
logger.org.ow2.jonas.generators.genic.additivity false <co
          xml:id="genic.additivity" />

[...]</screen> <calloutlist>
        <callout arearefs="log.config.classname">
          <para>Definition of the wrapper to use: here the java logging API
          wrapper.</para>
        </callout>

        <callout arearefs="handler.tty.type">
          <para>Definition of the console handler tty</para>
        </callout>

        <callout arearefs="handler.tty.type">
          <para>Switch means that the logs will be on System.out or System.err
          depending of the level of the log.</para>
        </callout>

        <callout arearefs="handler.tty.pattern">
          <para>Definition of the message format. here it contains the date
          followed by ':' the basename of the class followed by '.' the method
          name followed by ':' the message itself terminated by
          newline.</para>
        </callout>

        <callout arearefs="handler.logf.type">
          <para>Definition of the file handler logf</para>
        </callout>

        <callout arearefs="handler.logf.output">
          <para>Logs are in a file whose name is
          <filename>$JONAS_BASE/logs/&lt;jonas_name_server&gt;-&lt;timestamp&gt;.log</filename></para>
        </callout>

        <callout arearefs="logger.root.0">
          <para>Definition of the root logger. It uses handler tty</para>
        </callout>

        <callout arearefs="logger.root.handler.1">
          <para>Definition of the root logger: It uses also handler
          logf</para>
        </callout>

        <callout arearefs="logger.root.level">
          <para>Definition of the root logger: level INFO is used for all
          child loggers if there is no overriden definition</para>
        </callout>

        <callout arearefs="jonas_ejb21.level">
          <para>This line must be uncommented for setting DEBUG level for the
          logger used in the jonas ejb21 module</para>
        </callout>

        <callout arearefs="handler.mesonly">
          <para>Definition of the console handler mesonly used by generator tool, such as GenIC,
          which want to log messages without headers</para>
        </callout>

        <callout arearefs="genic.handler">
          <para>Definition of the handler used by the logger
          org.ow2.jonas.generators</para>
        </callout>

        <callout arearefs="genic.additivity">
          <para>This logger wants to use its own handler.</para>
        </callout>
      </calloutlist></para>
  </section>

  <section>
    <info>
      <title>Tips for setting loggers for JOnAS</title>
    </info>

    <para>When a problem occurs it may be worth to set some debugging traces
    in the <xi:include href="../variables.xml" xpointer="appserver" /> server.
    It is not easy to know which logger to set to obtain the pertinent traces
    that may help the debbugging process.</para>

    <para>The <filename>trace.properties</filename> file contains several
    commented lines prepared to set loggers in DEBUG level.</para>

    <para>Usually the name of loggers are related to the java package name in
    which it is used.</para>

    <itemizedlist>
      <listitem>
        <para>To set debug traces of the EJB2 container uncomment one or more
        lines related to logger org.ow2.jonas.lib.ejb2 for example:</para>

        <screen>logger.org.ow2.jonas.lib.ejb21.interp.level DEBUG
logger.org.ow2.jonas.lib.ejb21.synchro.level  DEBUG
logger.org.ow2.jonas.lib.ejb21.tx.level DEBUG</screen>
      </listitem>

      <listitem>
        <para>To set traces related to resource adapters:</para>

        <screen>logger.org.ow2.jonas.jca.level DEBUG
logger.org.ow2.jonas.jca.pool.level DEBUG</screen>
      </listitem>

      <listitem>
        <para>To set traces into the CAROL library::</para>

        <screen>logger.org.ow2.carol.level DEBUG</screen>
      </listitem>

      <listitem>
        <para>To set traces in JORAM:</para>

        <screen>logger.fr.dyade.aaa.level DEBUG  (for the MOM)

# for the JORAM resource adapter:
logger.org.objectweb.joram.client.jms.Client.level DEBUG
logger.org.objectweb.joram.client.connector.Adapter.level DEBUG</screen>
      </listitem>

      <listitem>
        <para>To set traces in Tomcat:</para>

        <itemizedlist>
          <listitem>
            <para>for all web application :</para>

            <screen>logger.org.apache.catalina.core.ContainerBase.[jonas].[localhost].level DEBUG</screen>

            <para><property>jonas</property> is the attribute name of the
            element Engine in $JONAS_BASE/conf/tomcat6-server.xml</para>

            <para>localhost is the attribute name of the element Host in
            $JONAS_BASE/conf/tomcat6-server.xml</para>
          </listitem>

          <listitem>
            <para>for a particular web application :</para>

            <screen>logger.org.apache.catalina.core.containerBase.[jonas].[localhost].[jonasAdmin].level DEBUG</screen>

            <para><property>jonas</property> is the attribute name of the
            element Engine in $JONAS_BASE/conf/tomcat6-server.xml</para>

            <para><property>localhost</property> is the attribute name of the
            element host in $JONAS_BASE/conf/tomcat6-server.xml</para>

            <para><property>jonasAdmin </property>is the name of the web
            application</para>
          </listitem>
        </itemizedlist>

        <para><note>
            <para>the attributes debug in elements of
            $JONAS_BASE/conf/tomcat6-server.xml are not used anymore in Tomcat.</para>
          </note></para>
      </listitem>

      <listitem>
        <para>There are a lot of traces possible for
        management, discovery, jtm, clustering, mail, ear,...</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <info>
      <title>Logging with particular log systems</title>
    </info>

    <section>
      <info>
        <title>java logging API</title>
      </info>

      <para>If Monolog is configured to use the JDK logger it will replace the
      JDK logger implementation with its own implementation and so all JDK
      logs are intercepted by Monolog. By default Monolog is configured to use
      the JDK logger.</para>
    </section>

    <section>
      <info>
        <title>Jakarta commons logging</title>
      </info>

      <para>There is no special configuration file for Jakarta commons
      login.If it is used on top of the java logging API it is the same case
      than the previous section.</para>

      <para></para>
    </section>

    <section>
      <info>
        <title>log4j</title>
      </info>

      <para><xi:include href="../variables.xml"
      xpointer="element(appserver)" /> don't provide the corresponding
      <filename class="extension">jar</filename> file so, log4j must be
      packaged (<filename class="extension">.jar</filename> file and
      <filename>log4j.properties)</filename> in any application that want to
      use it. The l<filename>og4j.properties</filename> file must be
      configured correctly.</para>

      <para>If log4j is used by several applications it is possible to
      centralize the log4j configuration by putting log4j.properties in
      <filename class="directory">$JONAS_BASE/conf </filename>and log4j jar
      file in <filename
      class="directory">$JONAS_BASE/lib/commons</filename>.</para>
    </section>
  </section>
</section>
