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)
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
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.
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:
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>
....
|
The configuration of a AsyncLogTargetFactory accepts following attributes:
The AsyncLogTargetFactory expects an valid target factory configuration as its child element.
The following configuration template configures a AsyncLogTarget
<async-target id="async-target-id" queue-size="15" priority="MIN"> ... any-target-definition ... </async-target> |
The configuration of a CocoonTargetFactory accepts following attributes:
The configuration of a CocoonTargetFactory accepts following sub elements:
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>
|
The configuration of a DatagramTargetFactory accepts following attributes:
The configuration of a DatagramTargetFactory accepts following sub elements:
The configuration of a CocoonTargetFactory accepts following attributes:
The configuration of a CocoonTargetFactory accepts following sub elements:
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>
|
The configuration of a JDBCTargetFactory accepts following attributes:
The configuration of a JDBCTargetFactory 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
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>
|
The configuration of a JMSTargetFactory accepts following attributes:
The configuration of a JMSTargetFactory accepts following sub elements:
The configuration of a CocoonTargetFactory accepts following attributes:
The PriorityFilterTargetFactory expects an valid target factory configuration as its child element.
The following configuration template configures a PriorityLevelTarget
<priority-target id="priority-target-id" log-level="ERROR"> ... any-target-definition ... </priority-target> |
The configuration of a SMTPTargetFactory accepts following attributes:
The configuration of a SMTPTargetFactory accepts following sub elements:
Note that the SMTPTargetFactory 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> |
The configuration of a SocketTargetFactory accepts following attributes:
the context key servlet-context.
The configuration of a SocketTargetFactory accepts following sub elements:
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>
|
The configuration of a SocketTargetFactory accepts following attributes:
The configuration of a SocketTargetFactory accepts following sub elements:
The configuration of a StreamTargetFactory accepts following attributes:
The configuration of a StreamTargetFactory accepts following sub elements:
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>
|
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:
The following section describes the various formatting options available.
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.
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.
An extended pattern formatter. New patterns are defined by this class are :
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
yyyy-MM-dd.log
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
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> ... |
-k, or --logKitconfig, eg.java org.apache.Cocoon -k logkit.xconf ... |
, or
java org.apache.Cocoon --logKitconfig logkit.xconf ... |
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>
|