Cocoon Logging Configuration

This document describes how to configure Cocoon's logging mechanism. The first section describes the basics of logging, introducing the key concept of Cocoon's logging. The next section describes the configuration files involved in Cocoon's logging.

(An overview of Cocoon logging can also be found here UnderstandingCocoonLogging. EricBoisvert)

Basics

Cocoon's logging mechanism introduces following keywords

Following category names are declared in the cocoon.xconf file

A log target is a physical logging destination. A log target is wrapped in a LogTargetFactory, and declared in the logkit.xconf file.

Following log target factories are available

Configuration

Logging categories are used in the java sources. A java programmer decides to use a specific category in some piece of java code.

Alternatively Avalon components used in Cocoon specifies in the its declaration cocoon.xconf the category by the attribute logger.

Note that in both cases we deal only with logging categories, not with logging targets. Logging targets are completely independent from the logging category, in respect of the java programmer.

In next level logkit.xconf maps logging categories to a log target. The configuration file logkit.xconf defines the log targets. More specific, logkit.xconf declares first LogTargetFactories. Next it configures instances of LogTargetFactory objects. And finally it maps logging categories to LogTargetFactory instances.

You have following mapping options

Each logging target has some target specific configuration options. Most of the logging targets offer a logging formatting configuration, which are described below.

The configuration file WEB-INF/web.xml is only used during startup and until the logkit.xconf takes over.

Declaring !LogTargets

Before you can configure a specific log target you have to declare it. This is done in the logkit.xconf file.

Inside of the factories element each factory element declares a log target.

A factory element requires following attributes:

Example

This example declares the SerlvetTargetFactory, you may use servlet for defining a servlet log target in the following sections of the logkit.xconf file.

....
<factories>
  <factory type="servlet"
    class="org.apache.avalon.excalibur.logger.factory.ServletTargetFactory"
  />
...
</factories>
<targets>
...
  <servlet...
  ....
  </servlet>
...
</targets>
....

!AsyncLogTargetFactory

The configuration of a AsyncLogTargetFactory accepts following attributes:

The AsyncLogTargetFactory expects an valid target factory configuration as its child element.

Example

The following configuration template configures a AsyncLogTarget

<async-target id="async-target-id" queue-size="15" priority="MIN">
  ... any-target-definition ...
</async-target>

!CocoonTargetFactory

The configuration of a CocoonTargetFactory accepts following attributes:

The configuration of a CocoonTargetFactory accepts following sub elements:

Example

The following configuration template configures a CocoonTarget, writing log events using the Cocoon's context root directory, as its base directory. (If Cocoon cannot access its context root directory Cocoon sets context-root to the sub-directory log of its work-dir.)

<cocoon id="core">
  <filename>${context-root}/WEB-INF/logs/core.log</filename>
  <format type="cocoon">
    %7.7{priority} %{time}   [%{category}] (%{uri}) 
    %{thread}/%{class:short}: %{message}\n%{throwable}
  </format>
  <append>true</append>
</cocoon>

Note if you change logKit.xconf, you must restart Tomcat

!DatagramTargetFactory

The configuration of a DatagramTargetFactory accepts following attributes:

The configuration of a DatagramTargetFactory accepts following sub elements:

!FileTarget

The configuration of a CocoonTargetFactory accepts following attributes:

The configuration of a CocoonTargetFactory accepts following sub elements:

Example

The following configuration template configures a FileTarget, writing logs to the file /var/tmp/log1.log.

<file>
  <filename>/var/tmp/log1.log</filename>
  <append>false</append>
  <format type="pattern">
    %7.7{priority} %{time} [%{category}] : %{message}\n%{throwable}
  </format>
</file>

JDBC!TargetFactory

The configuration of a JDBC!TargetFactory accepts following attributes:

The configuration of a JDBC!TargetFactory accepts following sub elements:

Setting normalized to true will use the NormalizedJDBCTarget, otherwise the DefaultJDBCTarget is used.

The DefaultJDBCTarget writes each log event into the table specified by the attribute name of element table.

The NormalizedJDBCTarget writes normalized value for category, and priority.

Subelements of table

Example

The following configuration template configures a JDBC target, writing to table cocoonlog. It uses the JDBC datasource jdbc/logdb. The category value of the log event is written to the column cat of table cocoonlog. The message value of the log event is written to the column msg of table cocoonlog. The priority value of the log event is written to the column prio of table cocoonlog. The time value of the log event is written to the column when of table cocoonlog. The context entry uri is writting to column uri.

<database>
  <datasource>jdbc/logdb</datasource>
  <normalized>false</normalized>
  <table name="cocoonlog">
    <category>cat</category>
    <message>mesg</message>
    <priority>prior</priority>
    <time>when</time>
    <context aux="uri">uri</context>
  </table>
</database>

JMS!TargetFactory

The configuration of a JMS!TargetFactory accepts following attributes:

The configuration of a JMS!TargetFactory accepts following sub elements:

!PriorityFilterTargetFactory

The configuration of a CocoonTargetFactory accepts following attributes:

The PriorityFilterTargetFactory expects an valid target factory configuration as its child element.

Example

The following configuration template configures a PriorityLevelTarget

<priority-target id="priority-target-id" log-level="ERROR">
  ... any-target-definition ...
</priority-target>

SMTPTargetFactory

The configuration of a SMTP!TargetFactory accepts following attributes:

The configuration of a SMTP!TargetFactory accepts following sub elements:

Note that the SMTP!TargetFactory requires a JavaMail Session object in the context, however, there is no way to place this object in the context when Cocoon starts up. To get around this, add a <session/> element into the target configuration. This causes a JavaMail Session object to be created and configured with the child elements of this element, although just an empty element worked fine for me. Here is a sample of an smtp log target:

