You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by do...@cocoon.apache.org on 2004/05/01 17:45:53 UTC
[Cocoon Wiki] Updated: ConfiguringTheLogs
Date: 2004-05-01T08:45:53
Editor: 80.129.137.61 <>
Wiki: Cocoon Wiki
Page: ConfiguringTheLogs
URL: http://wiki.apache.org/cocoon/ConfiguringTheLogs
no comment
Change Log:
------------------------------------------------------------------------------
@@ -1,535 +1,535 @@
-=== 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.
-== Basics ==
-
-Cocoon's logging mechanism introduces following keywords
-
- * Category is a symbolic name of some sort of logging output.
- * Target specifies a physical logging output
- * LogEvent created by a logging source, and routed via category resolution to a logging target, the logging sink
- * Formatter formats a logging event
-
-Following category names are declared in the cocoon.xconf file
-
- * sitemap
- * core.xml-parser
- * core.store.transient
- * core.store.janitor
- * core.xslt-processor
- * core.xpath-processor
- * core.url-factory
- * core.source-handler
- * core.program-generator
- * core.jsp-engine
- * core.i18n-bundles
- * core.xscript
- * core.language.java
- * core.language.js
- * core.classloader
- * core.markup.xsp
- * core.xml-serializer
- * core.xml-deserializer
- * core.monitor
- * core.resolver
-
-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
-
- * AsyncLogTargetFactory a virtual target, forwarding log events in a separate thread
- * CocoonTargetFactory an enhanced FileTarget, specially tailored for Cocoon needs
- * DatagramTargetFactory forwards logging events to datagram sink
- * FileTarget write logging events to file sink, offers rotation features
- * JDBCTargetFactory writes logging events to JDBC sink
- * JMSTargetFactory writes logging events to JMS sink
- * PriorityFilterTargetFactory a virtual target, filtering log events by its priority
- * SMTPTargetFactory forwards logging events as emails
- * ServletTargetFactory forwards formatted log events to the Servlets logging mechanism
- * SocketTargetFactory forwards logging events to socket sink
- * StreamTargetFactory writes logging events to a java.io.OutputStream, especially to System.out, and System.err
-== 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
- * Map a single category to a single logging target
- * Map more than one category to a single logging target
- * Map a child category to different logging target
- * Define a virtual logging target filtering logging events by priority, and map it to the logging target
-
-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:
-
- * type - defining the name of the element used for defining this log target instance
- * class - specifies the full qualified class name of the LogTargetFactory
-= 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:
- * id attribute specifies the target name, used in the category definition for referring to this target.
- * queue-size attribute for specifying the size of queue of log events.
- * priority the thread priority of the AsyncLogTarget thread, you may specify MIN, MAX, NORM, or a thread priority integer number, by default the priority is set to 1.
-
-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:
- * id attribute specifies the target name, used in the category definition for referring to this target.
-
-The configuration of a CocoonTargetFactory accepts following sub elements:
- * filename
- * format
- * append
- * rotation
-= 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:
- * id attribute specifies the target name, used in the category definition for referring to this target.
-
-The configuration of a DatagramTargetFactory accepts following sub elements:
-== FileTarget ==
-The configuration of a CocoonTargetFactory accepts following attributes:
- * id attribute specifies the target name, used in the category definition for referring to this target.
-
-The configuration of a CocoonTargetFactory accepts following sub elements:
- * filename
- * format
- * append
- * rotation
-= 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>
-}}}
-== JDBCTargetFactory ==
-The configuration of a JDBCTargetFactory accepts following attributes:
- * id attribute specifies the target name, used in the category definition for referring to this target.
-
-The configuration of a JDBCTargetFactory accepts following sub elements:
-
- * datasource specify the JNDI data source name
- * normalized specify true, or false.
- * table specify the name of the table using the attribute name
-
-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
- * category specify the column name as its value,
- * static specify the column name as its value, use the attribtue aux to specify the static value
- * context specify the column name as its value, use the attribute aux to specify the context entry name.
- * message specify the column name as its value
- * priority specify the column name as its value
- * time specify the column name as its value
- * rtime specify the column name as its value
- * throwable specify the column name as its value
- * hostname specify the column name as its value
-= 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>
-}}}
-== JMSTargetFactory ==
-The configuration of a JMSTargetFactory accepts following attributes:
- * id attribute specifies the target name, used in the category definition for referring to this target.
-
-The configuration of a JMSTargetFactory accepts following sub elements:
-== PriorityFilterTargetFactory ==
-
-The configuration of a CocoonTargetFactory accepts following attributes:
-
- * id attribute specifies the target name, used in the category definition for referring this target.
- * log-level attribute specifies the filter priority level. Logevents of this level or higher are passed further to the enclosed target factory configuration. The log-level sorted from lower priority to highest priority:
- * DEBUG priority defintion 5
- * INFO priority defintion 10
- * WARN priority defintion 15
- * ERROR priority defintion 20
- * FATAL ERROR priority defintion 25
-
-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 SMTPTargetFactory accepts following attributes:
- * id attribute specifies the target name, used in the category definition for referring to this target.
- * context-key attribute specifies the context key, storing the required JavaMail Session object, by default the context-key session-context is used.
-
-The configuration of a SMTPTargetFactory accepts following sub elements:
- * to one or more recipients addresses
- * from the sender address
- * subject the subject value
- * maximum-size defines the maximum numbers of logevents per mail
- * format
-== ServletTargetFactory ==
-The configuration of a SocketTargetFactory accepts following attributes:
- * id attribute specifies the target name, used in the category definition for referring to this target.
- * context-key attribute specifies the context key, storing the required
- ServletContext object, by default the context-key attribute uses
- the context key servlet-context.
-
-The configuration of a SocketTargetFactory accepts following sub elements:
- * format
-= 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:
- * id attribute specifies the target name, used in the category definition for referring to this target.
-
-The configuration of a SocketTargetFactory accepts following sub elements:
- * address - the attribute hostname specifies the destination host address, and the port attribute spefies the detination port number.
-== StreamTargetFactory ==
-The configuration of a StreamTargetFactory accepts following attributes:
- * id attribute specifies the target name, used in the category definition for referring to this target.
-
-The configuration of a StreamTargetFactory accepts following sub elements:
- * stream specifies the stream, you may use following stream sink names
- * System.out outputs log events to the System out stream
- * System.err outputs log events to the System err stream
-
- * format
-= 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>
-}}}
-== LF5TargetFactory ==
-The LF5TargetFactory 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 [http://jakarta.apache.org/log4j/docs/lf5/overview.html 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 GUI starts automatically after the first message is sent to this target
- * be aware that the default loglevel at logkit.xconf is ERROR
-== 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}
-}}}
-
- * The +|- indicates left or right justify.
- * The #.# indicates the minimum and maximum size of output. You may omit the values and the field will be formatted without size restriction. You may specify #, or #. to only define the minimum size. You may specify .# to only define the maximum size.
-
- * field indicates which field is to be output and must be one of properties of LogEvent. The following fields are currently supported:
- * category Category value of the logging event.
- * context Context value of the logging event.
- * message Message value of the logging event.
- * time Time value of the logging event.
- * rtime Relative time value of the logging event.
- * throwable Throwable value of the logging event.
- * priority Priority value of the logging event.
- * thread Name of the thread which logged the event.
- * subformat indicates a particular subformat to use on the specified field, and is currently only supported by:
- * context Specifies the context map parameter name.
- * time Specifies the pattern to be pass to SimpleDateFormat to format the time.
-
-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 :
- * class outputs the name of the class that has logged the
- message. The optional short subformat removes the
- package name. Warning : this pattern works only if formatting occurs in
- the same thread as the call to Logger, i.e. it won't work with
- AsyncLogTarget.
- * thread outputs the name of the current thread (first element
- on the context stack).
- * uri outputs the request URI.
-== 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
- * RevolvingFileStrategy write logging data to a fixed number of files
- * attribute type=revolving
- * attribute init specifies starting revolving index, by default it is 0
- * attribute max specifies ending revolving index, by default it is 10
-
- * UniqueFileStrategy, write logging data to unique named file
- * attribute type=unique
- * attribute pattern is SimpleDatePattern, by default it is {{{yyyy-MM-dd}}}
- * attribute suffix is optional, by default it is {{{.log}}}
-
-Following rotate strategies are available
- * RotateStrategyByDate - rotate if the current date, is different from the starting date of logging, or the latest rotation, comparing is performed via formatting both date using the specifed SimpleDateFormat pattern
- * RotateStrategyByTime - rotate after logging a period of time, specifed as SimpleDateFormat value of the format HH:mm:SS
- * RotateStrategyBySize - rotate if size of logging data exceeds the specified size
- * OrRotateStrategy - combining a rotate strategy, rotate if one of the enclosed rotate strategy wants to trigger a rotation
-
-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
- * yyyy Year
- * MM Month, MMM Month by Name
- * DD Day in year
- * dd Day in month
- * HH Hour in day 0-23
- * kk Hour in day 1-24
- * mm Minute
- * ss Second in minute
- * SSS Milliseconds
-== Specifying logkit.xconf ==
-
-Defining the logkit.xconf file you want to use depends on the Cocoon environment.
-
- * Servlet environment, you specify a servlet init parameter logkit config, eg.
-{{{
-...
-<init-param>
-<param-name>logkit-config</param-name>
-<param-value>/WEB-INF/logkit.xconf</param-value>
-</init-param>
-...
-}}}
-
- * Commandline environment, specify the option {{{-k}}}, or {{{--logKitconfig}}}, eg.
-{{{
-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 ==
- * LogFactorFiveHowto
- * ExploringTheLogs
- * [http://jakarta.apache.org/avalon/logkit/index.html AvalonLogKit]
- * [http://jakarta.apache.org/avalon/excalibur/logger/index.html ExcaliburLogger]
+=== 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.
+== Basics ==
+
+Cocoon's logging mechanism introduces following keywords
+
+ * Category is a symbolic name of some sort of logging output.
+ * Target specifies a physical logging output
+ * LogEvent created by a logging source, and routed via category resolution to a logging target, the logging sink
+ * Formatter formats a logging event
+
+Following category names are declared in the cocoon.xconf file
+
+ * sitemap
+ * core.xml-parser
+ * core.store.transient
+ * core.store.janitor
+ * core.xslt-processor
+ * core.xpath-processor
+ * core.url-factory
+ * core.source-handler
+ * core.program-generator
+ * core.jsp-engine
+ * core.i18n-bundles
+ * core.xscript
+ * core.language.java
+ * core.language.js
+ * core.classloader
+ * core.markup.xsp
+ * core.xml-serializer
+ * core.xml-deserializer
+ * core.monitor
+ * core.resolver
+
+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
+
+ * AsyncLogTargetFactory a virtual target, forwarding log events in a separate thread
+ * CocoonTargetFactory an enhanced FileTarget, specially tailored for Cocoon needs
+ * DatagramTargetFactory forwards logging events to datagram sink
+ * FileTarget write logging events to file sink, offers rotation features
+ * JDBCTargetFactory writes logging events to JDBC sink
+ * JMSTargetFactory writes logging events to JMS sink
+ * PriorityFilterTargetFactory a virtual target, filtering log events by its priority
+ * SMTPTargetFactory forwards logging events as emails
+ * ServletTargetFactory forwards formatted log events to the Servlets logging mechanism
+ * SocketTargetFactory forwards logging events to socket sink
+ * StreamTargetFactory writes logging events to a java.io.OutputStream, especially to System.out, and System.err
+== 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 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
+ * Map a single category to a single logging target
+ * Map more than one category to a single logging target
+ * Map a child category to different logging target
+ * Define a virtual logging target filtering logging events by priority, and map it to the logging target
+
+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:
+
+ * type - defining the name of the element used for defining this log target instance
+ * class - specifies the full qualified class name of the LogTargetFactory
+= 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:
+ * id attribute specifies the target name, used in the category definition for referring to this target.
+ * queue-size attribute for specifying the size of queue of log events.
+ * priority the thread priority of the AsyncLogTarget thread, you may specify MIN, MAX, NORM, or a thread priority integer number, by default the priority is set to 1.
+
+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:
+ * id attribute specifies the target name, used in the category definition for referring to this target.
+
+The configuration of a CocoonTargetFactory accepts following sub elements:
+ * filename
+ * format
+ * append
+ * rotation
+= 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:
+ * id attribute specifies the target name, used in the category definition for referring to this target.
+
+The configuration of a DatagramTargetFactory accepts following sub elements:
+== FileTarget ==
+The configuration of a CocoonTargetFactory accepts following attributes:
+ * id attribute specifies the target name, used in the category definition for referring to this target.
+
+The configuration of a CocoonTargetFactory accepts following sub elements:
+ * filename
+ * format
+ * append
+ * rotation
+= 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>
+}}}
+== JDBCTargetFactory ==
+The configuration of a JDBCTargetFactory accepts following attributes:
+ * id attribute specifies the target name, used in the category definition for referring to this target.
+
+The configuration of a JDBCTargetFactory accepts following sub elements:
+
+ * datasource specify the JNDI data source name
+ * normalized specify true, or false.
+ * table specify the name of the table using the attribute name
+
+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
+ * category specify the column name as its value,
+ * static specify the column name as its value, use the attribtue aux to specify the static value
+ * context specify the column name as its value, use the attribute aux to specify the context entry name.
+ * message specify the column name as its value
+ * priority specify the column name as its value
+ * time specify the column name as its value
+ * rtime specify the column name as its value
+ * throwable specify the column name as its value
+ * hostname specify the column name as its value
+= 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>
+}}}
+== JMSTargetFactory ==
+The configuration of a JMSTargetFactory accepts following attributes:
+ * id attribute specifies the target name, used in the category definition for referring to this target.
+
+The configuration of a JMSTargetFactory accepts following sub elements:
+== PriorityFilterTargetFactory ==
+
+The configuration of a CocoonTargetFactory accepts following attributes:
+
+ * id attribute specifies the target name, used in the category definition for referring this target.
+ * log-level attribute specifies the filter priority level. Logevents of this level or higher are passed further to the enclosed target factory configuration. The log-level sorted from lower priority to highest priority:
+ * DEBUG priority defintion 5
+ * INFO priority defintion 10
+ * WARN priority defintion 15
+ * ERROR priority defintion 20
+ * FATAL ERROR priority defintion 25
+
+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 SMTPTargetFactory accepts following attributes:
+ * id attribute specifies the target name, used in the category definition for referring to this target.
+ * context-key attribute specifies the context key, storing the required JavaMail Session object, by default the context-key session-context is used.
+
+The configuration of a SMTPTargetFactory accepts following sub elements:
+ * to one or more recipients addresses
+ * from the sender address
+ * subject the subject value
+ * maximum-size defines the maximum numbers of logevents per mail
+ * format
+== ServletTargetFactory ==
+The configuration of a SocketTargetFactory accepts following attributes:
+ * id attribute specifies the target name, used in the category definition for referring to this target.
+ * context-key attribute specifies the context key, storing the required
+ ServletContext object, by default the context-key attribute uses
+ the context key servlet-context.
+
+The configuration of a SocketTargetFactory accepts following sub elements:
+ * format
+= 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:
+ * id attribute specifies the target name, used in the category definition for referring to this target.
+
+The configuration of a SocketTargetFactory accepts following sub elements:
+ * address - the attribute hostname specifies the destination host address, and the port attribute spefies the detination port number.
+== StreamTargetFactory ==
+The configuration of a StreamTargetFactory accepts following attributes:
+ * id attribute specifies the target name, used in the category definition for referring to this target.
+
+The configuration of a StreamTargetFactory accepts following sub elements:
+ * stream specifies the stream, you may use following stream sink names
+ * System.out outputs log events to the System out stream
+ * System.err outputs log events to the System err stream
+
+ * format
+= 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>
+}}}
+== LF5TargetFactory ==
+The LF5TargetFactory 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 [http://jakarta.apache.org/log4j/docs/lf5/overview.html 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 GUI starts automatically after the first message is sent to this target
+ * be aware that the default loglevel at logkit.xconf is ERROR
+== 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}
+}}}
+
+ * The +|- indicates left or right justify.
+ * The #.# indicates the minimum and maximum size of output. You may omit the values and the field will be formatted without size restriction. You may specify #, or #. to only define the minimum size. You may specify .# to only define the maximum size.
+
+ * field indicates which field is to be output and must be one of properties of LogEvent. The following fields are currently supported:
+ * category Category value of the logging event.
+ * context Context value of the logging event.
+ * message Message value of the logging event.
+ * time Time value of the logging event.
+ * rtime Relative time value of the logging event.
+ * throwable Throwable value of the logging event.
+ * priority Priority value of the logging event.
+ * thread Name of the thread which logged the event.
+ * subformat indicates a particular subformat to use on the specified field, and is currently only supported by:
+ * context Specifies the context map parameter name.
+ * time Specifies the pattern to be pass to SimpleDateFormat to format the time.
+
+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 :
+ * class outputs the name of the class that has logged the
+ message. The optional short subformat removes the
+ package name. Warning : this pattern works only if formatting occurs in
+ the same thread as the call to Logger, i.e. it won't work with
+ AsyncLogTarget.
+ * thread outputs the name of the current thread (first element
+ on the context stack).
+ * uri outputs the request URI.
+== 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
+ * RevolvingFileStrategy write logging data to a fixed number of files
+ * attribute type=revolving
+ * attribute init specifies starting revolving index, by default it is 0
+ * attribute max specifies ending revolving index, by default it is 10
+
+ * UniqueFileStrategy, write logging data to unique named file
+ * attribute type=unique
+ * attribute pattern is SimpleDatePattern, by default it is {{{yyyy-MM-dd}}}
+ * attribute suffix is optional, by default it is {{{.log}}}
+
+Following rotate strategies are available
+ * RotateStrategyByDate - rotate if the current date, is different from the starting date of logging, or the latest rotation, comparing is performed via formatting both date using the specifed SimpleDateFormat pattern
+ * RotateStrategyByTime - rotate after logging a period of time, specifed as SimpleDateFormat value of the format HH:mm:SS
+ * RotateStrategyBySize - rotate if size of logging data exceeds the specified size
+ * OrRotateStrategy - combining a rotate strategy, rotate if one of the enclosed rotate strategy wants to trigger a rotation
+
+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
+ * yyyy Year
+ * MM Month, MMM Month by Name
+ * DD Day in year
+ * dd Day in month
+ * HH Hour in day 0-23
+ * kk Hour in day 1-24
+ * mm Minute
+ * ss Second in minute
+ * SSS Milliseconds
+== Specifying logkit.xconf ==
+
+Defining the logkit.xconf file you want to use depends on the Cocoon environment.
+
+ * Servlet environment, you specify a servlet init parameter logkit config, eg.
+{{{
+...
+<init-param>
+<param-name>logkit-config</param-name>
+<param-value>/WEB-INF/logkit.xconf</param-value>
+</init-param>
+...
+}}}
+
+ * Commandline environment, specify the option {{{-k}}}, or {{{--logKitconfig}}}, eg.
+{{{
+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 ==
+ * LogFactorFiveHowto
+ * ExploringTheLogs
+ * [http://jakarta.apache.org/avalon/logkit/index.html AvalonLogKit]
+ * [http://jakarta.apache.org/avalon/excalibur/logger/index.html ExcaliburLogger]