<smtp id="core" context-key="session-context">
  <smtphost>smtp.mail.com</smtphost>
  <to>errors@apache.org</to>
  <from>cocoon@yourdomain.com</from>
  <subject>A log message</subject>
  <maximum-size>10</maximum-size>
  <session/>
</smtp>

!ServletTargetFactory

The configuration of a SocketTargetFactory accepts following attributes:

ServletContext object, by default the context-key attribute uses

The configuration of a SocketTargetFactory accepts following sub elements:

Example

The following configuration template configures a ServletTarget, expecting a ServletContext object available under context-key servlet-context.

<servlet id="servlet-target-id" context-key="servlet-context">
  <format type="pattern">
    %7.7{priority} %{time} [%{category}] : %{message}\n%{throwable}
  </format>
</servlet>

!SocketTargetFactory

The configuration of a SocketTargetFactory accepts following attributes:

The configuration of a SocketTargetFactory accepts following sub elements:

!StreamTargetFactory

The configuration of a StreamTargetFactory accepts following attributes:

The configuration of a StreamTargetFactory accepts following sub elements:

Example

The following configuration template configures a StreamTarget

<stream-target id="stream-target-id">
  <stream>System.out</stream>
  <format type="pattern">
    %7.7{priority} %{time} [%{category}] : %{message}\n%{throwable}
  </format>
</stream-target>

L!F5TargetFactory

The L!F5TargetFactory makes use of LogFactor5 - a Swing based GUI that leverages the power of log4j logging framework and provides developers with a sophisticated, feature-rich, logging interface for managing log messages.

More information can be found at the log4j docs.

See also "quick start" LogFactor5 instructions in LogFactorFiveHowto.

Use the following example configuration in order to use the GUI:

<logkit>
  <factories>
    ...
    <factory class="org.apache.avalon.excalibur.logger.factory.LF5TargetFactory" type="lf5"/>
    ...
  </factories>
  <targets>
    ...
    <lf5 id="core"/>  
  ...
  </targets>
  ...
</logkit>

Some notes:

Formatting

The following section describes the various formatting options available.

!PatternFormatter

This formater formats the LogEvents according to a input pattern string.

The format of each pattern element can be

%[+|-][#[.#]]{field:subformat} 

A simple example of a typical PatternFormatter format would be:

   %{time} %5.5{priority}[%-10.10{category}]: %{message}

This would produce a line like:

   1000928827905 DEBUG [     junit]: Sample message

The format string specifies that the logger should first print the time value of the log event without size restriction, then the priority of the log event with a minimum and maximum size of 5, then the category of the log event right justified with a minimum and maximum size of 10, followed by the message of the log event without any size restriction.

!ExtendedPatternFormatter

Formatter especially designed for debugging applications. This formatter extends the standard PatternFormatter to add two new possible expansions. These expansions are %{method} and %{thread}. In both cases the context map is first checked for values with specified key. This is to facilitate passing information about caller/thread when threads change (as in AsyncLogTarget). They then attempt to determine appropriate information dynamically.

!CocoonLogFormatter

An extended pattern formatter. New patterns are defined by this class are :

AsyncLogTarget.

Logging Rotation

The logging rotation feature is restricted to FileTargets, and logging targets derived from a FileTarget.

The rotation concept introduce a file strategy for defining the filename, orthogonally to the file strategy, a rotate strategy decides the condition of rotation.

Following file strategies are available

Following rotate strategies are available

Specifying the rotation settings is done in the target section of a log target.

Specify a revolving file strategy using 4 files, rotate if writing more than 10 MB logging date, or an hour of day in year has expired. The files have suffix like 000001

...
  <rotation type="revolving" init="1" max="4">
    <or>
      <size>10m</size>
      <date>DD:HH</date>
    </or>
  </rotation>
...

Specifying a unique file strategy, and rotate if more than 100 MB logging data has been written, or after 5 minutes of logging. The files have suffix like 200211261127.log.

<rotation type="unique" pattern="yyyyMMddHHmm" suffix=".log">
  <or>
    <size>100m</size>
    <time>00:05:00</time>
  </or>
</rotation>

A short date pattern summary

Specifying logkit.xconf

Defining the logkit.xconf file you want to use depends on the Cocoon environment.

...
<init-param>
<param-name>logkit-config</param-name>
<param-value>/WEB-INF/logkit.xconf</param-value>
</init-param>
...

java org.apache.Cocoon -k logkit.xconf ... 

, or

java org.apache.Cocoon --logKitconfig logkit.xconf ...

Examples

This snippet configures a file rotation, rotating the file every 5 minutes, or if the file size exceeds 2MB. The filename suffixes represents the date and time of file creation, eg. access.log20021209 151231.log.

<logkit>
  <factories>
    <factory type="file"
      class="org.apache.avalon.excalibur.logger.factory.FileTargetFactory"
    />
  </factories>
  <targets>
    <file>
      <filename>/tmp/access.log</filename>
      <format pattern="extended">
        %7.7{priority} %{time}   [%{category}]: %{message}\n%{throwable}
      </format>
      <append>false</append>
      <rotation type="unique" pattern="yyyyMMdd HHmmss" suffix=".log">
        <or>
          <size>2m</size>
          <time>00:05:00</time>
        </or>
      </rotation>
    </file>
  </targets>
  <categories>
    <category name="my-cat-1" log-level="DEBUG">
      <log-target id-ref="file"/>
    </category>
  </categories>
</logkit>

See Also

ConfiguringTheLogs (last edited 2009-09-20 23:40:34 by localhost)